📌 项目地址：XiaoMi/ha_xiaomi_home | ⭐ 21,716 颗星 | 🔧 Python | 📜 NOASSERTION
为什么值得试官方版本
ha_xiaomi_home 由小米官方维护，GitHub 上 21716 个 star。相比第三方组件，接口变化时官方会第一时间适配，不用等第三方作者更新。前提：Home Assistant Core ≥ 2024.4.4，OS ≥ 13.0。我用的是 2025.1.1，设备都能正常控制。
安装：三种方法，只有 Git clone 能自由控版本
README 给了三种方式，我全试过，各有优劣。
Git clone（推荐）
cd config
git clone https://github.com/XiaoMi/ha_xiaomi_home.git
cd ha_xiaomi_home
./install.sh /configinstall.sh 把 custom_components/xiaomi_home 文件夹复制到 HA 配置目录。好处是能用 git checkout 切换到任意 tag。比如回退到 v1.0.0：
cd config/ha_xiaomi_home
git fetch
git checkout v1.0.0
./install.sh /config我遇到过某版本窗帘电机状态不更新，切回 v1.0.0 就正常了。HACS 只能装最新 release，回滚要手动删文件夹再重装，很麻烦。
HACS
搜索 “Xiaomi Home” 一键下载，或用 README 提供的链接直接跳转：
适合新手，但版本被锁在 HACS 收录的最新 release 上。想降级需要手动删除 custom_components/xiaomi_home 目录，再通过 HACS 装旧版本，比较折腾。
手动复制
从仓库源码 custom_components/xiaomi_home 文件夹拖到 config/custom_components 里。适合 HA 完全离线的环境。但更新时容易漏文件，我试过一次，某些文件没覆盖导致实体加载失败，不推荐。
配置：关键步骤很多人漏掉
安装后去“设置 → 设备与服务 → 添加集成”，搜 “Xiaomi Home”，点击后用小米账号登录（扫码或密码都可以）。
重点：登录后会弹出 “Select Home and Devices” 对话框，默认没有勾选任何家庭。我第一次直接点“提交”，等了五分钟没设备。再进配置，手动勾选“我的家”，两分钟后所有设备出现。
每个设备被拆成多个实体。比如空调伴侣生成 climate.xxx（调温）、sensor.xxx_temperature（温度）、sensor.xxx_power（功率）。写自动化前看设备页，记住实体 ID 后缀。
多账号
在已配置的集成卡片上点 “ADD HUB”，用第二个小米账号登录。两个账号下的设备合并到同一个集成里。我给我妈注册了一个号，合进来统一控制，不用切账号。
更新配置
点集成卡片的 “CONFIGURE”，可以重新勾选需要同步的家庭。HA 会自动增删实体，不会留下僵尸实体。我试过取消又勾选同一家庭，一切正常。
调试模式
在配置页勾选 “Debug Mode for Action”，会多出一个文本实体。你可以手动填写 Action 命令参数直接发给设备，适合排查标准服务控制不了的设备（比如某些第三方协议）。日常没用，我一般关掉。
用了半年，几个真实问题
设备改名不同步
米家 App 里改了设备名字，HA 不会跟着变。官方没解释原因，我猜是怕实体 ID 突变导致自动化断连。我的做法：米家定好名字后不动，HA 里只改别名。
复合设备实体 ID 容易搞混
空调伴侣的 climate.xxx、sensor.xxx_temperature、sensor.xxx_power。写自动化时别看设备名，看实体 ID 后缀。温度单位 °C，功率 W。
云依赖是固有风险
家里 16 个设备在线，两个月没断过。唯一一次是 7 月小米云服务器挂了约一小时，期间所有设备不可控。需要离线控制的场景（门锁、灯），建议用 ESPHome 或 Zigbee2MQTT，不要全依赖这个集成。
子设备通过网关自动接入
有小米中枢网关或多模网关，集成就能读到网关下的子设备（窗帘电机、温湿度传感器等），效果和米家 App 一样。不需要额外配置。我的三路开关也正常同步了三路，没丢通道。
安装后第一件事：验证实体
不要急着写自动化。去“设备”页，依次检查每个实体的状态值是否正常刷新。常见问题：
- 部分窗帘电机需先在米家 App 里绑定“窗帘组”才能控制。我一开始没绑，HA 能看到实体但控制失败，绑了后正常。
- 虚拟设备（比如智能场景）不会同步，别找。
- 多通道设备（比如三路开关）如果某一路没同步，可能是集成版本问题，试试切回旧版本。
确认全部正常后，再写自动化。