十分钟把小米智能家居接入 Home Assistant设备统一管理 本地控制完整教程【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home小米设备散落在米家 App 里想进 Home Assistant 做统一管理和自动化却不知道从哪下手ha_xiaomi_home是小米官方开源的集成组件负责把小米智能家居设备接入 Home Assistant——灯光、传感器、家电统统变成 HA 里可触发、可控制的实体而且支持云端和本地两种控制模式。一、先做选型云端控制还是本地控制结论先行家里有小米中枢网关且 HA 和网关在同一网络优先选本地控制没有网关或需要出门远程控制选云端控制。两种模式的差异一张表看清对比维度云端控制本地控制通信链路HA → 小米云MQTT 推状态 HTTP API 发指令→ 设备HA → 小米中枢网关局域网内 MQTT→ 设备响应速度要走公网延迟受网络状况影响局域网直达响应更快外部依赖小米云服务需要稳定外网一台小米中枢网关硬件远程场景出门在外也能控制仅限局域网内前置条件小米账号即可国内服务器账号 中枢网关且 HA 与网关同局域网适合谁没有网关、或有远程控制需求家庭网络稳定、追求速度和隐私先看云端控制的通信路径再看本地控制所有状态与指令都在局域网内完成不经过公网 两个决策口径选本地控制你已购买小米中枢网关HA 部署在家里同一网络日常控制都发生在屋内。选云端控制没有网关、设备分散在不同地方、或者你习惯在出差时用手机联动家里的设备。不确定也没关系——集成支持自动模式检测到条件满足时会自动走本地链路配置阶段可以直接选默认值之后随时改。二、十分钟落地从拿到代码到面板可见2.1 环境检查开始之前确认三件事Home Assistant 版本在 2023.12 及以上你要接入的小米设备已在米家 App 中完成配网并处于在线状态终端里能访问小米云服务地址国内账号对应国内云海外账号对应海外云。2.2 克隆项目代码git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home2.3 运行安装脚本cd ha_xiaomi_home bash install.sh /path/to/homeassistant/config把/path/to/homeassistant/config换成你 HA 的实际配置目录。脚本会校验路径是否存在然后自动清理旧版本、把xiaomi_home组件完整复制到配置目录下的custom_components中最后提示你重启。升级也是同一条命令脚本会先删掉旧组件再覆盖新文件。遇到权限报错时在命令前加sudo重试即可。2.4 确认组件出现在面板重启 Home Assistant进入设置 → 设备与服务能看到Xiaomi Home集成落地就算完成。整个过程顺利的话不到十分钟。三、授权与设备入网小米账号登录怎么过3.1 账号授权在设备与服务里点添加集成搜索Xiaomi Home配置流程由 config_flow.py 定义全程向导式操作页面会给出一个登录链接点击后跳转到小米账号登录页登录成功自动跳回最容易卡住的一点如果你的账号开启了双重验证输入密码后要立刻填写短信验证码别让登录页停留超时否则授权会中断需要重新发起授权过程中 HA 会做一次网络自检确认 OAuth 认证地址、小米 HTTP API 等地址可达。如果你的网络无法直连小米云可在集成的网络检测配置里设置代理或自定义检测地址。3.2 选择家居分组与设备发现授权成功后集成会拉取你米家 App 里的家居列表选一个所在分组即可——该分组下所有已配置的设备会被自动发现并批量创建为 HA 实体不需要逐台配网。3.3 选定控制模式继续走完向导时选择第一节里定好的控制模式自动 / 云端 / 本地。国内服务器账号 中枢网关的组合下本地模式才可选项选错了也没关系之后可以在集成的重新配置里随时切换。四、把设备调成你想要的样子 设备进来了接下来按自己的习惯微调。4.1 命名与房间分组集成默认按米家的房间信息给实体分组归位区域命名规则为 room。想调整命名规则、控制模式或集成显示语言走一遍设置 → 设备与服务 → Xiaomi Home → 重新配置就行不用删了重来。4.2 状态同步机制设备状态不是轮询来的而是通过 MQTT 通道以properties_changed、事件和在线/离线消息实时推送正常情况下无需手动调频率。如果怀疑链路异常可以先看 miot_network.py 里的网络检测与超时相关设置确认 HA 到目标地址的连通性。4.3 多语言显示集成自带简体中文、英文等 13 种语言文件存放在 translations/。想本地化界面上的某些措辞参考对应语言文件即可。4.4 接上自动化这是接入 HA 的最大收益在设置 → 自动化里把小米设备当成普通实体使用。比如门窗传感器触发 → 打开客厅灯并推送通知空调温度越过阈值 → 动作关闭。触发条件和动作都可以直接在 HA 编辑器里拖出来不需要碰任何代码。五、遇到问题对号入座现象可能原因处理动作设备没被发现① 设备未在米家 App 中完成配网或已离线② 本地模式下 HA 与中枢网关不在同一局域网③ 账号服务器区域与设备不匹配先查米家 App 里设备是否在线确认网关在线且与 HA 同网段必要时用正确云服务器重新添加一次集成控制延迟高或指令失败① 云端模式遇公网波动② 本地模式网关掉线或未启用③ 设备固件过旧有网关就切到本地模式检查 miot_network.py 中的超时与网络检测设置把设备固件升级到最新版设备状态不更新① MQTT 状态推送通道异常② 集成未完整加载在 设置 → 设备与服务 → Xiaomi Home 里重新加载集成用开发者工具 → 状态检查对应实体属性翻日志确认有无鉴权或网络报错写在最后走到这里你的小米设备已经从米家 App 搬进了 Home Assistant每一盏灯、每一个传感器都成了自动化的积木块。想深入理解局域网直连的实现细节可以读 test/test_lan.py 里的单元测试发现 bug 或想加新特性照着 CONTRIBUTING.md 参与开发就是下一步。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考