Home Assistant 接入米家：合法打通与常见坑

Home Assistant 接入米家：合法打通与常见坑

速查结论

米家与 Home Assistant（简称 HA）的打通，官方途径只有一条：米家的「Xiaomi Home 集成 / 开放接口（OAuth 授权）」。任何要你扫码登录、输入账号密码、抓取云端 Token 的第三方插件，都是「能用但不稳定、不合规」的路线，账号安全风险自己承担。
云端对接（OAuth）：免维护、自动发现设备，但断外网就废；局域网对接（局域网控制/蓝牙网关代理）：断外网可用、响应更快，但配置复杂、设备覆盖不全。
HA 接米家的正确姿势是「米家负责入网与传感器，HA 负责跨生态联动」，不要反过来——HA 里建所有 Zigbee 网络是另一套生态，投入翻倍。
接入前必做：给 HA 单独申请一个米家账号（家庭组共享设备），不要用主力账号授权，主账号修改密码/注销会直接打挂整个 HA。

三条路线对比速查

路线	原理	合法性	优点	缺点
官方云接入	OAuth 授权，走米家开放平台接口	官方支持	配置简单、设备自动同步、维护成本低	依赖外网、延迟较高、设备类型覆盖有差异
局域网接入	局域网内直连智能设备（Wi-Fi 设备本地协议）	灰色地带/需自行评估	断外网可用、响应快	需要设备支持、配置复杂、可能违反部分设备使用条款
第三方云端插件	用个人米家账号模拟登录抓 Token	不合规、账号风险	功能最全	Token 过期即失效、账号可能被风控、密码泄露风险

结论：首推官方云接入。如果你的 HA 只为「米家 + HomeKit + 其他生态互联」，云接入已经覆盖 90% 场景。

官方云接入的步骤

前置条件

一台运行 Home Assistant 的主机（树莓派/虚拟机/NAS/小主机均可）。
一个可访问互联网的网络环境。
一个专用米家账号（另行注册），并把这个账号加入家庭组，共享所需设备。

配置流程

1. HA 「设置 → 设备与服务 → 添加集成」
       ↓
2. 搜索「Xiaomi Home / 米家」官方集成（名称以集成列表为准）
       ↓
3. 选择「使用米家账号登录（OAuth）」
       ↓
4. 跳转米家授权页 → 输入专用账号 → 同意授权
       ↓
5. HA 自动拉取该账号下的设备并生成实体

同步策略

项目	说明
账号	用专用账号（家庭组共享），不要用主账号
设备共享	米家 APP 中「家庭管理 → 共享设备」给专用账号
自动发现	接入后设备自动出现，无需手动绑定
实体命名	首次同步后建议在 HA 里统一改名，方便自动化
刷新频率	状态随云端推送/轮询更新，传感器类有分钟级延迟

局域网路线（进阶，自行评估合规性）

适用场景：外网不稳定、追求低延迟、部分场景想断网可用。

常见玩法

局域网控制集成：直接与支持本地协议的米家 Wi-Fi 设备通信（需要设备型号支持，且通常需要通过抓包获取设备标识）。
蓝牙集成：HA 主机插蓝牙 USB 适配器，直接扫描米家蓝牙设备（温湿度传感器、牙刷等）。
Zigbee 协调器：HA 插 Zigbee USB 协调器（如基于 CC2652/EMBER 芯片的协调器），绕开米家网关直连 Zigbee 设备。但注意——配入 HA 的 Zigbee 设备就离开了米家网关，米家 APP 内不再可用，这是一次「迁出」而不是「共享」。

局域网路线的注意事项

设备不可同时属于两个网络控制器：Zigbee 设备同一时间只能 paired 到一个协调器。
不能为了「本地化」把米家网关下核心设备全部迁出——先迁非核心传感器（温湿度、人体感应）试水。
技术细节与合规性随固件/版本变化，自行评估设备使用条款与账号安全风险，本文不提供具体绕过手段。

接入后的联动模式

模式一：米家 → HA（推荐主力）

设备在米家，自动化在 HA。适合：

米家设备 + 非 HomeKit 设备 → HA 桥接到 HomeKit；
HA 里做复杂逻辑（与、或、时间、状态机）。

