企业官网建设流程全解析

米家设备接入Home Assistant终极指南：用ha_xiaomi_home让全屋设备统一听你指挥

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

晚上十一点半，卧室灯光要调到最暗、空调要切到睡眠模式、客厅插座要断电、门锁要确认落锁——这一串动作，如果还靠你拿起手机、在米家App里逐页寻找设备，少说也要花上五分钟。而装上 ha_xiaomi_home 之后，这些事可以浓缩成一句语音、一个按钮，甚至一条全自动触发的场景。它是小米官方支持的 Home Assistant 集成组件，能把米家账号下几乎全系的智能设备接入 Home Assistant，从此灯光、空调、传感器、门锁都在同一个平台上协同工作。下面这份指南，是我从"在十个App之间来回横跳"到"一个面板全搞定"的完整经验，希望能帮你少走弯路。

先看结果：那个不用打开任何App的早晨

我改造完家里的智能家居后，记下了这么一个普通早晨：

07:00，卧室窗帘在闹钟响起前缓缓拉开，灯光用十分钟从1%慢慢亮到30%，模拟日出。我拿起床头的平板看了一眼——不对，我压根没看，因为一切都在按场景运行。出门前喊了一声"离家"，全屋灯光熄灭、空调进入节能模式、扫地机器人开始工作、摄像头布防。

放在几个月前，这套流程需要我打开米家App关灯、再切到另一个App看摄像头、再打开第三个App调空调。现在呢？设备还是那些设备，变化的只是它们被装进了同一个系统。

带来这种变化的，就是 ha_xiaomi_home。它把小米设备从"米家App的私有世界里"解放出来，放进了 Home Assistant 这个开放生态——你可以把小米的灯具、插座、传感器，和任意其他品牌的设备放在同一个自动化里，互相触发、协同工作。

它到底是什么？凭什么值得装

简单说，ha_xiaomi_home 是小米官方提供的 Home Assistant 集成组件，你只需要登录自己的小米账号，组件就会把账号下的智能设备自动导入 Home Assistant，自动转换成对应的实体（开关、传感器、灯、空调等）。

和社区里那些靠逆向协议打通的第三方方案相比，它有三个明显的底气：

• ✅官方支持：登录走的是小米官方 OAuth 2.0 授权流程，设备通讯用的是官方 MIoT 协议，稳定性和兼容性有保障，而且持续更新。
• ✅导入即用：不需要手工配置设备型号、不填token、不写yaml映射，登录、选家庭、完事。
• ✅跨区域跨账号：中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个区域的设备都能导入，而且支持多个小米账号共存，不同账号的设备还能放进同一个房间。

两种工作模式：走云端的快递 vs 走家里的对讲机

这是 ha_xiaomi_home 最值得说的设计——它给了你两条控制通路，你可以按自己的需求选。

第一条：云端模式，随时随地。设备状态变化时，小米云会把消息实时推送给 Home Assistant；你要下发指令，指令先送到云端，再由云端转发给设备。整个过程不需要你干预，出门在外也能远程控制，代价是依赖外网、有一点点延迟。

第二条：本地模式，毫秒级响应。如果你家里有一台小米中枢网关（固件3.3.0及以上），网关内置了标准 MQTT Broker，设备和 Home Assistant 之间的通信全程在局域网内完成，不经过任何外部服务器。这就像和邻居隔墙喊话，比绕一圈云端快得多，隐私也更好。

怎么理解这两张图？你可以把云端模式想象成"发快递"：包裹（指令）先到中转站（小米云），再派送给收件人（设备），可靠但多一道工序。本地模式则是"对讲机"：网关里的 MQTT Broker 就是基站，设备状态一有变化，消息瞬间送达。想要快速响应的场景——比如人体传感器触发灯光、湿度变化启动加湿器——本地模式明显更合适。

十分钟上车：最快的安装与配置路线

先确认一个前提：Home Assistant Core 版本不低于 2024.4.4。满足之后，有三种安装方式，任选其一。

方式一：命令行克隆（我最推荐，方便日后切换版本）：

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

方式二：HACS 一键安装。在 HACS 商店搜索 "Xiaomi Home"，进入详情页点击下载即可，适合习惯用 HACS 管理组件的朋友。

方式三：手动拷贝。把custom_components/xiaomi_home整个文件夹复制到 Home Assistant 配置目录下的custom_components/里。

装完重启 Home Assistant，接下来就是见证奇迹的时刻：

1. 进入"设置 > 设备与服务"，点击"添加集成"，搜索 "Xiaomi Home"。
2. 按提示用小米账号登录（OAuth 2.0 授权，不会保存你的账号密码）。
3. 登录后选择"家庭与设备"，组件会把该家庭下的所有设备批量导入。

整个过程大约五分钟。导入完成后你会在设备列表里看到成排的小米设备——灯、插座、传感器、空调伴侣、加湿器……它们已经全部变成了 Home Assistant 能识别的实体。如果你在多个区域有设备，或想加入第二个小米账号，也可以在集成配置页里继续"添加中枢"，把不同账号、不同区域的设备合并到同一个房间管理。

