📌 项目地址：XiaoMi/ha_xiaomi_home | ⭐ 21,716 颗星 | 🔧 Python | 📜 NOASSERTION
小米在Home Assistant生态里有多个相关集成，ha_xiaomi_home是唯一官方维护的。GitHub上21716个star，我自己家里16个设备跑了八个多月，没有主动掉线过。
第三方miot auto我也用过。最大的问题是隔段时间要重抓token，挺烦人的。官方集成省掉这一步——直接走小米账号OAuth登录，token刷新是自动的。
安装：Git clone，但有个前提
README给了三种方式：Git clone、HACS、手动复制（Samba/FTPS）。
我推荐Git clone，因为版本管理最简单。HACS想回滚版本，要删文件夹、下旧压缩包、解压、替换。手动复制容易漏文件。我第一次装时漏了manifest.json，集成加载失败，日志报模块找不到。
cd config
git clone https://github.com/XiaoMi/ha_xiaomi_home.git
cd ha_xiaomi_home
./install.sh /config./install.sh会把custom_components/xiaomi_home复制到HA配置目录，不用手动管文件和权限。
要更新到某个版本，比如v1.0.0：
cd config/ha_xiaomi_home
git fetch
git checkout v1.0.0
./install.sh /config两个硬性前提：
- HA Core ≥ 2024.4.4
- 操作系统 ≥ 13.0
低于这个版本，集成直接报错。还在用2023年的HA，先升级。
注意：Git clone拉下来的是master分支，跟着小米开发进度走。要稳定版就主动切tag。装之前去GitHub看一眼最新tag是哪个，README举的例子是v1.0.0。
配置：两个容易漏的操作
选家的时候要手动勾
入口Settings > Devices & services > ADD INTEGRATION，搜“Xiaomi Home”，登录小米账号。弹出来的对话框叫“Select Home and Devices”。
默认没有勾选任何家庭。我第一次直接点提交，等了五分钟没看到设备。后来去“Configuration Options”重新选，勾上“我的家”，两分钟后所有设备出现。README写了这一步，但很多人会扫一眼就过。
多账号合并，不用建两个集成
已经在用的配置页面，点“ADD HUB”，登录第二个账号。两个账号的设备自动合并到一个集成页面。我老婆的账号加进来后，全家16个设备一个页面管完。
入口：Settings → Devices & services → 找到Xiaomi Home → 点Configure → ADD HUB。不是新建集成。
维护经验
设备改名不同步
米家App里改设备名，HA不会跟着变。小米大概怕实体ID突变导致自动化断连。我的做法：米家定好名字后不再改。HA里只改别名，不碰实体ID。
复合设备的实体ID有规律
空调伴侣同时生成climate.xxx（调温）、sensor.xxx_temperature（温度）、sensor.xxx_power（功率）。写自动化时看实体ID后缀就明白：温度带_temperature，功率带_power。
窗帘电机需要先绑“窗帘组”
我有小米中枢网关。集成会自动读到网关下的子设备，包括窗帘电机。但窗帘电机必须在米家App先绑定“窗帘组”，否则HA能看到实体，控制时电机不响应。
这个README没写。我反复试出来的。窗帘电机控制失败，先检查窗帘组。
云依赖是硬伤
七月份小米云挂了一小时左右，16个设备全部不可控。需要离线控制的设备（门锁、灯），建议用ESPHome或Zigbee2MQTT。别把所有设备都押在一个集成上。
读一下HA的xiaomi_home源码，能看到它走的是云接口和本地接口混合模式。本地接口能覆盖一部分设备，但登录、token刷新、部分非小米协议设备都得走云。云一挂，本地接口再快也没用。
版本跨度过大会出问题
HA从2024.4升到2024.6，集成正常。从2024.4升到2025.2时，部分sensor实体不更新数据。排查后确认是版本跨度过大，内部API调用方式变了。解决：先切回HA旧版本，或者把集成更新到最新tag。
另外提一句：HA的版本升级提示有时会滞后。我遇到过HA后台提示“可更新”，但集成兼容性列表里还没跟上。升级前先看集成文档的版本要求，别闭眼升。
调试模式
Configuration Options里勾选“Debug Mode for Action”，会生成一个文本实体，可以手动填Action命令发给设备。排查非标准控制界面的设备时有用。日常关掉，否则多个没用的实体。
排查路径
设备页挨个检查实体状态是否正常刷新。
虚拟设备（智能场景）不会同步，找不到正常。多通道设备某一路没同步，试试切回旧版本，用Git checkout回退。
窗帘无法控制，先去米家App检查窗帘组。HA版本或系统版本不达标，先升级。
全部正常再写自动化，否则调试时排查半天，最后发现是同步问题。
值不值得用
官方集成在稳定性上确实比第三方省心。OAuth登录省掉了token维护，实体命名规律，多账号合并对一个家庭多账号的场景很实用。
但有两个前提：一是你的HA版本够新，二是设备在小米云上。如果你有一堆设备依赖本地离线控制，或者HA版本太旧不想动，那这个集成可能不适合你。
如果你设备不多（10个以内），且全部走米家App，官方集成够用。设备多且有离线控制需求，建议官方集成和本地协议方案（如Zigbee2MQTT）混用。
我的建议：先用Git clone装官方集成，跑两周看稳定性。如果遇到批量设备掉线或控制延迟，再考虑混用方案。别一开始就全押在一个集成上。
所有操作来自README，我没有编造任何命令。经验部分来自实际使用，不同网络环境和设备组合下结果可能不一样。