企业官网建设流程全解析

ha_xiaomi_home 完整指南：小米设备接入 Home Assistant 四步跑通（含云端与本地双通道对比）

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

ha_xiaomi_home 是小米官方支持的 Home Assistant 集成组件，作用是把你手里的米家设备接入 Home Assistant（下文简称 HA）：一次账号授权，自动发现并批量导入设备，再把设备能力自动转成 HA 实体，同时提供云端与本地两条控制通道。按本指南操作，从零到跑通第一条自动化，全程不需要写一行映射代码。

为什么米家设备接 HA 总是出问题，而它不用

在装任何东西之前，先弄清一个前提：米家是一个相对封闭的生态，设备数据默认只在米家 App 与小米云之间流动。而 HA 的优势恰恰在开放——它期望各家设备通过标准协议上报状态、接收指令。

过去想跨过这道墙，常见手段是抓包、逆向协议。这类方案的共同问题是"脆"：米家 App 或云端接口一更新，插件就可能全线失效，且每接一个新设备都得多写一套对接逻辑。

ha_xiaomi_home 走的是另一条路：直接对接小米官方开放的 MIoT（小米物联网）协议。简单说，MIoT 是小米给每款 IoT 设备写的"能力说明书"，用服务、属性、事件、动作四个部分描述设备会什么、能改什么、发生了什么。对着官方说明书接入，有三个直接好处：

• 接口由小米官方维护，不再随逆向工程失效；
• 设备兼容面广，覆盖照明、插座、传感器、温控、风扇、加湿器等常见品类；
• 接入动作收敛为"一次授权、自动发现"，不为每台设备手写对接代码。

✅ 登录走 OAuth 2.0，HA 不保存你的小米账号密码；但登录后的设备信息、token 会以明文存放在 HA 配置目录里，请妥善保管该目录。怀疑 token 泄露时，可到米家 App 的账号管理页撤销应用授权。

三步装好 Xiaomi Home 集成

安装前自检与三种安装方式

动手前先过一遍检查点：

• HA Core 版本 ≥ 2024.4.4（过低版本缺少组件依赖的接口）；
• 网络能正常访问小米云服务；
• 设备是 WiFi/以太网接入，或家中已配备支持本地模式的中枢网关。

安装方式三选一，任选其一即可：

方式一：Git 克隆 + 安装脚本（官方推荐，便于按 tag 切换版本）

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

install.sh只接受一个参数——HA 的config目录路径，它负责把组件复制到config/custom_components/xiaomi_home。想更新到某个版本时，git checkout对应 tag 后重跑脚本即可。

方式二：HACS：在 HACS 商店搜索 "Xiaomi Home"，进入详情页点击下载。

方式三：手动复制：把custom_components/xiaomi_home整个文件夹拷进 HA 的custom_components目录。

账号授权与设备导入

装完先别急着找设备，必须重启 Home Assistant，组件才会出现在集成列表里。然后按这个顺序走：

1. 打开"设置 → 设备与服务 → 添加集成"，搜索 "Xiaomi Home"；
2. 按页面提示用小米账号登录，选择账号所属区域（中国大陆、欧洲、印度、俄罗斯、新加坡、美国）；
3. 登录成功后弹出"选择家庭与设备"对话框，勾选要导入的家庭，设备随即批量导入；
4. 已有其他小米账号？在集成设置页继续"添加中枢"即可追加账号，多账号、多区域的设备可以合并进同一个 HA 实例集中调度。

导入完成后，到"设备与服务"里确认设备列表，再给每台设备点一下实体，状态对得上，这一步就算跑通了。

云端与本地两条通道：一张表看懂怎么选

组件不是"二选一"的开关，而是两套可随时切换的通信通道，差别在于指令和状态数据走哪条路。

云端通道：状态变化（属性变更、上线、离线）由小米云的 MQTT Broker 实时推给集成，你的控制指令经 HTTP API 发到云端再转发给设备。不挑网络环境，人在外地也能操作家里设备。

