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 CoreHome Assistant OSHACS 版本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 安装通常为/configcd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home.git cd ha_xiaomi_home ./install.sh /configinstall.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 授权。延伸阅读官方中文文档doc/README_zh.md更新日志CHANGELOG.md贡献指南doc/CONTRIBUTING_zh.md依赖声明manifest.json【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考