企业官网建设流程全解析

ha_xiaomi_home：3步把米家设备接进Home Assistant的完整教程

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home

小米家电散落在米家App里？想集中管理，却没有官方入口

空气净化器还在米家App里调风速，智能灯你想拉进Home Assistant的自动化，扫地机的数据想进仪表盘，找了一圈社区方案，稳定性全看运气。小米官方的答案是ha_xiaomi_home：由小米官方维护的米家集成，直接把米家设备接入 Home Assistant，本地直连、云端两种控制通道都支持，现有设备不用换，米家App里的配置也不用动。

先盘清楚：它替你解决了什么

一句话定位：小米米家设备通往 Home Assistant 的官方桥梁。

• 官方出品：集成和它调用的云端接口都由小米官方提供，不用赌第三方集成的存活率。
• 本地/云端双通道：局域网里有中枢网关就走本地直连，没有就走小米云，两边都兜得住。
• 状态主动推送：设备属性一变就实时推到 Home Assistant，不靠定时轮询，状态不滞后。
• 实体自动长出来：它读每台设备的 MIoT-Spec-V2 功能描述，自动生成 switch、sensor、climate 等实体，不用手工映射。
• 多账号汇到一处：多个小米账号的米家设备可以导入同一个 Home Assistant 实例，一个面板统一管理。

这几点基本决定了你后面配置顺不顺手。看完这段，你应该更关心怎么把它跑起来。

三步跑通：装组件、登录、勾选家庭

第 1 步，装组件。在 Home Assistant 所在服务器上操作，前提版本是 Core 2024.4.4 及以上、Operating System 13.0 及以上：

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 Broker（可以理解成一个消息中转站）上订阅设备消息通道，设备属性变化或事件触发时发出properties_changed、event等上行消息，由 Broker 实时推给集成；整个配置过程只在初始时向云端查一次全部属性，之后不再轮询，对云端的访问压力很小。控制指令则走反方向，通过 HTTP 接口把set_properties、action消息发到云端，再由云端转发给设备。

指令怎么不出局域网：中枢网关当"居委会"

再打个比方：家里的事在居委会就能办，不用专门跑区里的大厅。小米中枢网关内置了一个标准 MQTT Broker（需固件 3.3.0_0023 及以上），集成直接向它订阅设备消息，控制指令也发布到这个 Broker，由网关转发给设备，全程不出局域网。如果本地通道和云端通道同时可用，中枢网关的本地控制优先。

实体为什么各不相同：一份出厂说明书

每台 MIoT 设备都带一份 MIoT-Spec-V2 描述，相当于出厂说明书，写清楚它有哪些属性、事件、方法。集成照着说明书匹配内置映射规则：可写的布尔属性变 switch，不可读写的变 sensor，事件变 event，方法变 button 或 notify——这就是不同设备长出不一样实体组合的原因，也是后面定制实体的入口。

一句话记住：状态靠通道推，指令走云端或网关，实体靠说明书长出来。

答疑时间：这几个坑先帮你填上 🔧

• 登录了但设备不显示→ 蓝牙、红外和部分虚拟设备暂不支持，或登录时选错了用户地区 → 先在米家App确认设备已绑定该账号，再在配置流程里选对地区重新导入。
• 点开关要等半天→ 局域网里没有中枢网关，指令只能绕道小米云 → 加装中枢网关后本地直连自动优先；配置里的"局域网控制"开关不建议拿来顶替，官方文档明确标注它可能引发异常。
• 实体名是英文，或者一堆没用的实体→ 云端翻译不全、冗余的 spec 实例没被过滤 → 改 specs 目录下的multi_lang.json和spec_filter.yaml，再到集成配置里点"更新实体转换规则"生效。
• 想同时管两个小米账号→ 一个账号一次只导入一套家庭 → 在 Xiaomi Home 配置页选"添加中枢"，再登录另一个账号即可。
• 想看看内部在干嘛→ 把custom_components.xiaomi_home的日志级别调成 debug，推送和控制过程都能在日志里看到。

想进一步查 MIoT-Spec-V2 到实体的完整转换表和过滤规则，可以看仓库里的中文文档 doc/README_zh.md，映射规则文件集中在 custom_components/xiaomi_home/miot/specs/。

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home