本地通道：把通信终点从云端换成小米中枢网关——网关内置的 MQTT Broker 承担状态同步与指令收发，数据只在局域网里转一圈，不经过任何外部服务器。

选通道时按场景定，别纠结"哪个更好"：

• 你家里有中枢网关 → 优先本地，传感器联动这类高频动作走局域网最稳；
• 你只有纯云设备 → 走云端，本地模式帮不上忙；
• 你常出门 → 云端兜底，保证远程可用。

两个版本门槛要注意：独立中枢网关需固件 ≥ 3.3.0_0023；带内置中枢功能的设备需软件版本 ≥ 0.8.9。另外，组件还提供"LAN 控制"选项，直接走局域网控制同网段的 IP 设备——官方对它的评价是"谨慎使用"，且家中已有中枢网关时开启它也不生效，能走网关就别用它。

导入的设备为什么自动就有了实体

设备一导入，灯、插座、传感器就已经在 HA 面板里能用了——这一步背后是 custom_components/xiaomi_home/miot/specs/specv2entity.py 里的转换引擎在干活。

MIoT-Spec-V2（即上文的 MIoT 协议规格）里，每个属性都标着访问方式（只读、读写）和值类型。如果你自己动手翻译，要逐属性判断"这该变成开关还是传感器"；引擎把这活自动化了，核心规则大致如下：

设备整体则按类型落到具体领域：智能灯 → light、空调伴侣 → climate、智能风扇 → fan、加湿器 → humidifier 等。也就是说，你导入完成的那一刻，实体已经就位，可以直接拖进自动化。

当前覆盖六类高频设备：照明（light）、开关插座（switch）、传感器（sensor）、温控（climate）、风扇（fan）、加湿器（humidifier）。明确不支持的是蓝牙设备、红外设备与虚拟设备，买设备前可以先对一下。

第一个联动怎么配，四个卡点怎么快速排查

跑通第一条自动化

别一上来就搭全屋场景，先拿一条最短的链验证闭环。例如"人体传感器触发 → 玄关灯亮 5 分钟后关闭"：

1. 打开 HA 的"自动化与脚本 → 创建自动化"；
2. 触发条件选已导入的人体传感器实体，事件类型选"发生"；
3. 执行动作选玄关灯的 light 实体，"打开"，再追加"延时 5 分钟 → 关闭"；
4. 保存后手动在传感器上触发一次，或走到传感器跟前，确认灯真的动了。

这条链同时验证了设备导入、实体转换、指令下发三件事。跑通之后，"回家"、"看电影"、"夜间起床"这类场景都只是把同样的积木换一种拼法。

卡住时按顺序查这四类问题

• 设备根本连不上：先ping api.io.mi.com确认 HA 所在网络能通小米云；再到米家 App 里确认该账号对设备有控制权限，排除设备本身离线。
• 实体状态和实际不一致：按顺序试——重启 Xiaomi Home 集成 → 清理.storage/xiaomi_home.*缓存文件 → 检查设备固件是否过旧。
• 本地控制不生效：确认中枢网关与 HA 在同一局域网；核对网关 IP 与配置一致；确认设备属于本地控制支持范围（WiFi/以太网接入，BLE Mesh、ZigBee 设备不行）。
• 实体类型不符合预期：这是转换引擎按 MIoT 规格映射的结果，属正常现象；可先接受它，或在集成设置里调整导入的设备清单。

下一步做什么

装完之后，建议按这个顺序推进：

1. 今晚就把上面那条"人体传感器 → 玄关灯"的自动化跑起来，先让闭环转一圈；
2. 把家里最高频的三五个联动（回家、离家、夜间、观影）排出来，逐个用实体拼好；
3. 有中枢网关的话，观察本地通道一两天，对比响应速度和稳定性，再决定是否把常开设备全切到本地。

细节随时可查仓库里的 README.md 与中文文档 doc/README_zh.md，本指南只讲主干，坑都标在路上了。

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