米家设备接入 Home Assistant：官方 Xiaomi Home 集成教程
如果你已经搭好 Home Assistant，下一步通常就是把家里分散在米家 App 里的设备集中到一个面板里。本文用小米官方维护的 Xiaomi Home 集成，演示从安装、账号授权到检查设备实体的完整流程。
如果还没有 HA 主机，可以先看本站的Home Assistant OS 安装入门。
先安装集成并授权账号，再选择米家家庭；设备接入后能否本地控制，要看具体型号和网关条件。
先选对集成
“米家接入 HA”有几条不同路线，名字容易让人混淆。本文主要介绍小米官方仓库 XiaoMi/ha_xiaomi_home 提供、通过 HACS 安装的 Xiaomi Home 集成。它根据 MIoT 设备规格创建 Home Assistant 实体，并通过小米账号授权导入家庭设备。
| 路线 | 适合情况 | 主要区别 |
|---|---|---|
| 小米官方 Xiaomi Home（本文） | 希望用账号导入米家家庭中的一批设备 | 需要安装 HACS 集成；OAuth 登录；设备支持情况按品类和型号而异 |
HA 内置 xiaomi_miio | 设备在 HA 官方文档的支持列表里，或需要手动填写设备令牌 | 集成域名是 xiaomi_miio；支持范围和配置项不同，不能与小米官方仓库混为一谈 |
| 社区 Xiaomi Miot 等集成 | 官方集成不支持自己的设备，愿意自行维护社区组件 | 安装来源、支持范围和维护节奏由对应项目决定；使用前先读该项目说明 |
HA 官方文档中的 xiaomi_miio 页面也使用了 “Xiaomi Home” 作为显示名称，但它是另一个内置集成。本文的官方集成来自小米自己的 GitHub 仓库，组件目录为 xiaomi_home。如果添加时看到相似名称，先确认你安装的是哪一条路线；官方仓库的配置流程会引导你跳转到小米账号登录页面。查看 HA 内置集成的支持范围。
开始前准备
- Home Assistant 已经能正常访问，并且已完成一次备份。
- 目标设备已经在手机的米家／Xiaomi Home App 中配网，且当前账号能看到它们。
- 记下米家账号使用的服务地区，例如中国大陆。不同地区的设备数据隔离，授权时必须选对地区。
- 确认 HA 主机能访问互联网。默认控制路径可能依赖小米云；需要本地控制时还要满足设备和网关条件。
小米官方仓库当前 README 列出的最低版本是 Home Assistant Core 2024.4.4 和 Home Assistant OS 13.0。实际使用建议先更新到受支持的稳定版本，并在安装前查看官方 README 的最新要求。
第一步：准备 HACS
如果你的 Home Assistant 已经有 HACS，跳到下一步。HACS 的安装方式取决于 HAOS、Container 或 Core 等安装类型，请以官方安装说明对应的标签页为准。
对 HAOS / Supervised，当前官方步骤是：
- 在 Home Assistant 中添加第三方 App 仓库：
https://github.com/hacs/addons。 - 打开“设置 → App → 安装 App”，安装 Get HACS，然后启动它。
- 查看 Get HACS 的日志并按提示完成下载。
- 重启 Home Assistant，再在“设置 → 设备与服务 → 添加集成”中完成 HACS 的首次配置。
**版本提示：**截至 2026 年 10 月，HACS 文档仍列有 HAOS 的独立安装步骤；文档同时说明从 Home Assistant 2026.11 起，HACS 会作为内置 Marketplace 提供。如果你使用 2026.11 或更新版本，先按当时的官方页面操作，可能不需要单独安装 HACS。
第二步：从 HACS 安装小米官方集成
- 打开 Home Assistant 左侧的 HACS。
- 进入 Integrations（集成），搜索 Xiaomi Home。
- 打开由小米官方仓库提供的集成详情页，选择 Download。
- 下载完成后重启 Home Assistant，让新集成加载。
如果搜索不到，先确认 HACS 已完成初始化、网络可以访问 GitHub，并且搜索的是集成而非 Dashboard 或主题。
第三步：登录账号并导入米家家庭
- 打开“设置 → 设备与服务 → 添加集成”，搜索 Xiaomi Home。
- 选择小米官方集成，按提示点击登录链接。Home Assistant 会打开小米的账号授权流程。
- 在小米登录页面完成授权，然后回到 HA。
- 选择与米家 App 一致的服务地区，再选择要导入的米家家庭。
- 提交配置并等待设备载入。集成会把选中家庭里的受支持设备导入 HA；一个账号下有多个家庭时，按需要添加。
- 打开“设置 → 设备与服务 → Xiaomi Home”，检查设备数量和实体列表。
小米官方集成使用 OAuth 2.0，不要求把小米账号密码写进 configuration.yaml。完成授权后，先试一盏灯或一个传感器：查看状态是否变化，再测试一个低风险控制动作。确认实体正常后，便可以将它加入仪表盘，或在“自动化与场景”里使用。
云端和本地控制有什么区别
接入成功不代表设备一定能断网运行。小米官方文档说明，设备的状态消息和控制路径会因设备、网关及配置而异：没有可用中枢网关时，控制指令可能经小米云发送；符合条件的中枢网关可以提供本地控制。官方 README 列出的支持本地控制的中枢网关需要满足相应固件版本，其中小米中枢网关目前仅在中国大陆可用。
集成还有“更新局域网控制配置”选项，但官方说明它主要适用于和 HA 在同一局域网中的 Wi-Fi／以太网设备，不适用于蓝牙 Mesh 或 Zigbee 设备，并提示这项功能可能造成异常。建议先用默认设置把设备接通，再根据自己的型号和网络情况评估；不要把“进了 HA”理解为“所有指令都在本地”。详情见小米官方集成说明。
常见问题
搜索不到设备
检查添加的是正确的米家家庭、账号和服务地区；确认设备仍在线并已绑定到米家 App。也可以到 Xiaomi Home 集成的“配置”中更新设备列表。小米官方文档指出，仍有少数蓝牙、红外及虚拟设备品类不受该集成支持。
设备出现了，但控制不了
先看实体是否可用，再确认 HA 主机能联网。若你配置了 VLAN、防火墙或访客网络，检查 HA 与目标设备／中枢网关之间的通信规则。局域网控制只适用于满足条件的 IP 设备，不会自动覆盖 Zigbee、蓝牙等所有设备。
登录成功后，担心账号安全
OAuth 登录不会把小米账号密码保存在该集成里，但小米官方文档提醒，用户信息、设备信息、证书和令牌会明文保存在 Home Assistant 配置文件中。妥善保管配置目录和备份，不要把 .storage、完整备份或令牌截图发到公开场合。如果怀疑授权信息泄露，可在米家 App 的账号授权管理中撤销 Xiaomi Home (Home Assistant Integration)，再回到 HA 重新授权。
小结
入门时可以按这个顺序做：先在米家 App 确认设备在线，再从 HACS 安装小米官方 Xiaomi Home 集成，用正确地区的账号授权，选择家庭，最后逐个验证实体。设备清单、可用功能和本地控制能力都取决于具体型号；遇到不支持的设备时，先查官方列表，再决定是否需要另一条集成路线。
更多资料：小米官方集成 README · HACS 安装说明 · HA 内置 xiaomi_miio 文档