藏在背后的"同声传译"：MIoT-Spec-V2 怎么变成实体

你可能会好奇：小米设备那么多，型号五花八门，组件是怎么自动把它们变成 Home Assistant 实体的？

关键在于小米的 MIoT-Spec-V2 协议。你可以把它理解成一份标准的"设备说明书"：每台设备由若干服务组成，服务下面有属性（property）、事件（event）和动作（action）。ha_xiaomi_home 内置的转换引擎会根据这些定义，自动为设备生成合适的实体类型，核心实现在custom_components/xiaomi_home/miot/specs/specv2entity.py这个文件里。

转换规则很有逻辑性，举几个最常见的：

也就是说，一台智能灯接入后，它的亮度、色温会自动变成可调节的数字实体，开关状态变成 Switch，你几乎不用做任何手动映射。另外，如果某个设备的规格不是小米标准命名空间定义的，实体名前面会自动加一个*号，方便你一眼识别来源。

组件还贴心地内置了13种语言包，存放在custom_components/xiaomi_home/translations/目录下，包括简体中文、繁体中文、英语、日语、德语、法语、西班牙语等，界面语言会跟随 Home Assistant 自动适配。

装上之后，生活真的不一样了

设备导入只是开始，真正的乐趣在于自动化。这里分享几个我实际在用的场景，都基于 ha_xiaomi_home 导入的设备：

• 💡回家亮灯：门磁传感器检测到开门，玄关灯立刻亮起（本地模式，响应几乎无延迟），再根据时间判断是否打开客厅主灯。
• 💨自动除湿：湿度传感器超过70%，加湿器自动开启；低于55%自动关闭。
• 🛋️观影模式：一句"看电影"，客厅主灯关闭、氛围灯调成暖色、电视和音响开机。
• 🚪离家兜底：检测到所有人离开，自动关灯、关空调、启动扫地机器人。

你可能注意到，这些场景里既有小米设备，也有其他品牌的设备——这正是接入 Home Assistant 的意义：自动化不再被品牌圈在各自的App里。ha_xiaomi_home 负责把小米设备"翻译"给整个生态，剩下的联动交给你的想象力。

入坑前必看：这些限制和坑，官方没写进宣传里

任何工具都有边界，把话说在前面能帮你省不少排查时间：

• 三类设备暂不支持：蓝牙设备、红外设备、虚拟设备。如果你家里主要是这类设备，需要提前心理预期。
• 中枢网关只在部分区域有售：本地控制依赖小米中枢网关或内置中枢网关功能的设备，而中枢网关目前仅在中国大陆发售。其他区域的用户默认走云端模式。
• LAN 控制功能要慎用：如果家里没有中枢网关，你可以在配置里开启"局域网控制"，但要注意它只能控制 WiFi 或网线连接的 IP 设备，控制不了 BLE Mesh、ZigBee 设备，而且官方明确提示该功能"可能引起异常"，不建议开启。另外，一旦局域网内存在中枢网关，LAN 控制会自动失效。相关参数可在custom_components/xiaomi_home/miot/lan/profile_models.yaml中查看。
• 配置文件里会明文保存账号信息：登录采用 OAuth 2.0，不会存储密码，但受 Home Assistant 平台限制，设备信息、证书、token 等会明文保存在配置文件中。请务必保管好配置文件，如果怀疑 token 泄露，可以在米家App的账号管理里撤销对"Home Assistant Integration"的授权。
• 云端模式依赖外网：外网中断时云端控制会失效，设备状态也可能延迟。追求稳定低延迟，建议配一台中枢网关走本地模式。

你可能想问的五个问题

Q1：支持所有小米设备吗？绝大多数主流品类都支持，只有蓝牙、红外和虚拟设备三类不行。

Q2：家里已经有一堆米家设备，需要重新买吗？不需要，账号下的存量设备直接导入，一台都不用重买。

Q3：可以同时用多个小米账号吗？可以，而且不同账号、甚至不同区域的设备都能合并到同一个 Home Assistant 里管理。

Q4：和米家App冲突吗？不冲突，米家App照常用，Home Assistant 只是新增了一条管理通路。

Q5：我是新手，配置难吗？整个流程只有"安装、登录、选家庭"三步，没有yaml要写，配置难度对新手非常友好。

最后：从"拥有设备"到"拥有场景"

回想一下，当初买智能家居时，我们想要的是什么？不是一堆会"单机联网"的灯和插座，而是"回家灯亮、起床窗帘开、出门全屋安防"这种整体体验。可现实中，设备越多，App越多，体验反而越割裂。ha_xiaomi_home 的意义，正是把这种割裂重新缝合起来——它让小米设备真正成为开放智能家居生态的一部分，而不是被困在自家App里的孤岛。

真正的智能家居，从来不是比谁设备多，而是比设备能不能协同。而这，正是 ha_xiaomi_home 帮你实现的事。现在就去克隆一份试试吧，五分钟之后，你可能会和我一样，再也回不去那个"满屏App"的日子了。

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