ha_xiaomi_home 使用指南：把米家设备接入 Home Assistant 的最短路径-编程实验室

ha_xiaomi_home 使用指南：把米家设备接入 Home Assistant 的最短路径

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

如果你手里有一堆小米智能设备，又用 Home Assistant 做家庭自动化，那么 ha_xiaomi_home 就是两者之间的桥梁。这个由小米官方支持的集成组件，能让米家 App 里的灯泡、插座、空气净化器等设备直接出现在 Home Assistant 中，参与你的自动化流程。本文面向第一次尝试接入的读者，讲清楚准备什么、怎么装、以及它为什么能实时感知设备状态。

接入后你能得到什么

最直接的收益是"一套设备，两个入口"。设备照常在米家 App 里管理，同时它们以标准实体的形式进入 Home Assistant：开关灯、查湿度、看门锁状态，都能写成自动化或交给语音助手。

对多账户家庭也有实际意义：集成支持登录多个小米账号，还能把不同账号下的设备放进同一个 Home Assistant 区域统一管理。另外，接入完成后集成会根据小米 MIoT 规范自动为设备生成实体，灯有亮度颜色、空调有温度档位，不需要你手动逐台定义。

接入前需要准备什么

Home Assistant 版本：Core 2024.4.4 及以上，或 Operating System 13.0 及以上。
一个小米账号：登录用的是 OAuth 2.0 授权流程，类似"第三方应用授权登录"，集成本身不保存你的账号密码。
设备范围：大部分米家品类都支持，但蓝牙设备、红外设备和虚拟设备不在支持列表内。
地区：云服务接口部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国，配置时需要选择账号所在地区。

有一点要提前知道：登录成功后，你的设备信息、令牌等会明文存放在 Home Assistant 的配置文件里，所以配置文件本身要保管好。

最快跑起来的步骤

官方推荐用 git 方式安装，因为以后想切换特定版本时最方便。在你的 Home Assistant 服务器上执行：

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

不想折腾命令行也可以：在 HACS 商店里搜索Xiaomi Home一键安装，或者把custom_components/xiaomi_home文件夹手动复制进你的config/custom_components目录。

装好后进入 Home Assistant 的"设置 > 设备与服务 > 添加集成"，搜索 Xiaomi Home 并用小米账号登录，然后弹出"选择家庭与设备"对话框，勾选要导入的家庭即可。整个过程不需要手写任何配置文件。

设备状态是怎么实时同步的

默认情况下走云端链路。集成向小米云的 MQTT Broker 订阅你关心的设备消息——MQTT 可以理解为一个"设备消息广播站"，设备一有变化（属性改变、产生事件、上下线），消息就会主动推给集成，而不是集成反复去云端"问"一次。控制方向相反：你在 Home Assistant 里下发指令时，集成通过小米云的 HTTP 接口把命令发给设备。一推一拉，状态刷新快，对云端的访问压力也不大。

如果你家有小米中枢网关（固件 3.3.0_0023 及以上），或者设备本身内置中枢网关功能（软件 0.8.9 及以上），链路就变成纯本地：网关内部自带一个 MQTT Broker，状态推送和控制下发都不出你家网络，延迟更低，也不依赖外网。

需要留意的是，中枢网关目前仅在中国大陆销售。官方还提供"局域网控制"开关作为替代，但它只能管同一局域网里的 Wi-Fi/网线设备，管不了蓝牙 Mesh 和 ZigBee 设备，且官方并不建议使用。