企业官网建设流程全解析

三步把小米设备搬进 Home Assistant：官方 Xiaomi Home 集成完整指南

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

家里有一堆小米设备，却想在 Home Assistant 里编排自动化？你可能已经发现：HA 里根本找不到这些设备的影子。这时就该请出小米官方支持的集成 ha_xiaomi_home 了——它把米家设备接进 Home Assistant，云端控制和局域网本地控制都能用，登录、选设备、建实体全程在 HA 界面里点完。

痛点：你的小米设备，在 Home Assistant 里"隐身"

想象一下这个场景：你想让"窗帘开到位后自动开灯"，结果打开 HA 才发现——窗帘、灯、空气净化器这些米家设备，一个都不在实体列表里。

问题不在你的操作，而在 HA 本身没有米家的入口。ha_xiaomi_home 就是补这块短板的官方集成，它帮你做三件事：

• 用你的小米账号把设备"搬"进 HA，不用手写任何配置文件
• 设备状态变化时自动同步，不用你轮询刷新
• 把米家设备的每个功能，翻译成 HA 认识的实体（灯是 light、开关是 switch、空调是 climate）

全程只需要一个小米账号，下面开始动手。🔌

如何五分钟把小米设备搬进 Home Assistant

1. 先确认版本够不够

集成对 HA 的版本有要求，不满足先升级：

• Core 版本 ≥ 2024.4.4
• Operating System 版本 ≥ 13.0

2. 克隆仓库并运行安装脚本

进入 HA 的 config 目录，执行：

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

install.sh 会做两件事：删掉旧版本，再把 custom_components/xiaomi_home 整个文件夹复制到config/custom_components下。

不想用 git 的话，也有两条备选路：在 HACS 里搜索Xiaomi Home一键安装；或者用 Samba/FTP 手动把custom_components/xiaomi_home文件夹拷到 HA 的custom_components目录。

3. 重启 HA，登录账号建实体

1. 重启 Home Assistant
2. 打开设置 → 设备与服务 → 添加集成，搜索Xiaomi Home
3. 点击登录，用小米账号完成授权
4. 在弹出的"选择家庭与设备"对话框里，勾选要导入的家庭，该家庭下的设备就全部进来了

之后想锁定某个版本？回到仓库目录执行git checkout v0.4.7再跑一次./install.sh /config即可。

能力速览：这个集成能覆盖哪些场景

云端与本地双通道控制

没有特别配置时，控制指令默认走小米云。如果你家里有小米中枢网关（固件 3.3.0_0023 及以上），或者买了内置中枢网关功能的米家设备（软件 0.8.9 及以上），就能启用本地控制，指令在局域网里直接到设备。

注意：中枢网关目前仅在中国大陆发售。其他地区可考虑开启"小米局域网控制"，但它只能控 IP 设备且官方明确不建议使用，后面避坑部分细说。

设备覆盖面：多账号、多地区都能收

• 支持大部分米家设备品类，只有蓝牙、红外、虚拟设备三类不在支持范围
• 导入后会自动生成对应实体：照明、开关、空调、传感器、风扇、加湿器、扫地机、窗帘、媒体播放器（电视盒子 v0.4.6 起支持）、热水器，以及 number/select/text/button 等
• 多个小米账号可以依次添加（集成页 → 添加中枢），不同账号、不同地区的设备都能放进同一个区域
• 云服务已部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个地区机房，配置时选自己的地区即可

13 种语言，实体名还能自己改

配置流程界面支持简体中文、繁体中文、英文、西班牙文、俄文、法文、德文、日文、意大利文、荷兰文、葡萄牙文、巴西葡萄牙文、土耳其文共 13 种语言。实体显示名会从小米云拉取厂商的多语言文件，嫌名字不好听？可以编辑本地的 multi_lang.json 覆盖翻译，它的优先级比云端文件高。

机制详解：双模式控制到底怎么工作

💡 这一节用大白话讲清楚两种控制通道的原理，看懂后你就知道"本地控制"和"局域网控制"为什么是两码事。

云模式：不轮询，消息推送到家

云端模式下，集成在小米云的 MQTT Broker（可以理解为云端的消息中转站）上订阅你关心的设备。设备属性一变或发生事件，云端立刻把消息推给集成，所以状态同步是实时的，而不是集成反复去问"你现在什么状态"。

好处是集成只在配置完成时向云端查询一次全部设备属性，之后几乎不产生查询压力。下发指令时则走小米云的 HTTP 接口，设备收到下行消息后执行并应答。

具体实现可以看 miot_cloud.py 和消息总线 miot_mips.py。

本地模式：中枢网关自带一个"消息中转站"

本地模式的原理和云模式几乎一样，只是中转站从云端搬到了你家：小米中枢网关内部内置了一个标准 MQTT Broker，实现了完整的订阅-发布机制。

• 上行：设备属性变化或事件发生时，消息发给中枢网关，由网关转发给 HA 里的集成
• 下行：集成要控制设备时，把指令发布到网关的 Broker，网关再转发给设备

整条链路不经过互联网，响应快、也更省隐私。

彩蛋：设备功能是怎么变成实体的

集成依据小米的 MIoT-Spec-V2 协议（小米给设备写的"功能说明书"）生成实体，规则大致是：

• 可写的布尔属性 → 开关；只读属性 → 传感器；带取值列表的可写属性 → 下拉选择
• 设备事件 → Event 实体（比如无线开关的"长按"）
• 设备方法 → 无参数的是按钮，有参数的是通知类实体，可传["Hello", true]这样的参数列表

不想生成某个功能的实体？在 spec_filter.yaml 里按设备 URN 过滤掉对应服务或属性即可，更多细节见 中文 README 的映射关系章节。

避坑指南：4 个踩坑高发场景

🚧 官方文档里藏着不少"默认不会发生"的前提条件，提前看一遍能省不少排查时间。

场景一：想开本地控制，发现"没生效"

现象：配置里找不到本地选项，或者开了也没变化。

解法：本地控制的硬前提是你得有小米中枢网关（固件 ≥ 3.3.0_0023）或带内置中枢网关的米家设备（软件 ≥ 0.8.9），且设备要能被发现（集成通过 mDNS 的 zeroconf 发现，见 miot_mdns.py）。另外中枢网关仅中国大陆有售，其他地区只能走云模式。

场景二：改了 multi_lang.json，实体名字纹丝不动

现象：编辑完 specs 目录 下的多语言或过滤文件，重启 HA 后实体名还是旧的。

解法：改文件不会自动生效。要到设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置里点一次"更新实体转换规则"，改动才会被读取。

场景三：图省事开了"小米局域网控制"，设备反而抽风

现象：部分设备偶发无响应、状态异常。

解法：官方 README 明确写了不建议启用这个功能——它只能控同一局域网内的 IP 设备（WiFi/网线连路由器的），蓝牙 Mesh、ZigBee 设备统统不管，还可能引发异常。而且只要局域网里有中枢网关，这个功能根本不会生效。所以：有中枢网关走本地模式，没有就安心用云模式。

场景四：担心账号安全问题

现象：听说集成登录小米账号，怕密码存在 HA 里。

解法：集成走的是 OAuth 2.0 授权流程，不保存你的小米账号密码。但要注意：登录成功后的用户信息（设备信息、证书、token）会明文存在 HA 的配置文件里，所以配置文件本身的保管很重要。万一怀疑 token 泄露，可以去 米家 APP → 我的 → 账号管理 → 应用授权，把 "Xiaomi Home (Home Assistant Integration)" 的授权撤掉，重新登录即可。

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