ha_xiaomi_home 上手指南3 步把小米智能家居设备接入 Home Assistant【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_home 是小米官方开源的 Home Assistant 集成组件它能把你米家 APP 里的小米智能设备灯、空调、扫地机器人、传感器等直接搬进 Home Assistant实现统一的控制与自动化。只要你有一台运行中的 HA 和一个小米账号跟着本文走十几分钟就能看到自己的设备出现在 HA 面板里。开始之前先确认这 3 个前置条件在动手安装前花一分钟核对一下Home Assistant 版本达标Core ≥ 2024.4.4如果是 HAOS 安装版本需 ≥ 13.0。进入设置 → 系统 → 关于即可查看当前版本。准备一个小米账号就是你平时登录米家 APP 的那个账号登录过程中会用到。知道设备所在的米家家庭登录成功后要按家庭维度导入设备提前确认设备挂在哪个家庭下。另外安装途径可以三选一git clone 手动部署、HACS 社区商店一键安装、或者直接复制组件文件。下面按推荐顺序逐个说。安装 ha_xiaomi_home三种方式哪一步最容易卡住方式一git clone 部署官方推荐最灵活这种方式的好处是后续升级方便——想换哪个版本切一下 Tag 即可。把仓库拉到 Home Assistant 的 config 目录下git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home进入仓库目录运行仓库自带的 install.sh 脚本把 HA 的 config 路径作为参数传入即可。这个脚本只干一件事把组件复制到 HA 的custom_components/目录下无需你关心细节。看到安装完成提示后重启 Home Assistant。⚠️ 最容易卡住的点如果 HA 跑在 Docker 里请确认容器网络模式是host否则本地控制相关功能会异常。方式二HACS 一键安装最省心如果你的 HA 已装好 HACS 商店操作只有三步打开 HACS → 搜索框输入Xiaomi Home→ 进入详情页点击下载。组件的 hacs.json 里写明了最低 HA 版本要求是 2024.4.4与方式一完全一致。装完同样需要重启一次 HA。方式三手动复制文件兜底方案不方便用 git 或 HACS 时可以把仓库里的custom_components/xiaomi_home整个文件夹通过 Samba、FTP 等方式复制到 HA 的config/custom_components目录下然后重启 HA。完成安装后打开设置 → 设备与服务如果能搜到 Xiaomi Home说明组件已经就位。首次配置登录小米账号 → 选家庭 → 导入设备这是整条流程里唯一需要动脑的环节跟着点即可添加集成设置 → 设备与服务 → 右上角添加集成搜索Xiaomi Home点击进入。选择登录地区按提示选择小米账号所在地区中国大陆、欧洲、印度、俄罗斯、新加坡、美国六选一。不确定选哪个的话可以在米家 APP 的我的 → 更多设置 → 关于米家里查看。完成 OAuth 登录页面会给出一个跳转地址通常是http://homeassistant.local:8123在浏览器打开它用小米账号登录并授权。此时你的操作电脑需要和 HA 在同一局域网且能访问 HA 首页否则认证会失败。选择家庭与设备登录成功后会弹出选择家庭与设备对话框选中你的设备所在家庭该家庭内的设备就会全部导入 Home Assistant。填写昵称并提交确认配置摘要昵称、语言、设备数量等点击提交集成会自动重新载入。⚠️ 设备较多的用户注意如果米家里有数百台设备首次导入会明显慢一些耐心等它跑完即可。导入完成后去设置 → 设备与服务 → 设备页面翻一翻你的小米设备应该已经整整齐齐地出现在 HA 里了可以直接拖进自动化使用。常用设置配置选项里值得动的几项在设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置中有几个选项新手阶段就可能用得上用户昵称登录时默认取账号名觉得太长可以改成自己喜欢的称呼。更新导入的设备列表米家 APP 里新加或删了设备在这里点一下重新选择家庭与设备就能同步。集成语言支持简中、繁中、英、日、德、法、西、俄等 13 种语言实体名称会跟着变化。Action 调试模式开启后会给带参数的设备方法额外生成一个文本输入实体方便你手动发指令测试日常使用可以关掉。如果你家里有多个小米账号比如夫妻各一个在集成页面点添加中枢即可登录第二个账号两个账号的设备还能放进同一个 HA 区域。接入原理一图看懂云端控制 vs 本地控制导入成功后你的设备默认是通过小米云收发消息的集成向小米云订阅设备状态变更属性变化、事件、上下线控制指令则走云端 HTTP 接口下发整体延迟在多数场景下可接受。如果你家里有小米中枢网关固件 3.3.0_0023 及以上或者设备自带中枢网关功能软件 0.8.9 及以上集成会自动切换成本地控制模式消息经由网关内置的 MQTT Broker 直接收发不依赖外网响应更快。需要注意的是小米中枢网关目前仅在中国大陆地区可用海外用户可以关注官方说明或了解集成提供的局域网控制功能仅支持同局域网的 IP 设备官方建议非必要时不要开启。常见问题 FAQQ1我的设备没同步过来怎么办先确认三件事① 登录时选的地区和小米账号实际地区一致不同地区云端数据隔离② 设备属于你选择导入的那个家庭③ 该设备品类是否受支持——目前蓝牙设备、红外设备、虚拟设备暂不支持其余绝大多数品类都可以。Q2登录认证失败、跳转地址打不开登录走 OAuth2 跳转你的操作电脑必须和 HA 在同一局域网且浏览器能访问homeassistant.local:8123。打不开的话检查 DNS 是否解析了.local域名或改用 HA 的局域网 IP。另外 Docker 部署的用户请确认网络模式为host。Q3设备数量很多第一次导入特别慢正常吗正常。数百台设备的用户首次加载会花一些时间集成只在配置完成时全量拉取一次属性之后靠消息订阅推送不会持续给云端制造压力。Q4能同时登录多个小米账号吗可以。第一个账号配完以后在集成页面点添加中枢继续登录其他账号即可多账号设备可以归入同一个区域。Q5安全方面有没有要注意的登录采用 OAuth 2.0HA 不保存你的小米账号密码。但登录成功后账号的设备信息、证书、token 会明文存放在 HA 的配置文件中所以请保管好配置文件若怀疑令牌泄露可到米家 APP 的账号授权管理里取消对集成的授权。仓库资料速览想深入了解或参与贡献这几个入口值得收藏中文说明文档安装、实体映射规则、多语言支持等完整内容更新日志每个版本新增与修复了什么升级前可先扫一眼贡献指南中文版提交 Issue 和 PR 的规范hacs.jsonHACS 元数据含最低版本要求组件源码集成主入口与全部实体类型核心逻辑在miot/子目录云端控制示意、本地控制示意英文版架构图方便对照阅读按上面安装 → 登录 → 选家庭三步走一遍你的小米智能家居就已经是 Home Assistant 的一部分了。接下来不妨试着写一条自动化让米家的灯和 HA 里的场景联动起来。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考