米家设备接入 Home Assistant：一步步搭好下班回家自动化-育师

米家设备接入 Home Assistant：一步步搭好下班回家自动化

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

晚上七点，你刚进单元门，玄关灯已经亮起，客厅空调正吹着 24 度的风——这不是巧合，而是你提前用 Home Assistant 的 Xiaomi Home 集成串起来的一条自动化链路。本文会带你把这条链路从 0 搭到能跑通：先理清接入米家设备要满足的条件，再选一条合适的安装路径并登录导入设备，然后看懂你的米家设备会变成哪些实体，最后按"触发 → 执行 → 验证"把下班回家场景写出来、跑起来。

先搭好地基：Home Assistant 版本与接入条件

在动手之前，先把两个硬性条件对齐，避免装完发现跑不起来：

项目	要求	为什么重要
Home Assistant Core	≥ 2024.4.4	低于此版本，集成的实体与配置流程不兼容
Operating System	≥ 13.0	运行集成的系统底座，影响网络与本地控制能力
Xiaomi Home 集成	已安装	米家设备进入 HA 的唯一入口

除了软件版本，控制方式还和硬件有关：你手里有没有小米中枢网关，决定了后面"控制指令走哪条路"那一节的选项。没有中枢网关也能玩，只是默认走云端。

米家设备的三条安装路径怎么选

安装方式按你对版本管理和操作习惯的偏好来挑，三条都能装好，差别在于后续升级方便程度。

安装路径	适合谁	特点
Git 克隆（推荐）	想要版本可控、方便升级	切 Tag 即可回到指定版本，适合进阶用户
HACS 一键安装	新手	在 HACS 里搜`Xiaomi Home`下载即可
手动复制	不方便用前两者	把`custom_components/xiaomi_home`拷进`config/custom_components`

如果你选 Git 克隆，进入 Home Assistant 的config目录后执行下面的命令即可，装完重启一次：

cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config # 脚本会把组件复制到 config 下并提示重启

想固定到某个版本时，进config/ha_xiaomi_home执行git checkout <版本号>再跑一次./install.sh /config就行，这正是 Git 方式比手动复制省事的地方。

登录账号并导入米家设备

装好后走一遍登录流程，让米家设备进入 HA。整个过程是 OAuth 2.0 授权，不会在 HA 里保存你的小米密码，但登录后的账号与设备信息会存在 HA 的配置文件里，所以要保管好这个配置文件。

打开设置 > 设备与服务 > 添加集成，搜索Xiaomi Home并进入。
基础配置页选择登录地区（小米账号所在地区）和语言，首次添加建议勾选集成网络配置做连通性检测。
按页面提示点击登录，用小米账号完成授权。
在"选择家庭与设备"弹窗里勾选要导入的家庭，该家庭下的设备会随之进来到 HA。

这里有两个容易踩的点，先说清楚：

登录地区要和你在米家 APP 里看到的账号地区一致，选错会取不到设备。
若用 Docker 部署 HA，网络模式要设成host，否则本地控制功能会异常。

控制指令走哪条路：自动、云端、本地对比

米家设备最终能不能"听你的话"，取决于控制指令从哪条通道发出去。在集成配置里有控制模式选项，理解它比记住某个开关更重要。

模式	指令路径	适用场景
自动	优先本地中枢网关，其次小米 OT 协议，都不行再落回云端	有中枢网关，想要低延迟又不想手动切换
云端	全程经小米云	无中枢网关，或设备跨网络分布

云端控制是默认且覆盖面最广的方式：集成向小米云的 MQTT Broker 订阅设备消息，状态变化或事件发生时由 Broker 主动推给 HA，不需要反复轮询；控制指令则走小米云 HTTP 接口下发。好处是不挑网络环境，代价是每次都要出一次外网。

本地控制依赖局域网里的小米中枢网关（固件 ≥ 3.3.0_0023），或内置中枢网关功能的设备（软件 ≥ 0.8.9）。中枢网关里跑着一个标准 MQTT Broker，HA 直接向它订阅消息、发布控制指令，指令不经过云端，响应更快、也更抗网络波动。

需要单独说明的是局域网控制：在集成的配置 > 更新局域网控制配置里可以开启。它只控制与 HA 同网段的 IP 设备（WiFi 或网线接入），管不了蓝牙 Mesh、ZigBee 设备，而且官方并不建议常开，容易引入异常。如果网段里已有中枢网关，即便开启了它也不会生效。对多数人来说，直接用"自动"或"云端"就足够了。

写自动化前：米家设备变成哪些 Home Assistant 实体

很多人卡住的地方不是写 YAML，而是不知道手里的设备在 HA 里叫什么。集成按 MIoT-Spec-V2 协议把设备的属性、事件、方法翻译成实体，看懂这张表，你才知道自动化里target该填什么。

