企业官网建设流程全解析

把米家设备装进 Home Assistant：米家集成完整指南

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

你喊过"小爱同学，关灯"，却没让 Home Assistant 听懂吗？Home Assistant 米家集成（项目名 ha_xiaomi_home）就是干这一件事的：把你米家账号下的设备接进 Home Assistant，让它们能被自动化、场景和语音助手统一调度。它由小米官方支持，设备状态走消息订阅推送，不是笨办法式的定时轮询；登录用 OAuth 2.0，集成本身不保存你的账号密码。

一句话：它解决的是"米家设备散落在米家 App 里，进不了 HA 自动化"这个真实痛点。

从 0 到跑通：装好并接入第一台设备

先花 30 秒确认版本

在 Home Assistant 的"设置 → 关于"里看两处：Core 版本要 ≥ 2024.4.4，操作系统版本要 ≥ 13.0。不达标就先升级，后面所有步骤都建立在它之上。

拿到代码，装进 config

登录 Home Assistant 的终端，按顺序执行：

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下，并自动清掉旧版本。装完重启 Home Assistant。

以后想固定到某个版本，也不用重新下载：

cd /config/ha_xiaomi_home git fetch git checkout v1.0.0 ./install.sh /config

不想折腾 git 的话还有两条路：HACS 社区商店里搜 "Xiaomi Home" 一键下载；或者手动把custom_components/xiaomi_home整个文件夹拷进config/custom_components。

登录并勾选设备

重启后走一遍配置流程：设置 → 设备与服务 → 添加集成 → 搜Xiaomi Home→ 用小米账号授权登录 → 在"选择家庭与设备"弹窗里勾选要导入的家庭 → 完成。几十秒后，设备就会以 HA 原生实体的形式出现在你的系统里。

能力版图：它到底能做什么

先看一张横向对比，再列清单。

再补一份能力清单：

• 米家设备按 MIoT-Spec-V2 规范自动转成 HA 实体：传感器、开关、灯、空调、风扇、窗帘、扫地机、取电、热水器、媒体播放器等，平台目录见 custom_components/xiaomi_home/。
• 多账号：不同小米账号的设备可以放进同一个 HA 区域，互不干扰。
• 跨地区：云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六地，数据按地区隔离，导入时选对地区即可。
• Action 调试模式：给带参数的指令开一个文本实体入口，方便手动发指令做调试。
• 配置入口：改昵称、重新同步设备列表、开调试模式，都在"设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置"里。

更多细节（含 MIoT-Spec-V2 到 HA 实体的映射规则）见官方说明 doc/README_zh.md。

云端还是本地：两种控制模式的工作原理

把云端控制想成"打电话给中转站"：你的指令先发到小米云，云再转给设备；设备状态变化也先上报到云，云再推给你。它的好处是不挑设备、不挑地区，坏处是离不开网。

本地控制则像"直接按手里的遥控器"：小米中枢网关里自带一个标准 MQTT Broker，集成直接连它，订阅和下发都发生在你的局域网内，不绕公网。断网的时候，这条链路照样工作。

两个关键事实：

• 真正的本地控制依赖中枢网关。需要小米中枢网关（固件 3.3.0_0023 及以上）或内置中枢网关的米家设备（软件 0.8.9 及以上）。中枢网关目前仅在中国大陆销售；海外地区没有网关可用，就默认走云端。
• 没有网关时指令全部经小米云下发；有网关时，本地链路优先生效。

还有个"局域网控制"开关，只覆盖同局域网内走 WiFi/网线的 IP 设备，管不到蓝牙 Mesh、ZigBee 设备，且官方明说它可能引发异常、不建议开启。能用中枢网关就别用它。

什么时候选哪种？

场景化玩法：让设备替你想着做

接入之后，米家设备就是普通的 HA 实体，下面这些玩法都能直接写进自动化。

回家模式

手机回到家里区域，触发客厅灯。给条件加一道光照度判断，白天就不亮灯，避免大中午也开灯：

alias: 回家开灯 trigger: - platform: zone zone: zone_home entity_id: device_tracker.你的手机 event: enter condition: - condition: sun after: sunset action: - service: light.turn_on target: entity_id: light.客厅灯

离家安防

离家时一键关灯关电器，扫地机出门开工：

alias: 离家清理 trigger: - platform: zone zone: zone_home entity_id: device_tracker.你的手机 event: leave action: - service: homeassistant.turn_off target: area_id: living_room - service: vacuum.start

门窗传感器、人体传感器接入后会变成 HA 的传感器/事件实体，直接写进触发条件即可：门窗打开 + 离家状态 → 推送通知。

照明随天走

用太阳位置做触发，日出前调亮、日落后转暖，模拟自然光过渡。传感器读数（光照、色温）都是实体，自动化里拖一下就能用。

环境监测联动

温湿度传感器、PM2.5 传感器接入后，阈值判断就是普通条件：

alias: 太干就加湿 trigger: - platform: numeric_state entity_id: sensor.卧室湿度 below: 40 action: - service: switch.turn_on target: entity_id: switch.加湿器

去年冬天那种"出差忘了关加湿器"的情况，现在交给自动化兜底就行。

安心使用：安全与避坑

先把安全说清楚

• 登录走 OAuth 2.0，集成不保存你的小米账号密码，这一点可以放心。
• 但登录成功后，设备信息、证书、token 会明文存在 Home Assistant 的配置文件里（平台限制，改不了）。所以真正要守的是/config目录本身的权限，别把它暴露给不该看的人。
• 怀疑授权泄露时，去米家 App → 我的 → 用户名 → 应用授权里，把 "Xiaomi Home (Home Assistant Integration)" 的授权撤掉，重新配一遍即可。
• 多账号场景下，每个账号都单独授权，定期回 App 里看一眼授权列表是好习惯。

常见问题速查

写在最后

Home Assistant 米家集成把"米家设备进不了 HA"这件事补齐了：双通道控制、多账号、原生实体、消息推送，都是官方在维护的。

现在就动手吧：按"从 0 到跑通"那节装好，挑一盏你最常用的灯接入，写出第一条"回家开灯"自动化。剩下的，交给时间。

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