小米设备接入 Home Assistant 完整指南：三步把米家设备搬进你的智能家居中枢-平芜编程栈

小米设备接入 Home Assistant 完整指南：三步把米家设备搬进你的智能家居中枢

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

ha_xiaomi_home 是小米官方的 Home Assistant 集成组件，让你用一套系统统一管理小米智能家居设备，本文带你完成接入。

小米设备为什么需要接入 Home Assistant

如果你家里同时用着米家、Home Assistant，甚至其他品牌的设备，大概率会遇到一个尴尬：灯在一个 APP 里，插座在另一个 APP 里，想写一条"人来灯亮、人走灯灭"的自动化，却得来回切换好几个应用。生态割裂，是大多数智能家居新手的第一道坎。

ha_xiaomi_home 要解决的就是这件事。它把小米 IoT 设备直接接进 Home Assistant，让这些设备以统一的面板、统一的自动化规则出现在一个系统里。你不用再管设备原本属于哪个 APP，接入之后，它们就都成了 Home Assistant 里可以直接调用、可以互相联动的实体。

小米 HA 集成是怎么跑起来的

看懂它的工作方式，你才知道它为什么稳。整个接入其实靠四条链路，下面每一条我都用大白话给你讲清楚。

第一，OAuth 2.0 登录认证。OAuth 2.0 可以理解为"刷身份证进门，但管家不留你的密码本"。你用小米账号授权时，小米发给 Home Assistant 的是一张"通行证"（token），拿这张通行证就能取到你的设备列表，但它并不保存你的账号密码。所以登录这一关，安全性是交给小米官方账号体系去把关的。

第二，订阅 MQTT 同步设备状态。MQTT 可以理解为设备状态变化的实时消息通道。打个比方：你订了快递，包裹一有动静物流就主动推送给你，不用你自己隔几分钟查一次。集成在小米云上订阅了你关心的设备消息，设备属性一变、事件一发生，消息立刻推过来。正因为靠的是推送，它只在配置完成时查一次全部属性，之后几乎不额外打扰云端，响应也快。

第三，HTTP 接口下发控制命令。HTTP 接口可以理解为"给前台留指令，前台转告后厨"。你在 Home Assistant 里点开关、调数值，集成通过小米云的 HTTP 接口把控制消息发下去，设备收到后做出响应。

第四，经小米中心网关的本地控制。这一条是关键，可以理解为"不用绕路去总店，家里就有个中转站"。小米中枢网关（固件 3.3.0_0023 及以上）或带内置中枢网关的设备里，自带一个标准的 MQTT Broker，实现了完整的订阅与发布机制。有了它，控制命令和设备状态都在你家局域网内来回走，不依赖公网，响应更快也更稳。

这四条链路合起来，就是一份"云端状态同步 + 本地控制兜底"的双通道设计：平时靠云端把设备状态实时同步进来；如果你手上有中枢网关，控制就走本地这条更快的路；没有网关时，命令则全部经由云端完成。两种通道互补，让你既省心又不卡壳。

小米设备接入 Home Assistant 教程：最快接入步骤

第一步，选一种安装方式。你有三种选择，按需取用：

Git 克隆（官方推荐）：最方便后续切换版本，进配置目录执行下面这段命令，把集成代码拉到 Home Assistant 并一键安装。
```
cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config
```
HACS 一键安装：在 HACS 搜索框输入Xiaomi Home，进入详情页点下载，适合不想碰命令行的人。
手动安装：把custom_components/xiaomi_home文件夹通过 Samba 或 FTP 拷到 Home Assistant 的config/custom_components目录下即可。

装完记得重启一次 Home Assistant 让组件生效。安装前注意版本要求：Core ≥ 2024.4.4，操作系统 ≥ 13.0。

第二步，绑定小米账号。进入「设置 > 设备与服务 > 添加集成」，搜索Xiaomi Home，按提示用小米账号登录。登录成功后会弹出"选择家庭与设备"，你挑一个米家家庭，该家庭里的设备就会导入 Home Assistant。如果不止一个账号，可以在已配置页面继续"添加中枢"，把其他小米账号也接进来。

第三步，验证设备上线。回到 Home Assistant 的设备与实体页面，确认你的灯泡、插座、门锁都出现了，状态也实时在变。随便点一下开关，能正常控制，说明接入就完成了。

接好之后能玩什么

接入只是开始，真正有意思的是跨设备联动。给你三个可以直接照着想的场景：

回家自动亮灯。场景：你快到家时。设备：门锁的"已开门"事件 + 门口和客厅的灯泡。效果：门锁一开，玄关和客厅的灯按你设好的顺序自动亮起，你不用摸黑找开关。
门锁与摄像头的安全联动。场景：白天你不在家。设备：门锁/门磁 + 摄像头 + 事件触发。效果：门锁被打开的那一刻，摄像头自动开始录像并推送消息给你，谁进了门一眼就能看到。
用电用水能耗看板。场景：月底想搞清楚钱花在哪。设备：智能插座/电表类传感器 + 数据面板。效果：把各个回路的读数汇总到一张面板上，哪个时段、哪类设备耗电最多，一目了然。

这些场景的共同点是：设备一旦进了同一个系统，你就不用再为"它们能不能对话"发愁，规则写一条就能串起一串动作。

上手前要注意什么：本地控制怎么开与常见限制

对云端有依赖。没有中枢网关时，所有控制命令都走小米云，网络一旦波动，控制会受影响；有网关的本地通道才更抗断网。
网关有型号与地区要求。小米中枢网关目前仅在中国大陆销售和使用，带内置中枢网关的设备也需固件达标（中枢网关 3.3.0_0023 及以上、内置版本 0.8.9 及以上）；海外地区只能走云端。
局域网控制不推荐常开。集成也能通过"小米局域网控制"实现部分本地化，但它只能控制同一局域网内的 IP 设备，管不到 BLE Mesh、ZigBee 设备，且可能引发异常，官方并不建议开启。
多账号注意选对地区。不同地区的小米云数据是隔离的，导入设备时要选对所在区域；不同账号、不同地区的设备可以放进同一个 Home Assistant 区域。
少数设备暂不支持。目前大部分米家设备品类都能接，但蓝牙、红外和虚拟设备这类暂不支持，接入前可以先对一下自家设备的类型。
配置目录要保管好。登录用的是 OAuth 2.0，密码不落地，但设备信息、证书、token 会明文存在 Home Assistant 配置里，一旦配置泄露他人可冒用身份登录，所以别把配置目录暴露出去。