米家设备接入 Home Assistant：ha_xiaomi_home 三种安装方式与本地控制实操

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

ha_xiaomi_home（Xiaomi Home）是小米官方的 Home Assistant 集成：登录小米账号后，把米家设备批量导入为可在 HA 里控制和自动化的实体。本文覆盖安装路径选择、登录配置、本地控制与进阶开关，写给想装起来、装完能用的人。

能力速览：先给结论

一句话结论：它能把绝大多数米家设备管起来，装完一小时左右可以全部跑通。

• 品类广：主流米家品类基本都支持，纯蓝牙、红外和虚拟设备除外。
• 多账号：多个小米账号可同时在线，设备还能放进同一个 HA 区域。
• 控制双链路：默认走小米云，有小家中枢网关后可切到全本地链路。
• 实体自动生成：按 MIoT-Spec-V2 描述自动生成 Text、Switch、Select 等实体，不用手写实体配置。
• 13 种语言：集成界面与设备名翻译支持简体中文、英文等 13 种语言，本地可扩充。

工作原理：状态和指令的两条链路

先搞懂集成和设备之间怎么对话，再选安装方式。

云端链路：集成向小米云的 MQTT Broker 订阅设备消息。MQTT 你可以理解成设备消息的"订阅制报纸"：属性变化或事件发生时，设备推一条上行消息，Broker 转给集成，HA 立刻知道，全程不轮询；整个配置过程只全量查询一次属性。指令方向反过来：HA 通过云端 HTTP 接口发命令，云端转发给设备执行。

本地链路：小家中枢网关内置一个标准 MQTT Broker，集成直接向它订阅；发指令时集成把命令发布到 Broker，由网关转发给设备。"设备 → 网关 → HA"整段在局域网内闭环，不依赖外网。

设备的能力描述来自 MIoT-Spec-V2 协议：一个设备挂多个服务，服务里再分属性、事件、方法。集成按固定规则把它们转成 HA 实体：

比如无线开关的"长按"事件会生成 Event 实体，按键被长按时触发自动化，事件参数里带着是哪一个键。

硬性条件：动手前先核对

最后一项最容易踩：各地区小米云数据互相隔离，首次配置务必选自己所在区域，选错只能重配。

路径选择：三种安装方式对照

三条路终点相同：组件落在config/custom_components/xiaomi_home。推荐 Git 克隆，理由在升级那栏——版本切换和回退都是改一行 tag 的事。

Git 克隆

进入 HA 的 config 目录，克隆仓库并执行官方安装脚本，输出 "Xiaomi Home installation is completed" 即成功：

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

以后想固定到某个版本，切 tag 再跑一次脚本即可，例如固定到 v0.5.0：

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

脚本无报错输出即切换成功，重启 HA 后实体按该版本规则生成。

HACS

在 HACS 搜索框输入Xiaomi Home，进入详情页点 DOWNLOAD，稍后回到集成列表就能搜到它。

Samba / FTP 手动复制

把仓库里的custom_components/xiaomi_home文件夹整体拷到 HA 的config/custom_components下，重启生效。每次更新都要手动覆盖一次，最省事也最费手，适合完全不碰终端的人。

🛠️ 上手流程：从登录到设备入网

1. 重启 Home Assistant，进集成搜索页能看到 "Xiaomi Home"，说明组件加载成功。
2. 设置 > 设备与服务 > 添加集成，搜索Xiaomi Home，下一步，点登录链接。
3. 用 OAuth 2.0 授权登录小米账号——走小米的第三方授权页，HA 里不输入你的密码。
4. 登录成功后弹出"选择家庭与设备"，勾选目标米家家庭，该家庭下设备批量导入。
5. 打开任意一个导入的实体（比如灯），开关一次；HA 里的状态和米家 App 里同步变化，即链路通了。

之后的所有操作都在"Xiaomi Home > 配置"页完成。

进阶配置：四个高频开关

多账号：第一个账号配完后，设置 > 设备与服务 > 已配置 > Xiaomi Home > 添加中枢，再走一遍登录。两个账号的设备可以放进同一个区域统一管理。

局域网控制：配置页执行"更新局域网控制配置"后，同一局域网内的 IP 设备（WiFi 或网线连接）可走局域网通道。官方明确该功能可能引起异常、不建议使用；且局域网内已有中枢网关时它不会生效。建议有中枢网关就别开，确实没中枢又嫌云端慢再试。

Action 调试模式：开启后，带输入参数的设备方法会额外生成一个文本实体，手动填参数就能向设备发 Action 指令，适合验证某个 Notify 实体的控制链路。

更新实体转换规则：改过custom_components/xiaomi_home/miot/specs/下任何文件（如spec_filter.yaml、multi_lang.json）后，必须到配置页执行"更新实体转换规则"才生效。其中multi_lang.json用于本地补充或改写设备名翻译，优先级高于云端多语言文件。

❓ 高频问题

Q：有些设备导入不了，为什么？结论在前：纯蓝牙、红外和虚拟设备目前不支持。如果你的型号属于这几类，集成内没有解法，只能换同品类的 WiFi 或 ZigBee 版本。

Q：没有中枢网关，还算本地控制吗？不算。完整本地控制要求中枢网关固件 ≥ 3.3.0_0023，或内置中枢的设备（软件 ≥ 0.8.9）；没有中枢，所有指令都走小米云。上面的局域网控制开关只覆盖同局域网 IP 设备，蓝牙 Mesh、ZigBee 设备它管不到。

Q：能同时登多个小米账号吗？能。多账号并存，且不同账号的设备可以添加进同一个 HA 区域。

Q：海外能用吗？能。云服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个地区，配置时选自己所在区域即可，之后不同地区的设备也能汇入同一区域。

⚠️ 提醒与自保

• 别把配置文件弄丢或外泄。OAuth 登录后，设备信息、证书、token 会明文存在 HA 配置文件里，文件一旦泄露，他人可冒用你的身份登录，备份要管好。
• 定期核对应用授权。怀疑 token 泄露时：米家 App → 我的 → 用户名进入小米账号页 → 应用授权 → Xiaomi Home → 取消授权。
• 中枢网关仅中国大陆可用。其他地区想走本地控制，只能依赖内置中枢网关功能的设备。
• 局域网控制默认建议不开。官方 README 已提示可能引起异常；开启后若设备行为诡异，先关掉它再排查。

源码入口与日常建议

日常使用建议：保持 HA 与米家设备在同一局域网；用区域功能给设备分组；把设备事件接进自动化；每次升级前先看 CHANGELOG.md 确认本版本改了什么。

官方中文文档见 doc/README_zh.md，安装、配置、映射规则和目录结构都在这一处。

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