MIoT-Spec-V2 元素	转换后的实体
可写 + bool 属性	Switch
可写 + string 属性	Text
可写 + 有取值列表的属性	Select
可写 + 有取值范围的属性	Number
只读属性	Sensor
事件	Event
方法（无入参）	Button
方法（有入参）	Notify

除了通用规则，还有一套特殊转换：设备或服务名命中特定映射时会直接变成对应的平台实体，比如带air-conditioner服务的设备会落到 climate 平台，light服务变成 light 实体，curtain服务变成 cover 实体。这些映射都定义在实体转换规则里，遇到不认识的实体名，翻这里能对上。

一个直观的例子：一台带空调服务的设备，你会在 HA 里得到一个climate实体，mode、target-temperature这些可写属性分别对应它的模式与温度设定；而只读的室内温度会变成一个sensor。自动化里调空调，调的就是这个climate实体，而不是某个switch。

下班回家自动化怎么写：触发、执行、验证三步

前面所有铺垫，都是为了把下面这条链路跑通。我们把它拆成触发、执行、验证三段，一段一段来。

触发：用"手机到家"或"门锁打开"作为信号。手机位置触发靠设备触发器，门锁则用状态触发器监听一个binary_sensor：

alias: 下班回家 trigger: - trigger: device # 手机进入"家"区域时触发 device_id: your_phone_device_id domain: device_tracker type: enters zone: zone.home - trigger: state # 门锁打开（on）时触发 entity_id: binary_sensor.door_lock to: "on"

执行：加一个时间条件，限定傍晚到夜间才生效，再按顺序点亮设备。mode: single保证上一次没跑完时不会叠加触发：

condition: - condition: time # 只在 17:00–23:00 之间执行 after: "17:00" before: "23:00" action: - service: switch.turn_on # 开玄关灯 target: entity_id: switch.entrance_light - service: climate.set_temperature # 空调设到 24 度 target: entity_id: climate.living_room_ac data: temperature: 24 mode: single

验证：保存后别急着等它"自然发生"。手动把手机切到家里区域、或临时把门锁状态改成on，观察设备是否按预期响应；再点开这条自动化的"运行历史"，确认触发、条件、动作每一步都通过了。这一步能帮你区分"没触发"和"触发了但动作失败"两类完全不同的问题。

按天气调温度、控制执行节奏两个进阶技巧

基础链路跑通后，可以按季节把温度设得 smarter。用choose结构，根据室外温度传感器挑不同的空调动作：

action: - choose: - conditions: # 室外很热时制冷 - condition: numeric_state entity_id: sensor.outside_temperature above: 28 sequence: - service: climate.set_temperature target: { entity_id: climate.living_room_ac } data: { temperature: 24 } - conditions: # 室外偏冷时制热 - condition: numeric_state entity_id: sensor.outside_temperature below: 15 sequence: - service: climate.set_temperature target: { entity_id: climate.living_room_ac } data: { temperature: 22 }

如果多个动作之间你希望留出间隔（比如先开灯、停几秒再启动空调），在动作里插一段delay即可：

action: - service: switch.turn_on target: { entity_id: switch.entrance_light } - delay: seconds: 5 # 开完灯停 5 秒再继续 - service: climate.set_temperature target: { entity_id: climate.living_room_ac } data: { temperature: 24 }

一个家庭、多个小米账号怎么管理

设备分散在不同小米账号下时，不用迁就谁，把几个账号都接进来就行。在一个账号配置完成后，回到设置 > 设备与服务 > 已配置 > Xiaomi Home，点添加中枢，再登录另一个小米账号，选要导入的设备即可。不同账号的设备可以放进同一个 HA 区域统一管理。

导入设备多时，可以在"配置 > 更新设备列表"里用筛选设备按房间、接入类型、型号做包含/排除，避免无关设备进自动化候选池。相关流程见配置流程实现。

自动化不生效先查这几处

出了问题别从头重装，按下表从最可能的地方查起：

症状	优先排查
设备无响应	在集成页面看设备是否在线；用本地控制时确认设备与 HA 同网段
自动化不触发	检查触发条件（位置/时间/门锁状态）是否真的满足；到"开发工具 > 状态"核对实体 ID 是否正确
状态不同步	在配置 > Action 调试模式里开一个文本实体，手动给设备发指令，确认是通信问题还是同步延迟
改了多语言或过滤文件没生效	回到配置 > 更新实体转换规则执行一次更新，多语言字典见 multi_lang.json

查日志时重点看config/home-assistant.log，集成的日志标识是Xiaomi Home，能帮你快速定位是认证、网络还是设备层的问题。