3步把米家设备接入 Home AssistantXiaomi Home 集成从安装到自动化实战指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home凌晨三点家里空调还开着你只能坐在床上盯着手机米家 APP 一顿操作。这种设备都在一个生态里中枢却在另一个 APP的割裂感用一次米家官方支持的 Home Assistant 集成组件Xiaomi Home米家集成项目代号 xiaomi_home就能解决小米账号一登录全屋米家设备变成 Home Assistant 里的实体自动化、场景、HomeKit 随便折腾。5分钟跑起来先看最短路径装完再说原理打开 Home Assistant 终端Supervisor → 终端执行下面两条命令完成安装并重启cd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config在 Home Assistant 界面进入设置 → 设备与服务 → 添加集成搜索Xiaomi Home。勾选风险告知选择登录地区在米家 APP「我的 → 更多设置 → 关于米家」可查和界面语言。点击登录链接在弹出的小米账号页面完成OAuth 2.0 授权。在「选择家庭与设备」页勾选要导入的家庭确认。设备开始逐个出现在「设备」列表里。看到灯、开关、传感器出现在仪表盘上就算跑通了。它到底能帮你做什么一句话把米家设备翻译成 Home Assistant 原生实体让你用 HA 的自动化引擎去驱动小米生态。对比维度Xiaomi Home 集成第三方米家集成只用米家 APP维护方小米官方支持个人开发者官方但封闭本地控制中枢网关 MQTT 全协议多为局域网单设备无中枢概念多账号支持可混排同区域通常单账号手动切号协议覆盖支持米家大部分品类看作者支持进度全品类官方 OAuth 登录不存你的账号密码授权链路由小米官方接口完成。云端 本地双模控制有小米中枢网关时指令走局域网 MQTT没有则自动回落云端。多账号同区管理不同小米账号的设备能放进同一个 HA 区域老房子和新家分开管也没问题。设备筛选按房间、接入类型、型号包含/排除数百台设备也能只导入你关心的那几台。13 种界面语言配置流程和实体名都支持中文界面由开发者人工校对过。环境与安装兼容性门槛先自查Home Assistant Core ≥ 2024.4.4设置 → 系统 → 关于可查看Operating System ≥ 13.0地区要求中国大陆、欧洲、印度、俄罗斯、新加坡、美国各地云端数据隔离登录时要选对地区跑在 Docker 里的 HA 需使用host 网络模式否则本地控制功能会异常方式一git clone 安装推荐技术向用户cd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config优点是升级/回退方便git checkout v0.4.7再跑一次./install.sh /config就能切到任意版本当前版本见 custom_components/xiaomi_home/manifest.json。方式二HACS 一键安装适合纯新手在 HACS 搜索框输入Xiaomi Home进入详情页点 DOWNLOAD然后重启 HA。装完执行一条命令验证看到 manifest.json 的路径输出就说明文件已就位ls /config/custom_components/xiaomi_home/manifest.json配置详解基础配置全在图形界面里走一共 4 步风险告知勾选同意集成声明用户信息会存在本地责任在你保管配置文件。基础配置填登录地区、集成语言、OAuth 认证跳转地址默认http://homeassistant.local:8123首次添加建议勾选「集成网络配置」做网络自检。选择家庭与设备勾选家庭并设置「房间名同步模式」——选以房间命名后米家里的房间会直接映射成 HA 的区域。完成导入设备开始同步数量多时首次导入需要几分钟别刷新页面。高级配置怎么开入口在设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置控制模式自动有中枢网关优先走本地没有才走云端或云端强制走小米云。筛选设备按房间/接入类型/型号做包含或排除支持「与/或」统计逻辑。Action 调试模式给带参数的设备方法额外生成一个文本输入实体方便手动发指令调试。更新局域网控制配置选网卡后可让集成在云端和中枢都不可用时尝试局域网直控仅支持同网段 IP 设备2020 年之前的旧设备可能不支持官方不推荐开启。配置项对应的存储示例只列关键字段完整内容在 HA 的.storage目录里{ cloud_server: 中国大陆, // 登录地区决定连哪个地区的小米云 ctrl_mode: auto, // 控制模式auto 优先本地cloud 仅云端 nick_name: 我的昵称, // 用户昵称用于设备命名前缀 devices_filter: null // 设备筛选规则null 表示全量导入 }更多字段含义和实体转换规则可查 doc/README_zh.md 和 CHANGELOG.md。技术原理速览控制链路分两条选哪条取决于你有没有中枢网关。云端控制集成向小米云的 MQTT Broker 订阅设备消息。设备属性一变云上的 Broker 就主动推送给集成不用轮询下发指令则走小米云 HTTP 接口。也就是说状态更新是推过来的延迟主要来自互联网往返。本地控制小米中枢网关固件 ≥ 3.3.0_0023或内置中枢的设备软件 ≥ 0.8.9自带一个标准 MQTT Broker订阅和下发全在局域网内完成断网也不受影响。怎么选有中枢网关就选自动日常走本地、网关掉线自动回落云端没有中枢、又需要偶尔远程控一下的用云端最省心只把 HA 当本地面板且全是 IP 直连设备的再考虑局域网控制。实战自动化设备进来了下面三个场景可以直接抄。如果你想要回家自动开灯思路手机作为 device_tracker 进入家门区域触发客厅灯开。alias: 回家开灯 trigger: - trigger: zone zone: zone.home entity: device_tracker.your_phone event: enter condition: [] action: - action: light.turn_on target: area_id: living_room mode: single如果你想要人走了自动关灯思路客厅人体传感器 10 分钟无人关掉客厅所有设备用area_id一次清场。alias: 离开自动关灯 trigger: - trigger: state entity: sensor.living_room_motion to: off for: minutes: 10 action: - action: homeassistant.turn_off target: area_id: living_room mode: single如果你想要湿度太低自动加湿思路传感器读数低于 40% 就打开加湿器高于 60% 再关。alias: 自动加湿 trigger: - trigger: numeric_state entity: sensor.bedroom_humidity below: 40 action: - action: switch.turn_on target: entity_id: switch.humidifier mode: single设备事件类实体门窗、按键长按等由 MIoT-Spec-V2 的 Event 转换而来可直接当trigger.event用详见 doc/README_zh.md 的「MIoT-Spec-V2 与 Home Assistant 实体的映射关系」一节。安全与隐私这四条必须做保管好 HA 的 config 目录。OAuth 流程不保存密码但登录后的设备信息、证书、token 会明文存在配置文件中文件泄露等于交出全屋设备的控制权。给小米账号开启两步验证并定期在「米家 APP → 我的 → 账号管理 → 应用授权」里检查Xiaomi Home (Home Assistant Integration)这条授权是否还在。怀疑 token 泄露时直接在小米账号授权页移除该应用授权集成会立即失效重新走一遍 OAuth 即可。把 HA 限制在内网访问不要直接把 8123 端口暴露公网。进阶建议把 IoT 设备划到独立 VLANHA 走固定 IP路由器上限制米家设备互访。用git tag锁定集成版本升级前先看 CHANGELOG.md避免盲目跟版。敏感设备门锁、摄像头的自动化只挂本地控制链路减少云端依赖面。问题速查连接与登录类症状登录页面转完圈没反应 → 排查① 确认操作终端和 HA 在同一局域网且能访问http://homeassistant.local:8123② 登录地区选错会导致拿不到设备对照米家 APP 核对③ 点「下一步」重试一次仍失败就重新发起 OAuth。症状认证信息过期集成掉线 → 排查① 进集成页点「配置」→「更新用户信息」重新认证② 检查小米账号是否改过密码或被踢下线。症状提示该用户已配置完成 → 这是正常拦截一个账号只能配一次去已配置列表里改选项。设备与实体类症状设备没同步过来 → 排查① 确认设备在米家 APP 里本身能正常工作② 蓝牙、红外、虚拟设备不在支持范围内③ 进「配置 → 更新设备列表」重选家庭检查是否被设备筛选条件排除了。症状实体名字带星号*→ 说明该实例来自厂商自定义命名空间而非小米标准规范属于正常现象可在高级选项里隐藏非标准实体。控制响应类症状指令明显偏慢 → 排查① 确认局域网内有中枢网关且固件 ≥ 3.3.0_0023② 控制模式设为「自动」③ 看日志确认指令是否走了云端。症状开了局域网控制却不生效 → 排查① 局域网里若存在中枢网关局域网控制会让位属预期行为② 确认选对了网卡③ 被控设备需是支持 MIoT-Spec-V2 的 IP 设备。症状关键词大概率原因处理无法访问 OAuth2 认证地址网络不通或地区选错配置网络检测自定义地址中枢网关模式报错局域网无可用中枢换控制模式为「云端」实体转换不生效本地规则文件改了没刷新配置 → 更新实体转换规则收束回到开头那个场景空调不用半夜爬起来关了「离开自动关灯」和「回家开灯」挂上去之后你只需要在出门时锁门剩下的交给 HA。整套体验的核心就两点——设备是官方链路同步的控制有本地兜底。下一步建议先搭一个「回家开灯」自动化跑三天确认实体和区域命名都顺手再考虑把中枢网关的本地控制打开。遇到问题先看 doc/README_zh.md 的常见问题章节再去看项目仓库的 Issue 讨论集成风险告知里也写了这类问题向开源社区求助比联系小米客服更有效。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考