小米设备接入 Home Assistant 实战指南：4 步把全屋米家设备搬进 HA
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
这是一份小米设备接入 Home Assistant 的完整攻略：小米官方支持的组件 ha_xiaomi_home 基于 MIoT 协议对接设备，提供云端与本地双控制通道，一次授权就能把你的米家设备自动导入 HA。
接入完成后的家：一个晚上的自动化
先看接完之后你每天能得到的东西。傍晚推开门，门磁先一步把信号送给 HA，玄关灯自己亮起，空调早已切到你习惯的送风温度；窝在沙发上喊一句"看电影"，客厅主灯熄灭、氛围灯带转暖，电视和回音壁同时开机；半夜起身，人体传感器把去卫生间的过灯点亮，躺回去之后又自动熄灭；清晨出门，离家模式关断全部照明，空调转入节能档。
这些动作你不用去米家 App 里逐个点按钮，也不用为每个房间配遥控器，它们都写在 HA 的自动化编辑器里。前提只有一个：小米设备得先进入 Home Assistant。下面就是完整的做法。
ha_xiaomi_home 是什么：协议、状态、指令的中转站
先弄清这个组件替你做哪些事，出了问题才知道该往哪里查。它干三件事，而且全自动：
- 协议转换——把小米设备的能力规格翻译成 HA 认识的标准实体；
- 状态同步——设备状态一变，HA 面板上立刻更新；
- 指令转发——你在 HA 里发出的开关、调温操作，准确送达对应设备。
有三个术语第一次出现，各解释一句：
| 术语 | 一句话解释 |
|---|---|
| MIoT 协议 | 小米官方开放的物联网标准，每台设备用统一格式声明自己有哪些属性、能收什么指令 |
| MQTT Broker | 消息中介，组件在它那里"订阅"设备消息，状态变化主动推送，不用反复轮询 |
| 小米中枢网关 | 米家生态的家用网关，内置 MQTT Broker，可以在局域网里代理设备通信 |
理解成"翻译 + 快递员"即可：规格翻译给 HA 看，状态实时送到，指令按地址发出。
ha_xiaomi_home 安装教程：环境、安装、授权四步走完
按下面四步操作完，你的小米设备就会整整齐齐出现在 HA 里，全程不需要写代码。
先检查这两项，别省
动手前确认环境，能省掉后面一大半排查时间：
- HA 版本：官方要求 Core ≥ 2024.4.4，Operating System ≥ 13.0，版本太旧会缺组件依赖的接口；
- 网络连通性：确认系统能访问小米云，终端执行一条命令即可验证：
ping api.io.mi.com有回应就继续，没有就先解决网络问题。
Git 脚本或 HACS 安装，二选一
方式一：Git 克隆（官方推荐，后续切换版本方便）：
git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config方式二：HACS 安装：在 HACS 商店搜索 "Xiaomi Home"，进入详情页一键下载即可。
⚠️ 两个容易踩的坑：
install.sh只接受一个参数，就是 HA 的config目录路径，传多传少都会直接报错退出；无论哪种方式装完，必须重启 Home Assistant，集成才会出现在列表里。
小米账号授权与区域选择
进入设置 → 设备与服务 → 添加集成，搜索 "Xiaomi Home"，按提示用小米账号登录，并选择账号所属区域。可选区域有六个：中国大陆、欧洲、印度、俄罗斯、新加坡、美国。
授权成功后，组件会自动发现账号下的全部设备并批量导入，不用逐台添加。两个实用点：同一个 HA 可以继续添加其他小米账号；不同区域的设备也能导入同一个 HA 实例统一调度。
本地控制参数在哪改
本地控制相关的参数集中在 custom_components/xiaomi_home/miot/lan/profile_models.yaml，需要时按文件内注释修改。
⚠️ 官方建议对本地控制模式保持谨慎，目前仅支持 WiFi 或以太网（局域网 IP）连接的设备；蓝牙 Mesh、ZigBee 设备不在其列。如果你家里有小米中枢网关，组件会自动利用网关的本地代理能力，无需额外配置。
云控 vs 本地：一张表看清两种通道
看完这节能根据你的网络环境和生活习惯选定主通道，两者不互斥，可以按场景混用。
| 对比维度 | 云端控制 | 本地控制 |
|---|---|---|
| 通信路径 | 设备 → 小米云 → HA | 设备 → 中枢网关 → HA |
| 网络依赖 | 需保持外网连通 | 纯局域网，断外网照常工作 |
| 响应速度 | 受网络波动影响 | 局域网内几乎无延迟 |
| 隐私 | 状态数据经云端中转 | 数据不出家门 |
| 典型场景 | 出远门远程操控 | 传感器联动、本地自动化 |
云控模式下，云端的 MQTT Broker 负责把设备状态变更实时推送给组件，控制指令则通过云端 HTTP 接口下发，人在外地也能指挥全屋；本地模式把通信终点换成中枢网关，所有数据只在局域网里转一圈。
另外说明一点：小米中枢网关目前仅在中国大陆销售，其他地区只能依赖云控或局域网控制能力。
导入即可用：MIoT 规格自动转换引擎
这是组件里最省事、也最容易被忽略的一环：你导入设备那一刻，实体就已经生成好了，一行代码、一张映射表都不用写。
原理是这样的：每台小米设备都附带一份 MIoT-Spec-V2 规格，像说明书一样描述自己"有什么属性、能做什么"。组件内置的 specv2entity.py 转换引擎读取这份规格，自动判断每项能力的读写属性和数据类型，再对号入座生成 HA 实体：
| 设备规格里的能力 | 自动生成的 HA 实体 |
|---|---|
| 可写的布尔属性 | Switch（开关） |
| 只读属性 | Sensor（传感器） |
| 带取值范围的数值属性 | Number（数值） |
| 带固定选项的属性 | Select（下拉选择） |
| 可写字符串属性 | Text（文本） |
| 设备事件 | Event（事件） |
| 无参数的方法 | Button（按钮） |
| 带参数的方法 | Notify（通知） |
所以温湿度计导入后自动变成传感器、灯变成可开关的灯实体、空调伴侣变成温控实体，理解"属性 vs 服务 vs 事件"这类协议细节的事，引擎替你做了。
覆盖面速查：六大类设备与 13 种语言
导入前可以先对一下家里的设备清单，高频品类基本都能覆盖：
| 设备类别 | 对应 HA 领域 | 典型设备 |
|---|---|---|
| 照明设备 | light | 智能灯泡、灯带 |
| 开关插座 | switch | 智能插座、墙壁开关 |
| 传感器 | sensor | 温湿度、人体、门窗传感器 |
| 温控设备 | climate | 空调伴侣、智能温控器 |
| 风扇 | fan | 智能风扇、空气循环扇 |
| 加湿器 | humidifier | 各类智能加湿器 |
语言方面，translations/ 目录下提供了 13 种语言的翻译文件，覆盖简中、繁中、英文、日文、德文、法文、西文、俄文、意大利文、荷兰文、葡萄牙文、巴西葡萄牙文和土耳其文，配置界面会跟随 HA 的语言设置自动切换。
出问题时怎么办：三类高频问题排查清单
卡住了别慌，按下面的顺序排查，大多数问题都能对号入座。
设备连不上
- 先
ping api.io.mi.com，确认网络能到小米云； - 再到米家 App 里确认该账号对这台设备有控制权限；
- 最后排除设备本身离线、掉线的情况。
实体状态不同步
- 重启 Xiaomi Home 集成；
- 仍不行则清除
.storage/xiaomi_home.*缓存文件后重启 HA； - 再检查设备固件是否过旧，能升级就升级。
本地控制失效
- 确认中枢网关与 HA 处于同一局域网；
- 核对网关状态与配置是否一致；
- 确认设备属于本地控制支持的范围（WiFi/以太网），蓝牙 Mesh、ZigBee 设备走不了这条路。
把接入交给组件，把编排留给自己
ha_xiaomi_home 的价值，在于把智能家居里最繁琐的"接入"环节做成了标准动作：授权一次，设备批量导入，实体自动生成。小米设备接入 Home Assistant 之后，你面对的是同一个可以随意编排的全屋平台，而不是两套互相隔离的系统。剩下的场景与联动，都是 HA 自动化编辑器里点两下的事。
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
