三步把小米设备搬进 Home Assistant官方 Xiaomi Home 集成完整指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home家里有一堆小米设备却想在 Home Assistant 里编排自动化你可能已经发现HA 里根本找不到这些设备的影子。这时就该请出小米官方支持的集成 ha_xiaomi_home 了——它把米家设备接进 Home Assistant云端控制和局域网本地控制都能用登录、选设备、建实体全程在 HA 界面里点完。痛点你的小米设备在 Home Assistant 里隐身想象一下这个场景你想让窗帘开到位后自动开灯结果打开 HA 才发现——窗帘、灯、空气净化器这些米家设备一个都不在实体列表里。问题不在你的操作而在 HA 本身没有米家的入口。ha_xiaomi_home 就是补这块短板的官方集成它帮你做三件事用你的小米账号把设备搬进 HA不用手写任何配置文件设备状态变化时自动同步不用你轮询刷新把米家设备的每个功能翻译成 HA 认识的实体灯是 light、开关是 switch、空调是 climate全程只需要一个小米账号下面开始动手。如何五分钟把小米设备搬进 Home Assistant1. 先确认版本够不够集成对 HA 的版本有要求不满足先升级Core 版本 ≥ 2024.4.4Operating System 版本 ≥ 13.02. 克隆仓库并运行安装脚本进入 HA 的 config 目录执行cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /configinstall.sh 会做两件事删掉旧版本再把 custom_components/xiaomi_home 整个文件夹复制到config/custom_components下。不想用 git 的话也有两条备选路在 HACS 里搜索Xiaomi Home一键安装或者用 Samba/FTP 手动把custom_components/xiaomi_home文件夹拷到 HA 的custom_components目录。3. 重启 HA登录账号建实体重启 Home Assistant打开设置 → 设备与服务 → 添加集成搜索Xiaomi Home点击登录用小米账号完成授权在弹出的选择家庭与设备对话框里勾选要导入的家庭该家庭下的设备就全部进来了之后想锁定某个版本回到仓库目录执行git checkout v0.4.7再跑一次./install.sh /config即可。能力速览这个集成能覆盖哪些场景云端与本地双通道控制没有特别配置时控制指令默认走小米云。如果你家里有小米中枢网关固件 3.3.0_0023 及以上或者买了内置中枢网关功能的米家设备软件 0.8.9 及以上就能启用本地控制指令在局域网里直接到设备。注意中枢网关目前仅在中国大陆发售。其他地区可考虑开启小米局域网控制但它只能控 IP 设备且官方明确不建议使用后面避坑部分细说。设备覆盖面多账号、多地区都能收支持大部分米家设备品类只有蓝牙、红外、虚拟设备三类不在支持范围导入后会自动生成对应实体照明、开关、空调、传感器、风扇、加湿器、扫地机、窗帘、媒体播放器电视盒子 v0.4.6 起支持、热水器以及 number/select/text/button 等多个小米账号可以依次添加集成页 → 添加中枢不同账号、不同地区的设备都能放进同一个区域云服务已部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个地区机房配置时选自己的地区即可13 种语言实体名还能自己改配置流程界面支持简体中文、繁体中文、英文、西班牙文、俄文、法文、德文、日文、意大利文、荷兰文、葡萄牙文、巴西葡萄牙文、土耳其文共 13 种语言。实体显示名会从小米云拉取厂商的多语言文件嫌名字不好听可以编辑本地的 multi_lang.json 覆盖翻译它的优先级比云端文件高。机制详解双模式控制到底怎么工作 这一节用大白话讲清楚两种控制通道的原理看懂后你就知道本地控制和局域网控制为什么是两码事。云模式不轮询消息推送到家云端模式下集成在小米云的 MQTT Broker可以理解为云端的消息中转站上订阅你关心的设备。设备属性一变或发生事件云端立刻把消息推给集成所以状态同步是实时的而不是集成反复去问你现在什么状态。好处是集成只在配置完成时向云端查询一次全部设备属性之后几乎不产生查询压力。下发指令时则走小米云的 HTTP 接口设备收到下行消息后执行并应答。具体实现可以看 miot_cloud.py 和消息总线 miot_mips.py。本地模式中枢网关自带一个消息中转站本地模式的原理和云模式几乎一样只是中转站从云端搬到了你家小米中枢网关内部内置了一个标准 MQTT Broker实现了完整的订阅-发布机制。上行设备属性变化或事件发生时消息发给中枢网关由网关转发给 HA 里的集成下行集成要控制设备时把指令发布到网关的 Broker网关再转发给设备整条链路不经过互联网响应快、也更省隐私。彩蛋设备功能是怎么变成实体的集成依据小米的 MIoT-Spec-V2 协议小米给设备写的功能说明书生成实体规则大致是可写的布尔属性 → 开关只读属性 → 传感器带取值列表的可写属性 → 下拉选择设备事件 → Event 实体比如无线开关的长按设备方法 → 无参数的是按钮有参数的是通知类实体可传[Hello, true]这样的参数列表不想生成某个功能的实体在 spec_filter.yaml 里按设备 URN 过滤掉对应服务或属性即可更多细节见 中文 README 的映射关系章节。避坑指南4 个踩坑高发场景 官方文档里藏着不少默认不会发生的前提条件提前看一遍能省不少排查时间。场景一想开本地控制发现没生效现象配置里找不到本地选项或者开了也没变化。解法本地控制的硬前提是你得有小米中枢网关固件 ≥ 3.3.0_0023或带内置中枢网关的米家设备软件 ≥ 0.8.9且设备要能被发现集成通过 mDNS 的 zeroconf 发现见 miot_mdns.py。另外中枢网关仅中国大陆有售其他地区只能走云模式。场景二改了 multi_lang.json实体名字纹丝不动现象编辑完 specs 目录 下的多语言或过滤文件重启 HA 后实体名还是旧的。解法改文件不会自动生效。要到设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置里点一次更新实体转换规则改动才会被读取。场景三图省事开了小米局域网控制设备反而抽风现象部分设备偶发无响应、状态异常。解法官方 README 明确写了不建议启用这个功能——它只能控同一局域网内的 IP 设备WiFi/网线连路由器的蓝牙 Mesh、ZigBee 设备统统不管还可能引发异常。而且只要局域网里有中枢网关这个功能根本不会生效。所以有中枢网关走本地模式没有就安心用云模式。场景四担心账号安全问题现象听说集成登录小米账号怕密码存在 HA 里。解法集成走的是 OAuth 2.0 授权流程不保存你的小米账号密码。但要注意登录成功后的用户信息设备信息、证书、token会明文存在 HA 的配置文件里所以配置文件本身的保管很重要。万一怀疑 token 泄露可以去 米家 APP → 我的 → 账号管理 → 应用授权把 Xiaomi Home (Home Assistant Integration) 的授权撤掉重新登录即可。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考