新手如何把小米米家接入 Home Assistant：ha_xiaomi_home 集成完整指南

发布时间：2026/10/30 2:08:11
新手如何把小米米家接入 Home Assistant：ha_xiaomi_home 集成完整指南

新手如何把小米米家接入 Home Assistant：ha_xiaomi_home 集成完整指南

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

想把小米米家设备接入 Home Assistant，却不知该选哪个插件？ha_xiaomi_home（Xiaomi Home）是小米官方支持的集成组件：登录账号即可把设备批量导入，还支持云端与本地两种控制模式。本文带你走完安装、登录、设备导入与本地控制的全流程。

🚀 快速上手：安装集成并完成账号登录

前置条件

  • Home Assistant 版本：Core ≥ 2024.4.4，Operating System ≥ 13.0
  • 已准备好小米账号，米家 App 中设备已正常联网

安装（三选一）

  1. HACS 一键安装（推荐）：在 HACS 搜索框输入Xiaomi Home，进入详情页点击 DOWNLOAD。
  2. git clone 安装：把仓库克隆到 HA 的 config 目录并运行安装脚本，方便通过切换 tag 回退到指定版本。
git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config
  1. 手动安装：把custom_components/xiaomi_home文件夹复制到config/custom_components目录下。

安装完成后重启 Home Assistant，再按以下路径登录并导入设备：

  1. 进入设置 > 设备与服务 > 添加集成，搜索Xiaomi Home。
  2. 选择登录入口，用小米账号完成 OAuth 登录。
  3. 登录后弹出「选择家庭与设备」，勾选要导入的米家家庭，该家庭设备即被导入。

⚠️ 版本要求是硬门槛：Core 低于 2024.4.4 的 Home Assistant 无法安装本集成。 ⚠️ 登录成功后，账号 token、证书等信息会明文保存在 HA 配置文件中，请自行保管；如怀疑令牌泄露，可在米家 App 的账号授权页取消「Xiaomi Home」授权。

🔍 功能拆解：看懂集成怎么控制设备

云端控制：订阅机制让状态实时更新

默认模式下所有指令都经小米云转发。集成向云端 MQTT Broker 订阅设备消息，设备属性变化或事件发生时由云端实时推送，无需轮询。得益于这套订阅机制，集成只在配置完成时向云端查询一次全部设备属性，之后靠消息订阅更新，对云端压力小，出门在外也能远程查看与控制。

图：云端控制架构，集成经小米云 MQTT 订阅设备状态、经 HTTP 接口下发指令

本地控制：中枢网关让指令不出内网

若家中有小米中枢网关（固件 3.3.0_0023 及以上）或内置中枢网关的设备（软件 0.8.9 及以上），集成可借助网关内置的 MQTT Broker 直接收发指令，不经过小米云。断网时局域网内设备仍可控制，链路更短；需注意中枢网关目前仅在中国大陆可用。

图：本地控制架构，经小米中枢网关内置 MQTT Broker 收发指令，不经过云端

设备自动映射：米家设备直接变 HA 实体

集成会解析设备的 MIoT-Spec-V2 规范，把属性、事件、方法自动转换成 Home Assistant 实体：可写布尔属性变成开关，只读属性变成传感器，带参数的事件变成事件实体，带参数的方法变成通知实体。导入设备即自动生成对应实体，可直接用于自动化。目前蓝牙、红外与虚拟设备暂不支持。

🏠 实战场景：三条常用联动

  • 人来灯亮：门口人体传感器检测到移动 → 客厅灯开启，超时自动关闭。
  • 温度越界自动调空调：温湿度传感器读数高于阈值 → 空调切到制冷；低于阈值 → 切到制热。
  • 门窗异常即时推送：门窗磁传感器触发事件 → 经通知实体发送提醒，并可联动摄像头等安防动作。

⚠️ 避坑指南：高频问题与解决思路

  • 设备加不进来或某些设备不显示？确认米家 App 中该家庭已添加且设备在线；蓝牙、红外、虚拟设备本就不支持。多个家庭可在「选择家庭与设备」里分别勾选导入。
  • 本地控制没生效？本地模式依赖小米中枢网关（固件 3.3.0_0023+）或内置中枢网关设备（软件 0.8.9+），且仅中国大陆可用；局域网控制只覆盖 IP 设备，与中枢网关并存时也不会生效，官方建议谨慎开启。
  • 改了规则文件没反应？修改custom_components/xiaomi_home/miot/specs下的文件后，需在集成配置页执行「更新实体转换规则」才生效。

更多细节可查阅 doc/ 目录与 更新日志。

ha_xiaomi_home 适合手里有一批米家设备、想在 Home Assistant 里做统一控制与跨品牌联动的用户。建议先用 HACS 装好并完成一个家庭的设备导入，跑通基础自动化后，再逐步接入中枢网关体验本地控制。贡献与开发说明见 CONTRIBUTING.md。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考