Xiaomi Home 集成部署 Home Assistant 的 5 个实操步骤与故障自查-平芜编程栈

Xiaomi Home 集成部署 Home Assistant 的 5 个实操步骤与故障自查

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

升级 Home Assistant 之后，米家设备实体行为异常或控制失效，是小米用户最常遇到的问题。这篇指南覆盖 Xiaomi Home 集成（Home Assistant 米家集成）的部署、登录导入、实体验证和常见故障自查，照做即可完成接入并定位版本相关问题。

环境要求速查：版本对应表

集成版本	Home Assistant Core	Home Assistant OS	HACS 版本
v0.4.7（当前仓库版本）	≥ 2024.4.4	≥ 13.0	≥ 1.34.0

选哪一行的判断方法：当前仓库提供的就是 v0.4.7，一行即可。若你的 Home Assistant Core 低于 2024.4.4，先升级 Home Assistant 本身，再安装本集成；HACS 低于 1.34.0 时先在 HACS 设置里升级 HACS。Python 运行时不单独列出：标准 Docker / OS / 容器安装自带的 Python 由 Home Assistant 版本决定，满足即可；Python 3.10 及以上由 Home Assistant 2024.4+ 自带。依赖组件（manifest.json）声明了 http、persistent_notification、ffmpeg、zeroconf 四个内置组件，以及 construct、paho-mqtt、numpy、cryptography、psutil 五个 Python 包：前两者随 Home Assistant 内置，ffmpeg 需要系统已安装，Python 包由 Home Assistant 在首次加载集成时自动安装，不需要手动 pip。

部署实操：从一键安装到源码部署

HACS 一键安装（最简单）

打开 Home Assistant 左侧菜单，进入 HACS（社区商店）。
搜索框输入Xiaomi Home，点击进入集成详情页。
点击Download / 下载，等待文件下载完成。
重启 Home Assistant。

重启后左侧「设置 > 设备与服务」中即可看到 Xiaomi Home，这一步完成集成文件落盘，配置放到下一节做。

Git 克隆方式部署（版本切换最灵活）

需要先备份现有 config 目录，然后克隆仓库到配置目录。把下面的/config换成你实际的 Home Assistant 配置目录路径（Docker 安装通常为/config）：

cd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home.git cd ha_xiaomi_home ./install.sh /config

install.sh 会把custom_components/xiaomi_home复制到config/custom_components/下并先删掉旧版本，成功后打印 "Xiaomi Home installation is completed. Please restart Home Assistant."。随后重启 Home Assistant 生效。

需要切换或锁定特定版本时，先拉取远端标签再 checkout 目标 tag，重新执行安装脚本：

cd /config/ha_xiaomi_home git fetch git checkout v0.4.2 ./install.sh /config

切换后重启 Home Assistant 即回到该版本，这是后文回滚操作的基础。

手动复制安装（无 Shell 环境）

没有 Shell 权限时走文件传输路线：把仓库压缩包下载下来，将custom_components/xiaomi_home整个文件夹复制到 Home Assistant 的config/custom_components/下，若该目录已有旧版本先覆盖再重启。适合只装一次、不频繁更新的场景。

配置与首次验证：登录、导入与可用性检查

登录小米账号并导入设备

进入「设置 > 设备与服务 > 添加集成」，搜索 "Xiaomi Home"，点击下一步，用小米账号 OAuth 登录（不保存明文密码）。登录成功会弹出「选择家庭与设备」对话框，选择家庭后该家庭内的设备全部导入 Home Assistant。多小米账号场景下，到「设置 > 设备与服务 > 已配置 > Xiaomi Home > 添加中枢」重复登录即可，不同账号的设备可以放进同一个区域。

验证集成已正常工作

依次做三个检查：

在「设备与服务」页面确认 Xiaomi Home 的集成版本号显示为 v0.4.7（与安装源一致）。
展开已导入设备，确认每个设备生成了实体（switch、sensor、climate、vacuum、fan、light、media_player 等），实体类型由设备 MIoT-Spec-V2 物模型自动决定。
对一个实体执行控制动作（如开一个开关），设备应有响应；状态变化应能自动回推，无需轮询。

需要更细的问题定位时，在configuration.yaml中开启 debug 日志（logger 配置里对custom_components.xiaomi_home设为 debug），重启后查看日志中的消息订阅与控制下发记录。

高频问题自查：按现象定位

