ha_xiaomi_home 米家集成指南：10 分钟把小米设备搬进 Home Assistant
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
你手头有小米的空气净化器、智能灯、扫地机，想把它们搬进 Home Assistant，却发现没有官方入口，只能翻社区的各种野路子插件，稳定性全看运气。ha_xiaomi_home 就是小米官方支持的米家集成：现有米家设备直接接入 Home Assistant，本地直连和小米云两条路都走得通，不用换设备，也不用改你原来的用法。
这篇文章带你 10 分钟跑通它，顺带把内部机制讲明白。
小米设备进不了 Home Assistant：为什么选 ha_xiaomi_home
一句话定位：它是米家和 Home Assistant 之间那扇官方开的门。
过去小米设备只有两条路：要么开着米家 App 手动点，要么找社区第三方插件。前一条路进不了 Home Assistant 的自动化，后一条路质量看作者的手艺，更新也没人保证。
ha_xiaomi_home 直接解决这个尴尬：用你的小米账号读取设备列表和功能规格，自动生成对应的 Home Assistant 实体，导入之后就能长期稳定地用下去。
能力到底覆盖多少？先盘一遍再动手。
先盘家底：这个米家集成能为你做哪 5 件事
一句话定位：记住这 5 条，就能判断它适不适合你的场景。
- 多账号统一管：多个小米账号的设备能并进同一个 Home Assistant 实例，甚至放进同一个区域。
- 本地云端双路：局域网里有中枢网关就走本地直连，没有就走小米云，两头都兜得住。
- 状态主动推：不做周期性查询，属性一变立刻送到集成手里，看板不滞后。
- 实体自己长出来：集成读取每台设备的 MIoT-Spec-V2 规格，自动产出 switch、sensor、climate 等实体，不用你手工映射。
- 实体名 13 种语言：设备属性名自动翻译，中文界面开箱就是中文。
能力齐了，上手要花多少功夫？三步的事。
跑通只需三步：拿代码、登录、选家庭
一句话定位：版本要求是 Core 2024.4.4 以上、Operating System 13.0 以上，然后跟着走。
第 1 步，拿代码。在 Home Assistant 所在的服务器上克隆仓库并执行安装脚本：
cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config预期结果：集成目录落进custom_components，重启 Home Assistant 后安装完成。
第 2 步，登录。进界面设置 → 设备与服务 → 添加集成，搜索Xiaomi Home点下一步，会跳到小米账号登录页。登录走 OAuth 2.0，你的密码不会落进 Home Assistant。这里有个关键点：要选对账号所在地区，中国、欧洲、美国的设备存在不同机房的小米云上，选错了就导不出设备。
第 3 步，选家庭。登录成功后弹出"选择家庭与设备"，勾选要接入的米家家庭，这个家庭下的设备会全部导入。刷新设备列表，净化器和灯应该已经在实体列表里待命了。
以后想升级，在克隆目录拉取新 Tag 再跑一次脚本即可：
cd config/ha_xiaomi_home git fetch git checkout <想切到的版本tag> ./install.sh /path/to/homeassistant/config跑通了，你也许会问：设备的状态到底从哪儿来？
设备状态从哪来：MQTT 推送，不做轮询
一句话定位：状态更新是"送到门口"的，它从不替你跑腿去问。
你可以把这事理解成医院病房的呼叫系统：每张床头都有呼叫按钮，病人一按，护士站的呼叫屏立刻亮起来，护士不用每隔五分钟去巡房看一遍。
说白了，集成在小米云的 MQTT Broker 上订阅了设备消息通道，设备属性变化或事件发生时会发出 properties_changed、event 这类上行消息，Broker 实时转给集成。配置完成时它只向云端问一次全部属性，之后就不再重复查询。控制指令则走反方向：集成通过 HTTP API 发 set_properties 或 action 消息，云端再转给设备。
但这样有个短板：指令绕了云端一圈，总会多一跳。能不能让它快起来？
让控制不出局域网：中枢网关本地直连
一句话定位：家里有中枢网关，消息就在屋内直接走，不出局域网。
你可以把它理解成楼内对讲机：打电话的人和接电话的人住在同一栋楼，信号走楼内对讲线就行，不需要绕到市话交换机再回来。
说白了，小米中枢网关（固件 3.3.0_0023 及以上）内置了一个标准 MQTT Broker。集成直接向网关订阅设备消息，控制指令发布到 Broker 后由网关转给设备，全程不出局域网。两条通道同时具备时，中枢网关的本地控制自动优先。
通道讲清了，那每台设备为什么生成不同的实体组合？
不同设备生成不同实体：MIoT-Spec-V2 转换规则
一句话定位：每台设备自带一份标准"设备清单"，集成按转换表照着造实体。
你可以把它理解成大家电附带的说明书：上面写清了这台机器有哪些旋钮、每个旋钮干什么、还有哪些指示灯。MIoT-Spec-V2 就是这份说明书，列出设备的服务、属性、事件和方法。
集成拿着规格去匹配内置的转换表：可写的布尔属性变 switch，只读属性变 sensor，事件变 event 实体，无参方法变 button，带参方法变 notify。同一套规则套在不同设备上，长出来的实体自然各不相同——想定制实体名或过滤冗余实体，这也是入口。完整的转换表和过滤规则，官方中文文档里都有。
跑起来之后，总会遇到些问题。一次修完。
排障与进阶：常见坑一次修完
一句话定位：全部按"现象 → 原因 → 解法"组织，照着解法操作就行。
- 登录后设备不显示→ 蓝牙、红外和部分虚拟设备暂不支持，或登录时选错了地区 → 先在米家 App 里确认设备已绑定该账号，再在配置流程中重选地区重新导入。
- 控制响应偏慢→ 局域网里没有中枢网关，指令只能绕道小米云 → 加装中枢网关后本地直连自动优先；配置里的"局域网控制"开关不建议拿来顶替，官方文档明确标注它可能引发异常。
- 实体名是英文、或一堆没用的实体→ 云端翻译不全，冗余的 spec 实例默认没被过滤 → 修改 specs 目录下的 multi_lang.json 和 spec_filter.yaml，再到集成配置里点"更新实体转换规则"生效。
- 想同时管两个小米账号→ 目前只导入过一套家庭 → 在 Xiaomi Home 配置页选"添加中枢"再登录一次。
- 想看内部在干嘛→ 默认日志级别信息太少 → 把
custom_components.xiaomi_home的日志级别调成 debug，订阅、推送、下发的过程会原样打印出来。
再往下想深挖 Spec 转换与过滤的细节，去读 custom_components/xiaomi_home/miot/ 核心目录和 doc 下的中文文档就够用了。到这里，你的小米设备已经全部就位，可以开始搭自动化了。
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
