3步把小米设备搬进 Home Assistant：米家集成同步配置完全手册
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
米家集成（Xiaomi Home）是小米官方为 Home Assistant 提供的智能家居组件，它把你在米家 APP 里的智能灯、空调、传感器变成 Home Assistant 里可读取、可控制的实体。下面带你把「跨区域同步」和「设备延迟」这两件事一次理顺。
一个真实的早晨
先看三个具体的使用场景，你会更清楚这个集成在解决什么：
- 你走进客厅，人形传感器上报了状态，同一套 Home Assistant 里的灯光实体跟着变化，卧室面板上无需刷新就能看到。
- 厨房的烟感或温湿度传感器触发了事件，联动脚本自动打开客厅的灯，整个过程发生在同一个系统内。
- 家里不同房间、甚至不同地区的设备，最终都汇总到同一个界面里，你在一张看板上管理它们。
这些之所以能成立，核心在于集成不是靠反复去云端「问」设备，而是设备主动把变化推过来。
落地实操：四步完成配置
先做配置，再回头看它为什么快。
- 在 Home Assistant 的「设置 > 设备与服务 > 添加集成」里搜索 Xiaomi Home，用小米账号登录。登录区域要选对，可在米家 APP 的「个人资料 > 附加设置 > 关于小米家庭」里确认你所在地区。
- 登录后会弹出「选择家庭与设备」，勾选要导入的米家家庭，该家庭下的设备会被一并拉进来。多个账号可之后在集成页面继续添加。
- 在「配置选项」里调整区域规则。
area_name_rule这一项决定设备落到哪个区域，常见取值为不分配、按家庭名称、按房间名称三种，默认跟房间走。 - 如果需要本地控制，再配置网络检测地址，并把 Home Assistant 与小米中枢网关放到同一局域网。
底层机制：两条链路各管一摊
理解「快」和「稳」，关键是把两条链路分开看。
云端链路：订阅而非轮询
集成通过小米云的 MQTT Broker 订阅你关注的设备。设备属性一变或产生事件，设备向云发上行消息，Broker 再把订阅到的消息推给集成。好处是不用轮询：只在配置完成时向云端查一次全部属性，之后靠推送。云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个机房，不同地区数据相互隔离，所以要按所在地区登录才能导入对应设备。
本地链路：绕开云端
有小米中枢网关时，集成走它内置的 MQTT Broker：设备上行消息先到网关，Broker 推给集成；控制指令也由集成发布到 Broker，经网关转发给设备。全程不出局域网，延迟自然低。相关逻辑分别见 miot_cloud.py 与 miot_lan.py。
避坑与排障：常见现象对一下
| 现象 | 可能原因 | 对策 |
|---|---|---|
| 设备响应偏慢 | 走了云端链路 | 让 HA 与中枢网关同网段，优先本地控制 |
| 设备没导入 | 登录区域选错 | 按所在地区重新登录对应机房 |
| 网络判断不稳 | 检测地址不可达 | 在network_detect_addr配多个可用检测地址 |
| 实体不符合预期 | 转换规则未命中 | 检查设备是否缺必选服务、属性、事件 |
网络检测的具体处理在 miot_network.py 中实现，配好多个检测地址能降低单点抖动带来的误判。
进阶定制：让实体更合心意
当默认转换不满足你时，有两个文件值得上手：
- spec_filter.yaml 控制哪些 MIoT-Spec-V2 实例会被转成 Home Assistant 实体，用它来收敛或放宽实体清单。
- multi_lang.json 管理设备名在不同语言下的显示。集成内置 13 种界面语言，从简体中文到德语、俄语都能选，改完名字在各语言界面里会更统一。
这些改动都作用于「规格到实体」的转换层，不会改变上面的两条链路本身。
快速问答
延迟主要卡在哪一步？多数情况卡在云端往返。把 HA 与中枢网关放进同一局域网，改用本地链路，体感会明显不同。
多个地区的设备能放一起吗？可以。不同地区的米家设备能添加到同一个 Home Assistant 区域，但登录时仍要选对对应地区。
实体怎么对不上我想要的？先看设备是否缺少必选的服务、属性或事件，再用spec_filter.yaml调整转换范围，用multi_lang.json统一命名。
行动清单
- 确认登录区域与你的米家地区一致，再开始导入设备。
- 把 Home Assistant 与小米中枢网关放到同一局域网，优先走本地控制。
- 在
network_detect_addr里配置多个网络检测地址，提升连接判断稳定性。 - 用
spec_filter.yaml和multi_lang.json收敛实体、统一命名，让界面更清爽。 - 遇到延迟时，先区分问题出在云端链路还是本地链路，再对症下药。
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
