企业官网建设流程全解析

小米设备接入 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基本可以直接用。它是小米官方支持的 HA 集成组件，基于 MIoT 协议批量导入小米设备，云端和局域网两条控制通道随你切换。先把结论放在这：主力设备是 WiFi 或有线的小米设备、又想要长期不用折腾的话，建议直接上它——新手一小时内能完成从零到全屋上线。

为什么稳：走官方 MIoT 协议，而不是抓包逆向

先说清一个词：MIoT（小米物联网协议）是小米官方开放的设备能力描述标准，每台设备的型号、属性、服务、事件都按统一格式登记。ha_xiaomi_home直接对接这套协议，而不是靠抓包、逆向私有通信——这就是它稳的根源：

• 接口由官方维护，协议不随米家 App 版本漂移，不会"插件一更新就全线失效"；
• 兼容面由小米统一保证，绝大多数品类的设备都在协议覆盖范围内，接入动作被收敛成"一次授权、自动发现"，不用为每台设备手写对接代码；
• 过去那种逆向私有协议的做法，本质是在跟小米的更新节奏赛跑，维护成本高、随时断供。

一句话：它把"接入"这件事从手工作坊变成了标准动作，你看到的是稳定的接口，而不是随时会失效的补丁。

云端还是本地：两种控制通道怎么选

两种模式都基于同一个消息机制：MQTT Broker（可以理解为局域网或云端的"消息中转站"，谁订阅了就推给谁）的区别只在于这个中转站放在哪。

云端通道：人在外地也能指挥

设备状态变化（属性更新、上线离线）由小米云上的 MQTT Broker 实时推给集成层；你在 HA 发出的指令则通过 HTTP 接口发到云端，再转发给设备。优点是对网络环境零挑剔——只要 HA 能连外网，出门在外也能操作全屋。

本地通道：数据不出家门

如果你更在意延迟和隐私，本地模式把中转站换成了小米中枢网关（小米官方网关设备，固件 3.3.0_0023 及以上）——它内置一个标准 MQTT Broker，状态同步和指令收发全在局域网里完成，几乎零延迟，数据不经过任何外部服务器。家里装了中枢网关的话，组件会自动利用它的本地代理能力，无需额外配置。

怎么选，看你在意什么：

• 在意远程控制（出差、回老家想调家里的设备）→ 云端通道，省心；
• 在意联动速度和隐私（传感器触发、本地自动化密集触发）→ 中枢网关 + 本地模式，瞬时响应；
• 两条通道不是互斥的，有网关的设备走本地，其余走云端，可以混着用。

⚠️ 两个前提：中枢网关目前仅在中国大陆销售；组件另有一个"局域网直连"功能支持所有区域，但只能控制 WiFi/以太网设备，官方建议谨慎开启——同一局域网内只要存在中枢网关，该功能自动让位。

ha_xiaomi_home 安装：从环境检查到设备导入

1. 先过环境门槛

• HA Core 版本≥ 2024.4.4（Operating System 发行版 ≥ 13.0）；
• 系统能正常访问小米云服务，否则授权环节会卡住。

版本太旧的话，组件依赖的接口缺失，后面排查会非常费劲，先升版本再装。

2. 二选一安装

Git 克隆（官方推荐，方便日后切换版本 tag）：

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

HACS：在商店里搜索 "Xiaomi Home"，一键下载。

⚠️install.sh只接受一个参数：HA 的config目录路径。无论哪种方式，装完必须重启 Home Assistant，集成才会出现在列表里。

3. 授权账号，设备自动导入

打开"设置 → 设备与服务 → 添加集成"，搜索Xiaomi Home，按提示登录小米账号并选择账号所属区域。可选区域：中国大陆、欧洲、印度、俄罗斯、新加坡、美国。

登录后组件会自动发现账号下的全部设备并批量导入，不用逐台添加。设备分散在多个区域也没关系——不同区域的设备可以统一导入同一个 HA 实例集中调度，也支持添加多个小米账号，跨账号的设备可以归到同一个区域里。

4. 按需微调本地参数

本地控制相关的设备型号清单维护在custom_components/xiaomi_home/miot/lan/profile_models.yaml中，需要时按注释修改即可，常规使用不用动它。

实体为什么"导入即可用"：specv2entity 引擎在背后干活

小米设备出厂时会带一份 MIoT-Spec-V2 规格文档，声明自己有哪些服务、属性、事件和操作。这份规格如果让你自己翻译成 HA 实体，光理解"属性 / 服务 / 事件"三者的边界就得花不少功夫。

组件内置的specv2entity转换引擎把这一步整个自动化了。设备导入完成的那一刻，它已经在后台读取规格、判断每个能力的读写属性和数据类型，生成对应的 HA 实体：

• 可写的布尔属性 →Switch（开关）
• 只读的属性 →Sensor（传感器）
• 可写的多选项 →Select，连续数值 →Number
• 设备事件 →Event实体，操作指令 →Button或Notify

也就是说，没有手写映射这个环节。你只管导入，实体直接能拖进自动化。

支持范围一览：设备品类与多语言

设备类型（六大高频品类）

⚠️ 注意三类设备不支持：蓝牙设备、红外设备、虚拟设备（如米家里的"全屋"虚拟入口）。

多语言

custom_components/xiaomi_home/translations/目录下提供12 种语言的界面翻译，覆盖简体中文、繁体中文、英文、日文、德文、法文、西班牙文、俄文等，界面语言跟随 HA 的语言设置自动切换。

踩坑急救：按故障类型分三块查

网络类——设备连不上

• ✅ 先ping api.io.mi.com，确认 HA 所在机器能访问小米云；
• ✅ 到米家 App 确认该账号对目标设备有控制权限（设备授权给了别的家庭成员是常见坑）。

状态类——实体不更新

按顺序做三件事：

1. 重启 Xiaomi Home 集成；
2. 清除.storage/xiaomi_home.*缓存文件后重启；
3. 检查设备固件是否过旧，能升级就升级。

本地类——本地控制不生效

• ✅ 确认中枢网关与 HA 在同一局域网，且网关 IP 与配置一致；
• ✅ 确认目标设备属于本地控制支持范围（WiFi / 以太网），BLE Mesh、Zigbee 设备走本地通道；
• ✅ 网关固件升到 3.3.0_0023 及以上。

一天怎么用：全屋自动化是怎么跑起来的

串一个具体画面：傍晚进门，门磁触发"回家"场景，玄关灯亮、客厅空调切到舒适温度；一句"看电影"，主灯熄灭、氛围灯转暖色，电视音响同步开机；夜里起身，人体传感器感知到活动，卫生间路径灯自动点亮，回床后自动熄灭；早上出门，离家模式关掉全部灯光、空调转节能。

这些联动能成立，靠的是前面几件事的叠加：设备经 MIoT 协议顺利导入、云端或本地通道保证状态实时同步、转换引擎把每个能力暴露成标准 HA 实体。剩下的场景编排，就是 HA 自动化本身的分内事了。

这套方案适合谁

• 小米设备占主力、想让它们稳定进 HA 做全屋自动化的用户——这就是它的主场；
• 在意响应速度和数据不出家门的用户，家里添一台小米中枢网关，本地通道价值直接拉满；
• 设备以蓝牙 / 红外为主的话，它帮不上忙，先想清楚再装。

下一步建议：先导 3~5 台 WiFi 设备跑通最常用的一两条自动化，验证同步稳定性后再逐步扩量；有中枢网关的，优先把高频联动的传感器和灯光切到本地通道。

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