企业官网建设流程全解析

如何快速把小米米家设备接入 Home Assistant？ha_xiaomi_home 官方集成完整指南

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

晚上回家还要在米家 App 里逐个关灯、关插座的瞬间，你一定想过：能不能把所有小米设备搬进 Home Assistant 统一管理？ha_xiaomi_home（米家集成）就是干这件事的——它把小米 MIoT 设备接入 Home Assistant，让你用 HA 的面板和自动化掌控整个家。

一句话看懂它

简单说，ha_xiaomi_home 是小米官方维护的一个 Home Assistant 集成组件：装好之后，你米家账号下的灯泡、插座、空气净化器、扫地机器人……都会变成 HA 里标准的实体，可以直接点亮、调温、写自动化。✅

为什么值得信它？第一，它是小米官方出品的开源项目，云端接口也是官方提供的，稳定性和安全性比社区"魔改"方案踏实得多；第二，登录走的是 OAuth 2.0，HA 里不会存你的小米账号密码；第三，设备多、品类杂的小米生态，正是 HA 最需要这类"官方搬运工"的场景。

它背后是怎么跑起来的

这套集成内部有四条线在干活，用大白话讲一遍，你就知道它为什么既快又稳。

登录：一张不存密码的"门禁卡"

你用小米账号登录时，走的是 OAuth 2.0 授权流程，类似住酒店刷房卡：集成只拿到一把"钥匙"（令牌），拿不到你的账号密码本身。需要注意的是，登录成功后，令牌、设备信息会明文保存在 HA 的配置文件里，所以配置文件要保管好。万一怀疑令牌泄露，可以在米家 App 的账号安全页里一键取消授权。

状态同步：订阅群消息，而不是反复敲门

设备状态是怎么"实时"出现在 HA 里的？集成并没有每隔几秒去问一次云端"我的灯现在啥状态"，而是在 MIoT 云上订阅了 MQTT 消息。打个比方：它像加了一个群聊，设备一有变化（开关、属性变动、事件触发），消息就自动推到 HA，秒级更新。配置完成时只需向云端查询一次全部属性，之后的访问压力非常小。

下发指令：通过 HTTP 接口"点外卖"

反过来，你在 HA 里点一下"开灯"，集成会通过 MIoT 云的 HTTP 接口把控制命令发给设备，云端再转发给设备执行。就像点外卖下单，订单经平台送达厨房，你不用自己跑餐厅。

本地直连：把"外卖"换成"自家厨房"

如果你的局域网里有小米中枢网关（固件 3.3.0_0023 及以上），或者内置中枢网关的米家设备（软件 0.8.9 及以上），集成就会切到本地模式：网关本身内置了一个标准 MQTT Broker，状态推送和控制指令都在局域网内完成，不再绕远路经过云端——响应更快，断外网时家里照样能自动化。

注意：小米中枢网关目前仅在中国大陆地区发售；海外用户没有网关时，指令默认全部走云端。

五分钟上手

先确认版本：HA 核心版本需 ≥ 2024.4.4。然后按你喜欢的路子装：

方式一：Git 克隆（官方推荐，方便回退到指定版本）🚀

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

方式二：HACS 一键安装—— 打开 HACS，搜索框输入 Xiaomi Home，进入详情页点 DOWNLOAD 即可。

方式三：手动安装—— 把custom_components/xiaomi_home整个文件夹复制到 HA 的config/custom_components目录下（可用 Samba 或 FTP 传输），重启 HA。

装完开始登录：进入「设置 > 设备与服务 > 添加集成」，搜索Xiaomi Home，按提示用小米账号 OAuth 登录，然后在"选择家庭与设备"对话框里勾选要导入的米家家庭，设备就批量进来了。

家里有两个小米账号？完全没问题：进入「已配置 > Xiaomi Home」，点「添加中枢」，再登录另一个账号即可。不同账号的设备甚至能放进同一个 HA 区域统一管理。

落地玩法

设备进来了，才是好玩的部分。给你四个可以直接抄的场景：

回家自动开灯 🏠—— 触发条件用门磁/人体传感器或手机地理围栏（回家事件），动作设为打开玄关灯、空调。因为状态是 MQTT 实时推送的，人还没开门，灯已经亮了。

离家布防—— 自动化里把"所有成员离家 + 布防时段"设为触发，动作开启摄像头录像并推送告警到你的 HA 通知通道，门锁异常事件也会第一时间弹出来。

一键影音模式—— 建一个场景：打开电视、调暗灯光、音箱播轻音乐。配合米家音箱的 Notify 类实体，还能让音箱用语音报"观影模式已开启"。

能耗一眼看电耗 📊—— 把带电量计量的插座或智能电表作为传感器导入，用 HA 的能源面板或仪表卡片查看客厅、厨房各自用了多少度电，月底账单不再是一笔糊涂账。

更多转换规则和细节，可以参考 中文 README 和 源码目录 custom_components/xiaomi_home/miot/。

能力边界与注意点

上手前把这几条丑话说在前面，能少走弯路：

• 不是 100% 全品类：蓝牙设备、红外设备、虚拟设备暂不支持，其余绝大多数品类都覆盖。
• 本地模式有门槛：中枢网关只在大陆地区销售；局域网控制（LAN control）虽不限地区，但只能控制同网段的 WiFi/网线直连设备，且官方并不建议开启，稳定性不如走中枢网关。
• 可用地区：云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个区域，配置时要选对地区；跨地区的设备可以导入到同一个 HA 区域。
• 安全提醒：OAuth 令牌等用户信息明文存于 HA 配置文件，服务器安全要自己守住；怀疑泄露就去米家 App 撤销授权。
• 适合谁：适合愿意折腾 Home Assistant 的多设备小米用户；如果你只有两三个设备且只用米家 App，这套集成可能"火力过剩"。

常见问题

问：我买了个小米蓝牙温度计，能导入吗？

不能。蓝牙、红外和虚拟设备目前不在支持范围内，WiFi/以太网/ZigBee 等品类基本都可以。

问：外网断了，我的自动化还活着吗？

没有中枢网关的话，指令要经云端中转，外网断就失效了；有小米中枢网关（或内置中枢的设备）时，状态订阅和控制都走局域网，断外网照样运转。

问：老公和老婆各有一个小米账号，设备冲突吗？

不冲突。集成支持多账号登录，两个账号的设备可以共存，还能放到同一个区域里统一调度。

写在最后

ha_xiaomi_home 把"官方出品、OAuth 安全登录、MQTT 实时状态、HTTP 下发指令、可选本地直连"这几件事一次做齐了，对小米生态 + Home Assistant 双栈用户来说，基本是目前最省心的选择。🎯

如果这篇指南帮你想通了接入路径，不妨去翻一翻仓库里的 README、更新日志 和 贡献指南——看完之后，你的米家设备可能正等着被自动化"接管"呢。

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