集成搜索不到或添加后没反应

现象：添加集成列表里搜不到 Xiaomi Home，或点击登录后无任何界面变化。

原因：集成文件未完整放入config/custom_components/、HACS 依赖未安装、或只做了热重载而非完整重启。

处理：

确认config/custom_components/xiaomi_home/目录存在且包含manifest.json。
执行完整重启（不是 Developer Tools 里的 reload）。
用 Git 方式安装的话，重新跑一次./install.sh /config保证文件齐全。

登录成功但设备列表为空或设备缺失

现象：OAuth 登录通过，「选择家庭与设备」里没有家庭或设备不全。

原因：账号地区不匹配、设备类型不支持、或共享设备归属问题。

处理：

确认配置时选择的用户地区与小米账号所属地区一致——数据在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六地机房相互隔离。
蓝牙、红外及虚拟设备品类目前不支持，缺失属正常。
带中枢网关的设备需网关固件 ≥ 3.3.0_0023（或内置中枢网关软件 ≥ 0.8.9）才能走本地控制，固件低会一直走云端。

实体名称、单位或取值不对

现象：某个属性单位显示错误，或取值列表文案不对。

原因：设备 MIoT-Spec-V2 定义有误，或云端多语言翻译缺失。

处理：编辑custom_components/xiaomi_home/miot/specs/下的文件——spec_modify.yaml改格式与取值、spec_add.json补自定义 spec、multi_lang.json补本地翻译（本地翻译优先级高于云端）。改完必须到「Xiaomi Home > 配置 > 更新实体转换规则」重新加载，文件改动才会生效。

修改本地 spec 文件没生效

现象：改了spec_filter.yaml、spec_modify.yaml等文件，实体没有任何变化。

原因：本地 spec 文件不会热加载，必须触发"更新实体转换规则"。

处理：进入「设置 > 设备与服务 > 已配置 > Xiaomi Home > 配置」，勾选「更新实体转换规则」，下一步完成后重启。

多账号登录后设备重复

现象：同一设备出现两个同名实体。

原因：该设备被多个账号共享，每个账号都把它导入了同一个区域。

处理：确认实际使用的账号，在米家 APP 里调整设备共享关系，或在 Home Assistant 中删除其中一个账号的配置重新登录导入。

控制方式对比：云端、本地与局域网

模式	通信路径	硬件要求	可用性	特点
云端控制	小米云 MQTT Broker 订阅状态 + HTTP API 下发控制	无	全球（六地机房）	受外网与小米云可用性影响
本地控制	中枢网关内嵌 MQTT Broker，订阅与下发均走网关	小米中枢网关固件 ≥ 3.3.0_0023，或内置中枢网关软件 ≥ 0.8.9（中枢网关仅中国大陆可用）	局域网	断外网仍可控制，v0.4.0 起有连接状态通知
局域网控制	直连同局域网 WiFi/网线 IP 设备	同网段 IP 设备	全球	官方标注可能引起异常，建议不要开启

选择原则：家中有中枢网关且在中国大陆时，优先用本地控制；否则保持默认云端控制即可。局域网控制仅在无网关、希望部分本地化时考虑，且若局域网内存在中枢网关，该功能不会生效。

更新与回滚：升级前检查与回滚步骤

升级前做三件事：

核对 CHANGELOG.md 里目标版本的变更，特别注意涉及实体转换规则的条目。
备份config目录——OAuth 令牌、证书、设备 spec 都明文存放在这里。
确认 Home Assistant Core ≥ 2024.4.4。

Git 方式升级（HACS 用户直接在详情页点更新）：

cd /config/ha_xiaomi_home git fetch git checkout v0.4.7 ./install.sh /config

执行后重启 Home Assistant，在设备与服务页面确认版本号已变更。

回滚与善后：

版本回滚：git checkout回旧 tag，重跑./install.sh /config，重启。
配置回滚：从备份还原 config 目录后重启；若升级后登录失效，可删除 Xiaomi Home 配置重新走登录流程（删除前确认已备份）。
⚠️ v0.3.0 起实体 unique_id 生成规则有变更，勾选「更新实体转换规则」可能使已配置的自动化失效；自动化多的实例，升级前先备份再决定要不要更新转换规则。
怀疑 OAuth 令牌泄露时，到米家 APP「我的 > 用户名 > 应用授权」中取消 Xiaomi Home 授权。