企业官网建设流程全解析

一条命令把米家接入Home Assistant：小米官方集成ha_xiaomi_home新手完整指南

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

米家买的灯、净化器、扫地机都归米家 App 管，可你想把它们拉进 Home Assistant 的自动化里，却找不到正规入口。问题的答案就是 ha_xiaomi_home：小米官方支持的集成组件，直接把米家设备接入 Home Assistant，本地、云端两条控制通道都覆盖，现有设备不用换。

能力速览：小米官方集成能帮你做哪些事

• 多账号设备统一管理：多个小米账号下的米家设备可导入同一个 Home Assistant 实例，一起调度。
• 本地/云端双通道：局域网有中枢网关就本地直连，没有就走小米云，两边都能兜住。
• 状态订阅推送：设备属性一变就实时推过来，不轮询、不滞后。
• 实体自动生成：读每台设备的 MIoT-Spec-V2（小米 IoT 平台的设备功能描述标准）自动转成 switch、sensor、climate 等实体，不用手工映射。
• 实体名多语言：属性名自动翻译，支持 13 种语言，中文界面开箱即中文。

先把整套流程跑通，再回头拆它的内部机制，这样理解起来最顺。

安装前的版本检查

动手前先确认两项前置条件：

• Home Assistant Core 2024.4.4 及以上
• Operating System 13.0 及以上

在 HA 界面底部就能看到当前版本号；不满足就先升级系统，否则后续步骤会在安装时卡住。版本没问题，就可以把代码拉到服务器上了。

一条命令跑起来：克隆代码并执行安装脚本

在 Home Assistant 所在服务器的终端里，克隆仓库进 config 目录，再运行安装脚本。脚本做的事很单纯：把custom_components/xiaomi_home组件复制到你的配置目录里。

cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/your/config

跑完终端会提示安装完成，接着重启 Home Assistant。重启后在集成列表里能看到Xiaomi Home，就说明装好了。

以后想升级，切到目标 Tag 再跑一次脚本即可：

cd config/ha_xiaomi_home git fetch git checkout <你要切换的tag> ./install.sh /path/to/your/config

小米账号登录与家庭设备导入

界面里走设置 → 设备与服务 → 添加集成，搜索Xiaomi Home进入登录页，有两个要点：

• 地区务必选对：不同地区的设备存在不同的云上，选错就导不出设备，这是登录失败最常见的原因。
• 密码不入库：登录走 OAuth 2.0 流程，密码不会存进 Home Assistant；但登录后的账号令牌会明文存在配置文件中，注意别把配置目录泄露出去。

登录成功会弹出"选择家庭与设备"对话框，勾选要接入的米家家庭，该家庭下的设备会全部导入。刷新设备列表，空气净化器和灯出现在实体列表里，就算跑通了。

跑通之后你可能会好奇：它到底是怎么"跟设备说话"的？下面拆开两条通道看。

设备状态为什么不滞后：订阅推送与家里的小中转站

状态保鲜靠的不是反复询问，更像体育场馆的电子记分牌：比分一变屏幕立刻刷新，你不用每隔几分钟起身去看一次计分板。

技术实现上，集成在小米云的 MQTT Broker（MQTT 是一种轻量级的消息订阅协议）上订阅设备消息通道。设备属性变化或事件触发时，云端把消息实时推给集成；配置完成时它只向云端查一次全部属性，之后不再轮询。控制指令走反方向：集成通过云端 HTTP 接口发出，由云端转发给设备。

如果家里有小米中枢网关（固件 3.3.0_0023 及以上，或内置中枢网关功能的米家设备），链路会进一步缩短：网关内置标准 MQTT Broker，集成直接向网关订阅消息，控制指令也直接发布给网关，由它转发到设备，全程不出局域网。

通道之外还有一条暗线：每台设备都自带 MIoT-Spec-V2 描述，列清楚它有哪些属性、事件、方法。集成拿描述去匹配内置规则——属性转成 sensor 或 switch，事件转成 event，方法转成 button，这就是不同设备生成不同实体组合的原因，也是日后你定制实体的入口。

机制上没什么更多悬念了，但实际用起来还是有几个容易绊脚的地方。

最容易卡住的 4 个问题 ⚠️

登录后部分设备不显示→ 蓝牙、红外和部分虚拟设备目前不支持，或登录时选错了用户地区 → 先在米家 App 确认设备已绑定该账号，再到配置流程里选对地区重新导入。

控制指令走云端、响应偏慢→ 局域网里没有小米中枢网关，指令只能绕道小米云 → 加装中枢网关后本地链路自动生效；配置里的"局域网控制"开关只覆盖 IP 设备，官方文档明确它可能引发异常，不建议拿它顶替。

实体名是英文、或一堆用不上的实体→ 云端翻译不全，冗余的 spec 实例默认没被过滤 → 改 specs 目录下的 multi_lang.json 和 spec_filter.yaml，再到集成配置里点"更新实体转换规则"让修改生效。

想同时管两个小米账号→ 一个账号只导入一套家庭 → 在 Xiaomi Home 配置页点"添加中枢"，再用另一个账号登录一次，不同账号的设备还能放进同一个区域。

进阶资料去哪找

• 官方中文文档：MIoT-Spec-V2 到实体的完整转换表、过滤规则和自定义写法都写在这里。
• specs 映射规则目录：想定制实体、补翻译，从这里动手。
• 更新日志：升级版本前看一眼，确认实体 unique_id 规则有无变化，避免已配置的自动化失效。

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