小米Home 接入教程
小米Home（Xiaomi Home）集成可以把你米家 / 小米账号下的智能设备接入 Home Assistant，登录账号、完成验证后即可把已适配的米家设备同步到 HA 中进行统一管理与控制。本文演示在冬瓜 HAOS 上接入「小米Home」集成的完整流程。
| 名称 | OS | Core | Xiaomi home |
|---|---|---|---|
| 版本 | 17.0 | 2025.2.1 | 0.4.7 |
在开始之前，请确认：
- 冬瓜 HAOS 默认已安装相关组件，如需更新可通过 HACS 操作更新程序。
- 已在「米家 / 小米」App 内将智能设备接入你的小米账号。
- HA 盒子、电脑和所有智能设备处于同一个局域网内（详细配置可参考「智能设备网络设置」文档）。
- 准备好你的小米账号（用于登录授权）。
说明：目前并不是账号下的所有设备都能完美适配，仅支持已在适配列表中的设备。
第 1 步：进入「设置 → 集成与服务 → 添加集成」
Section titled “第 1 步：进入「设置 → 集成与服务 → 添加集成」”在 Home Assistant 中依次进入 设置 → 集成与服务，点击右下角的 添加集成。
第 2 步：搜索 xiaomi home
Section titled “第 2 步：搜索 xiaomi home”在弹出的搜索框中输入 xiaomi home，点击搜索结果中的「小米Home（Xiaomi Home）」集成。
第 3 步：阅读并同意条款
Section titled “第 3 步：阅读并同意条款”勾选「我已悉知……」相关条款后点击 下一步；确认信息无误后再次点击 下一步。
第 4 步：开始登录小米账号
Section titled “第 4 步：开始登录小米账号”在登录页面点击「请点击此处进行登录」，进入小米账号登录界面。
第 5 步：登录小米账号
Section titled “第 5 步：登录小米账号”使用 账号密码登录 或 扫码登录 完成小米账号登录。登录成功后返回 HA 界面，确认显示的账号信息无误。
第 6 步：选择验证方式
Section titled “第 6 步：选择验证方式”在验证环节选择一种验证方式（如邮箱或手机短信）。
第 7 步：获取并填写验证码
Section titled “第 7 步：获取并填写验证码”点击 发送验证码，将收到的验证码填入输入框，点击 确定 完成验证。
第 8 步：必要时修改为 HA 设备 IP
Section titled “第 8 步：必要时修改为 HA 设备 IP”如果页面显示为空白（白色），说明使用的是 IP 登录方式。此时将浏览器地址栏中的 homeassistant.local 修改为你 HA 设备的实际 IP 地址。
第 9 步：确认认证成功
Section titled “第 9 步：确认认证成功”按回车键确认，等待页面显示「认证成功」的提示。
第 10 步：选择要导入的设备和同步模式
Section titled “第 10 步：选择要导入的设备和同步模式”返回 HA 界面，勾选需要导入的设备，并选择对应的同步模式。
第 11 步：完成导入
Section titled “第 11 步：完成导入”点击 下一步，系统会显示已适配的设备列表，接入完成。
注意：并非账号下的所有设备都能完美适配，最终以系统显示的已适配设备列表为准。
更新设备列表
Section titled “更新设备列表”当账号下新增了设备、需要重新同步时，可按以下 3 步更新：
第 1 步：进入集成配置
Section titled “第 1 步：进入集成配置”进入 Xiaomi Home 集成设置，点击齿轮 ⚙ 图标进入配置选项页面，按提示勾选相应选项后点击 下一步。
第 2 步：处理设备筛选
Section titled “第 2 步：处理设备筛选”如果之前进行过设备筛选，需勾选对应的筛选选项；如果未设置过筛选，直接点击 下一步。
第 3 步：提交保存
Section titled “第 3 步：提交保存”勾选「确认修改」复选框，点击 提交 按钮保存更新。
| 问题 | 解决办法 |
|---|---|
| 搜索不到 xiaomi home 集成 | 确认冬瓜 HAOS 组件已安装，可通过 HACS 更新后重试，或重启一次 Home Assistant 再搜索。 |
| 登录后页面显示空白（白色） | 这是 IP 登录方式，把地址栏中的 homeassistant.local 改为 HA 设备实际 IP 地址后回车，等待「认证成功」。 |
| 收不到验证码 | 确认所选验证方式（邮箱 / 手机）正确，重新点击「发送验证码」，注意验证码有时效。 |
| 部分设备没有导入 / 不可用 | 目前并非账号下所有设备都能完美适配，仅支持已在适配列表中的设备。 |
| 新增设备没有出现 | 进入集成设置点齿轮 ⚙ 重新走一遍「更新设备列表」流程并提交。 |
接入小米Home 的核心流程是：添加集成 → 搜索 xiaomi home → 同意条款 → 登录小米账号 → 验证码验证 →（必要时改 IP）认证成功 → 勾选设备并同步。完成后即可在 Home Assistant 中统一管理已适配的米家设备；后续新增设备可通过齿轮 ⚙ 进入配置更新设备列表。