模式二：HA → 米家（补充）

HA 为控制方，调用米家设备服务。适合：

HA 的传感器/自动化里直接调用米家设备（如 HA 里的天气预报变化 → 开米家窗帘）。

模式三：双引擎（主 HA，米家兜底）

HA 做云上编排与跨生态；
核心照明/安防同时保留米家本地自动化，HA 挂了家里还能用。

接入后的进阶配置

实体组织

米家同步进来的实体数量会随设备增加而膨胀，做好组织很关键：

统一命名规则：房间-位置-类型（如 客厅-吊灯-主灯），自动化里调用一目了然。
按房间建区域：HA 的「区域」概念，把设备按房间归类，批量执行场景。
隐藏无用实体：每个设备会同步十几个实体，只保留状态、开关、传感器核心实体，界面清爽一半。
用「场景+助手」代替裸实体：在 HA 里把高频组合做成脚本，再暴露给语音/面板。

典型 HA 自动化示例（伪代码表述）

触发：人体存在传感器（玄关）状态变化
条件：太阳下山后
动作：
  - 客厅主灯 → 开
  - 窗帘电机 → 关闭
  - 小爱音箱（经米家云）→ 播报「欢迎回家」

触发：温湿度传感器温度 > 28℃
条件：有人在家（人体传感器任一有人）
动作：
  - 米家空调伴侣 → 开机制冷 26℃
  - 延时 30 分钟 → 检查温度，若 < 25℃ 则关机

书写自动化的核心纪律：每个动作加超时与失败分支，避免「卡住等云端」。

常用维护清单

每月检查授权状态（集成页面有无「需要重新授权」提示）；
每月备份一次 HA 配置（设置 → 系统 → 备份）；
HA 大版本升级前先快照，升级出问题可以回滚；
长期不用的旧实体清理掉，避免自动化引用失效。

常见坑

用主账号授权：改密码、换手机、注销，任何一个操作都会让 HA 授权失效，且账号异地登录有风控提示。专用小号 + 家庭共享设备是标准解。
云端自动化做高实时联动：传感器 → 云端 → HA → 云端 → 灯具，全程 3~10 秒延迟，人体感应灯能等到人坐下才亮。高实时场景交给本地（Zigbee 网关本地联动或 HA 局域网）。
米家 Token 模式过时不知道：Token 有效期有限，某天所有设备集体「不可用」，先怀疑授权过期而不是设备坏了。
HA 桥接 HomeKit 超过设备数上限：HomeKit 桥有数量上限（常见为单桥 150 个实体），实体多的家庭拆桥。
米家自动化与 HA 自动化重复执行：同一个「开门开灯」在两边都配，开两次灯/延迟翻倍。一边配就不在另一边配，明确分工。
蓝牙设备距离：HA 主机的 USB 蓝牙适配器信号穿墙差，远端设备频繁「不可用」，加蓝牙 Mesh 中继或改用 Wi-Fi 直连设备。
断网部署定位错误：云接入方案在外网中断时整个 HA 对米家失去控制；想要断网可用，回到本地化方案（见 ms-0501）。

部署硬件建议（量级参考）

方案	硬件	成本量级	适合
入门	树莓派 + SD 卡	300~600 元	体验、少量设备
常用	x86 小主机（N100 类）+ SSD	600~1500 元	200 实体以内
进阶	NAS 虚拟机 / 独立小主机 + UPS	1500 元以上	全屋 + 长期运行

存储用 SSD：HA 数据库写入频繁，SD 卡 3~6 个月大概率报废。
配 UPS：HA 主机 + 路由器 + 中枢统一备电，断网不断系统。
远程访问：不要把 HA 端口直接暴露到公网，使用官方或成熟的远程方案。

与其他章节的联系

是否值得上 HA，先看《中枢网关与本地化：断网也能执行的底层逻辑》（ms-0501.md）——米家中枢能解决 80% 需求；跨生态视角见《Matter 与米家：跨生态互联现状与选购建议》（ms-0505.md）；网络基础见《网络规划：Mesh 路由与 AP 布置建议》（ms-0103.md）。