小米设备接入 Home Assistant 终极指南：ha_xiaomi

小米设备接入 Home Assistant 终极指南：ha_xiaomi_home 完整上手

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

在 Home Assistant 面板上点开关，米家的灯纹丝不动；温湿度数值要等半分钟才动一下——这个瞬间劝退过太多想把全屋"收编"进 HA 的人。开源组件 ha_xiaomi_home 就是为此而生的：小米官方支持的 Home Assistant 集成组件，基于官方 MIoT 协议把小米设备变成标准 HA 实体，云端、本地两条控制通道按需使用，不抓包、不逆向。

三步跑通：小米设备接入 Home Assistant 的最短路径

最快的路是 git clone 加一条安装脚本，全程不写代码。

版本要求：Home Assistant Core ≥ 2024.4.4，Operating System ≥ 13.0。

克隆并安装。在 HA 的 config 目录执行下面两条命令，install.sh会把集成自动复制到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/homeassistant/config

⚠️install.sh只接受一个参数——config 目录路径；安装完成后必须重启 Home Assistant，组件才会出现在集成列表里。

添加集成。进入"设置 → 设备与服务"，添加集成，搜索Xiaomi Home，按页面提示用小米账号登录（OAuth 2.0 流程，不会保存你的账号密码）。
选区域、选设备。选择账号所属区域（中国大陆、欧洲、印度、俄罗斯、新加坡、美国六选一），在"选择家庭与设备"对话框勾选家庭，设备批量导入，实体即刻可用。

不想走命令行也可以从 HACS 搜索 "Xiaomi Home" 一键安装，详见简体中文 README。

双通道控制机制：云端管远程，本地管即时

ha_xiaomi_home 内置两条并行的控制通道，它们不互斥，组件会根据你的网络环境自动择优。

云通道绕道小米云，却是远程场景里最稳的路

云控模式下，状态和指令走两个方向：小米云上的 MQTT Broker 把设备状态变化（属性变更、事件、上下线）实时推送给集成；你在 HA 发出的指令则经 HTTP API 送到云端，再转发给设备。得益于订阅而非轮询，集成只在配置完成时向云端全量查询一次属性，对云端压力很小，状态却始终是实时的。

本地通道把终点换成自己家里，指令延迟降到局域网级

只要家里有小米中枢网关（固件 3.3.0_0023 及以上）或内置中枢功能的设备（软件 0.8.9 及以上），集成会通过 mDNS 自动发现并接管它：网关自带标准 MQTT Broker，状态订阅与指令下发全部在局域网内完成，数据不出家门，断网照跑。

⚠️ 另有一个不依赖中枢的"局域网控制"（LAN control），只能控制同局域网内的 IP 设备（WiFi/以太网），官方明确提示"可能引起异常，建议不要使用"；且局域网内存在中枢网关时，该功能会自动失效。

对比维度	云端控制	本地控制（中枢网关）
通信路径	设备 → 小米云 → HA	设备 → 中枢网关 → HA
外部网络依赖	需要，须保持联网	不依赖，纯局域网
指令延迟	受公网波动影响	局域网级，近乎即时
适用场景	出门在外的远程操控	传感器联动、本地自动化

一个藏得很深的亮点：specv2entity 自动"翻译"设备规格

如果没有内置的 specv2entity.py 转换引擎，每接入一台小米设备，你都得人工读懂它的 MIoT-Spec-V2 规格——哪些是属性、哪些是服务、哪些是事件——再逐台手写映射规则。这个引擎把输入到输出做成了一步：输入是设备规格，输出是一整批标准 HA 实体：

可写 bool 属性 →Switch，只读数值属性 →Sensor
带取值列表的属性 →Select，带取值范围 →Number
事件 →Event，无参方法 →Button，带参方法 →Notify

对扫地机、加湿器、温控器这类常见品类，它按设备 > 服务 > 属性 > 通用规则的优先级依次匹配三张映射表；匹配不上特殊规则就落入通用属性转换表。对你的意义很直接：设备导入完成的那一刻，实体就全部能用，一行 yaml 都不用写。

能力全景速查

设备品类、实体覆盖、通道与语言，一张表看全：

维度	支持范围
设备品类	照明、开关插座、传感器、温控、风扇、加湿器、扫地机、音箱等（蓝牙、红外、虚拟设备不支持）
HA 实体覆盖	light、switch、sensor、climate、fan、humidifier、vacuum、cover、media_player、button、number、select、text 等
控制通道	小米云（MQTT + HTTP）、中枢网关本地 MQTT、局域网控制（仅 IP 设备）
账号与区域	多小米账号并存，六大区域（中国大陆/欧洲/印度/俄罗斯/新加坡/美国）可跨区导入同一区域
界面语言	简中、繁中、英、日、德、法、西、俄等 13 种，跟随 HA 语言设置自动切换

翻译文件位于 translations/；实体名称的翻译还可以用 multi_lang.json 在本地补充或覆盖（优先级高于云端翻译）。

避坑手册：高频故障与已验证解法

下面五条按排查频率排列，带 ✅ 的为官方文档验证过的解法。

设备连不上→ 先ping api.io.mi.com确认 HA 网络能到达小米云；再到米家 App 确认账号对该设备有控制权限、设备本身在线 ✅
实体状态不同步→ 依次执行：重启 Xiaomi Home 集成 → 清除.storage/xiaomi_home.*缓存文件 → 检查设备固件是否过旧 ✅
本地控制不生效→ 确认中枢网关与 HA 处于同一局域网、网关固件 ≥ 3.3.0_0023；局域网内已有中枢时"局域网控制"会被自动禁用，别在它身上找原因
改了规格规则实体没变→ 修改 specs/ 下任何文件（如spec_filter.yaml、multi_lang.json）后，必须在集成 CONFIGURE 页面执行"更新实体转换规则"才生效 ✅
怀疑令牌泄露→ 到米家 App → 我的 → 小米账号管理 → 应用授权，找到 "Xiaomi Home (Home Assistant Integration)" 取消授权 ✅