7分钟搞定！Xiaomi Home智能家居无缝接入Home Assistant全指南

你是否还在为小米智能家居设备无法完美融入Home Assistant而烦恼？手动配置复杂、设备响应延迟、多账号管理混乱？本文将带你一站式解决这些痛点，从安装到高级配置，7分钟打造流畅的智能家居控制中心。读完你将获得：3种安装方式对比、云/本地控制架构解析、多账号管理技巧、8种语言支持配置。

为什么选择Xiaomi Home Integration？

Xiaomi Home Integration是小米官方为Home Assistant提供的集成组件，支持绝大多数小米IoT智能设备。与第三方插件相比，它具备三大优势：官方云接口保障数据安全、本地控制降低延迟、多语言界面适配全球用户。目前已支持中国大陆、欧洲、印度等6大地区，覆盖扫地机器人、空调、灯光等20+设备类型。

核心功能模块位于custom_components/xiaomi_home/miot/目录，包含设备通信miot_client.py、云服务miot_cloud.py、本地控制miot_lan.py等核心组件。

安装指南：3种方法任选

方法1：Git Clone（推荐）

适合熟悉命令行的用户，便于版本切换：

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

如需指定版本（如v0.4.2），可在克隆后执行：

git checkout v0.4.2
./install.sh /config

要求Home Assistant版本≥2024.4.4，操作系统≥13.0，查看manifest.json获取完整依赖列表。

方法2：HACS一键安装

Home Assistant社区商店（HACS）用户可直接搜索"Xiaomi Home"完成安装，适合新手用户。安装后在「设备与服务」中添加集成即可。

方法3：手动部署

通过Samba或FTPS将custom_components/xiaomi_home/目录复制到Home Assistant的config/custom_components路径下。该方法需手动处理依赖，仅推荐网络受限环境使用。

配置流程：从登录到设备管理

首次登录与设备导入

1. 进入设置 > 设备与服务 > 添加集成，搜索"Xiaomi Home"
2. 点击登录链接，使用小米账号完成OAuth 2.0授权（账号密码不会存储在本地）
3. 在弹出的"选择家庭与设备"对话框中，勾选需要导入的设备

安全提示：所有用户数据（设备信息、令牌等）将明文存储在配置文件中，建议启用Home Assistant的加密存储功能。如怀疑令牌泄露，可在小米Home APP的「账号管理 > 应用授权」中移除访问权限。

多账号管理技巧

当需要管理多个小米账号时，可在已配置的集成页面点击添加中枢：

设置 > 设备与服务 > 已配置 > Xiaomi Home > ADD HUB

不同账号的设备可共存于同一区域，适合家庭共享场景。账号切换无需重启Home Assistant，实时生效。

高级配置选项

在集成配置页面点击配置按钮，可进行：

• 设备列表更新：同步最新添加的小米设备
• 动作调试模式：通过Text实体手动发送设备控制命令
• 局域网控制设置：启用后支持WiFi设备本地通信（需小米多模网关）
• 实体转换规则更新：修改spec_filter.yaml后需执行此操作

技术解析：云与本地控制双架构

云控制架构

Xiaomi Home Integration通过订阅MIoT Cloud的MQTT Broker实现设备状态同步，控制命令经HTTP接口转发。工作流程：

1. 设备状态变化 → 上传至MIoT Cloud
2. MQTT Broker推送消息至集成组件
3. Home Assistant实体更新状态

优势：支持所有小米IoT设备，不受局域网限制；劣势：依赖网络稳定性，延迟约200-500ms。

本地控制架构

当小米多模网关（固件≥3.3.0_0023）存在时，集成将自动切换为本地通信：

1. Home Assistant与网关建立MQTT连接
2. 控制命令直接发送至网关，无需云端中转
3. 设备状态变化通过网关实时推送

支持设备类型：WiFi直连设备（如空气净化器）、Zigbee设备（需通过网关）；不支持蓝牙及红外设备。本地控制延迟可低至50ms，适合对实时性要求高的场景。

多语言支持与个性化

界面语言设置

集成支持8种语言，配置流程中可选择：简体中文、繁体中文、英语、西班牙语等。语言文件位于：

• 配置流程文本：custom_components/xiaomi_home/translations/
• MIoT规范翻译：custom_components/xiaomi_home/miot/i18n/

示例：修改繁体中文翻译需编辑zh-Hant.json，添加自定义设备名称。

实体命名规则

设备实体命名遵循MIoT-Spec-V2规范，转换逻辑定义于miot_spec.py。常见转换规则：

• 可写布尔属性 → Switch实体
• 带取值范围的数值属性 → Number实体
• 无参数动作 → Button实体

自定义转换规则可通过修改multi_lang.json实现，例如：

{
  "urn:miot-spec-v2:device:health-pot:0000A051:chunmi-a1": {
    "zh-Hant": {
      "service:002": "養生壺",
      "service:002:property:001": "工作狀態"
    }
  }
}

常见问题与解决方案

设备不显示怎么办？

1. 确认设备支持状态：蓝牙、红外设备暂不支持
2. 检查网络区域：小米账号区域需与设备注册区域一致
3. 更新实体规则：集成配置页点击更新实体转换规则

本地控制失效排查

• 网关固件版本需≥3.3.0_0023
• 确保Home Assistant与网关在同一局域网
• 检查防火墙设置：允许访问端口54321（MIoT协议）

多语言显示异常

非中英语言的界面文本由机器翻译生成，如需优化可提交PR至translations目录，官方会定期合并社区贡献。

资源与社区

官方文档：

• 许可证
• 贡献指南 | 简体中文
• 更新日志

开发资源：

• 核心代码：custom_components/xiaomi_home/
• 测试脚本：test/
• 实体转换规则：miot/specs/

如果你在使用中遇到问题，欢迎在项目仓库提交issue，或参与GitHub讨论区交流。贡献代码请遵循Google Python风格指南。

总结与展望

Xiaomi Home Integration通过官方授权的方式，为Home Assistant用户提供了稳定、安全的小米设备接入方案。无论是追求简单部署的普通用户，还是需要定制实体转换规则的高级玩家，都能找到适合的配置方式。随着小米多模网关的普及，本地控制将覆盖更多设备类型，未来有望实现完全脱离云端的智能家居系统。

现在就用3分钟安装体验，让你的小米设备在Home Assistant中焕发新生！如有帮助请点赞收藏，下期将带来「小米扫地机器人自动化场景设计」专题。