小米米家设备接入 Home Assistant 完整指南Xiaomi Home 集成安装、配置与双通道控制教程【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_homeXiaomi Home 集成是小米官方支持的 Home Assistant 组件用于把小米米家设备接入 Home Assistant让灯、插座、温湿度计、空调伴侣等设备进入同一个自动化平台统一调度。这篇指南覆盖安装、小米账号授权、云端与本地两种控制通道的配置方法以及常见故障的排查思路适合第一次做小米米家设备接入 Home Assistant 的新手。接入小米米家设备后Home Assistant 里能跑起来哪些自动化场景先看看装好之后能做什么。傍晚你推开门回家门磁传感器上报状态变化Home Assistant 自动点亮玄关灯并把空调调到你预设的舒适温度你说一句看电影客厅主灯熄灭、氛围灯切成暖色、音响开机这些动作全部由自动化规则触发不需要碰米家 App夜里起身人体传感器检测到移动路径灯亮起几分钟后自动熄灭早上出门离家模式关闭所有灯光空调切到节能。这些场景的共性是每个小米设备在 Home Assistant 里都变成了标准实体可以直接写进自动化、仪表板和脚本而不用再和米家 App 抢控制权。为什么小米米家设备不能直接接入 Home Assistant问题出在生态边界上。米家设备的数据默认只在米家 App 和小米云之间流转第三方系统想读取状态、下发指令早期只能靠抓包、逆向协议写插件。这类手段不稳小米云接口或设备固件一更新插件就可能全线失效维护成本全压在用户自己身上。Xiaomi Home 集成换了个思路不逆向直接对接小米官方开放的 MIoT-Spec-V2 协议。MIoT-Spec-V2 可以理解为小米给每类设备规定的一份能力说明书写明设备有哪些属性比如温度值、能执行哪些方法比如开关机、会发出哪些事件比如门被打开。设备按这份说明书自报家门集成负责把说明书翻译成 Home Assistant 能识别的实体。于是接入动作收敛成一次授权、自动发现不需要为每台设备手写对接逻辑。Xiaomi Home 集成安装步骤环境检查、仓库克隆与小米账号登录安装前检查版本要求先确认你的 Home Assistant 版本满足最低要求版本过低会缺少组件依赖的接口后续排查很麻烦Core ≥ 2024.4.4Operating System ≥ 13.0同时保证系统能正常访问小米云服务登录授权环节要用到。方式一Git 克隆安装官方推荐在 HA 的配置目录下执行以下命令把组件复制到custom_components目录git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/config⚠️ 两个关键点install.sh只接受一个参数即 HA 的config目录路径填错会直接报错退出执行成功后输出提示Please restart Home Assistant必须重启 HA组件才会出现在集成列表里。官方推荐这种方式因为日后想切到某个固定版本只需git checkout对应 Tag 后重跑一次脚本即可。方式二HACS 一键安装如果已装 HACS在商店搜索框输入Xiaomi Home进入详情页点 DOWNLOAD完成后同样重启 HA。登录小米账号并选择服务地区重启后打开 HA 的设置 → 设备与服务点击添加集成搜索 Xiaomi Home按页面提示登录小米账号然后选择账号所属区域。可选区域共 6 个中国大陆、欧洲、印度、俄罗斯、新加坡、美国。不同区域的小米云数据相互隔离选错区域会导致搜不到设备。登录成功后会弹出选择家庭与设备对话框选择要导入的米家家庭该家庭内所有设备会批量导入不需要逐台添加。设备分散在多个账号或多个区域的也可以通过添加中枢继续登录其他小米账号把不同来源的设备汇到同一个 HA 实例里。验证设备导入是否成功回到设置 → 设备与服务Xiaomi Home 条目下应能看到刚导入的设备每台设备展开后有一组实体开关、传感器、选择器等。随手点一个灯的开关设备状态立刻变化且实体同步刷新说明导入成功。小米米家集成云端与本地控制通道原理及实体自动转换机制云端控制经小米云完成状态同步与指令下发云控模式下集成的两端分别对接小米云的 MQTT Broker 和 HTTP API设备属性变化、上下线事件由 MQTT Broker 主动推送给集成集成无需轮询你在 HA 里发出的控制指令则通过 HTTP API 发到云端再转发给设备。整个链路对家庭网络环境不挑剔人在外地也能远程操作家里的设备。本地控制小米中枢网关承接局域网内通信本地模式把通信终点从小米云换成小米中枢网关。网关内置标准 MQTT Broker设备状态消息和控制指令都在局域网内走一圈不经过任何外部服务器响应几乎是瞬时的传感器联动类自动化尤其受益。启用本地模式有版本门槛独立的小米中枢网关需要固件 3.3.0_0023 及以上内置中枢网关功能的设备需要软件 0.8.9 及以上且中枢网关目前仅在中国大陆发售。此外集成还提供局域网控制作为降级方案只能控制通过 WiFi 或网线连接路由器的 IP 设备管不了 BLE Mesh、ZigBee 设备官方明确建议谨慎使用启用局域网控制时相关模型参数存放在 custom_components/xiaomi_home/miot/lan/profile_models.yaml按文件内注释修改。云端控制与本地控制通道对比对比项云端控制本地控制消息中转方小米云小米中枢网关数据走向指令和状态都经过公网只在家庭局域网内传输响应速度受公网波动影响接近零延迟远程可用性断网也能远程操作家中设备仅局域网内有效前置条件能访问所选区域的小米云拥有固件 3.3.0_0023 及以上的中枢网关MIoT-Spec-V2 实体自动转换导入即用的实体生成规则设备导入后最省事的一环是集成内置的实体转换引擎。它读取每台设备的 MIoT-Spec-V2 说明书按属性访问方式自动生成对应实体可写的布尔属性 → Switch开关可写的带取值列表属性 → Select下拉选择可写的数值范围属性 → Number数值输入只读属性 → Sensor传感器只读文本属性 → Text设备事件 → Event设备方法 → Button无参数或 Notify带参数换句话说导入完成的那一刻实体就已经能用了你不需要手写任何映射。转换规则的实现在 custom_components/xiaomi_home/miot/specs/specv2entity.py配套的过滤和改写规则放在 custom_components/xiaomi_home/miot/specs/ 目录下如spec_filter.yaml可按设备型号过滤不需要的属性改动后需在集成配置 → 更新实体转换规则中刷新一次。支持的设备范围、服务地区与界面语言设备类型转换后的实体接入 Home Assistant 后的典型用途智能灯、灯带light场景照明、氛围调色智能插座、墙壁开关switch通断控制、功耗统计温湿度、人体、门窗传感器sensor / binary_sensor自动化触发条件空调伴侣、温控器climate按时间表调节室温智能风扇、循环扇fan风速与摇头控制智能加湿器humidifier湿度联动开关蓝牙设备、红外设备和虚拟设备暂不支持。界面语言方面custom_components/xiaomi_home/translations/ 目录维护了简体中文、繁体中文、英文、日文、德文等 13 种语言的翻译跟随 HA 的语言设置自动切换。小米米家集成常见故障排查状态不同步、本地控制失效怎么办症状检查项解决办法重启后集成列表里没有 Xiaomi Homeconfig/custom_components/下是否存在xiaomi_home文件夹重跑./install.sh /path/to/config再重启 HA登录成功但搜不到设备所选区域与小米账号归属地是否一致更换正确的服务区域重新登录多区域设备可分别添加实体状态长时间不更新设备在米家 App 里是否在线OAuth 授权是否过期米家 App 中重新确认设备在线必要时在小米账号的应用授权页取消 Xiaomi Home 授权后重新登录本地模式没有生效中枢网关固件是否 ≥ 3.3.0_0023网关与 HA 是否同一局域网升级网关固件核对网关 IP满足条件后集成会自动走网关通道实体行为与预期不符该型号是否在过滤规则中被裁剪查看 spec_filter.yaml必要时按注释调整并刷新转换规则组件后续的版本演进可以看 更新日志想给翻译或转换规则提改进意见可参考 中文贡献指南。随着设备越接越多你会发现真正的工作量从接入转移到了编排——那正是 Home Assistant 最擅长的部分。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/7 19:37:19 · 阅读 1.2k 小米米家设备接入 Home Assistant 完整指南：Xiaomi Home 集成安装、配置与双通道控制教程
小米米家设备接入 Home Assistant 完整指南Xiaomi Home 集成安装、配置与双通道控制教程【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_homeXiaomi Home 集成是小米官方支持的 Home Assistant 组件用于把小米米家设备接入 Home Assistant让灯、插座、温湿度计、空调伴侣等设备进入同一个自动化平台统一调度。这篇指南覆盖安装、小米账号授权、云端与本地两种控制通道的配置方法以及常见故障的排查思路适合第一次做小米米家设备接入 Home Assistant 的新手。接入小米米家设备后Home Assistant 里能跑起来哪些自动化场景先看看装好之后能做什么。傍晚你推开门回家门磁传感器上报状态变化Home Assistant 自动点亮玄关灯并把空调调到你预设的舒适温度你说一句看电影客厅主灯熄灭、氛围灯切成暖色、音响开机这些动作全部由自动化规则触发不需要碰米家 App夜里起身人体传感器检测到移动路径灯亮起几分钟后自动熄灭早上出门离家模式关闭所有灯光空调切到节能。这些场景的共性是每个小米设备在 Home Assistant 里都变成了标准实体可以直接写进自动化、仪表板和脚本而不用再和米家 App 抢控制权。为什么小米米家设备不能直接接入 Home Assistant问题出在生态边界上。米家设备的数据默认只在米家 App 和小米云之间流转第三方系统想读取状态、下发指令早期只能靠抓包、逆向协议写插件。这类手段不稳小米云接口或设备固件一更新插件就可能全线失效维护成本全压在用户自己身上。Xiaomi Home 集成换了个思路不逆向直接对接小米官方开放的 MIoT-Spec-V2 协议。MIoT-Spec-V2 可以理解为小米给每类设备规定的一份能力说明书写明设备有哪些属性比如温度值、能执行哪些方法比如开关机、会发出哪些事件比如门被打开。设备按这份说明书自报家门集成负责把说明书翻译成 Home Assistant 能识别的实体。于是接入动作收敛成一次授权、自动发现不需要为每台设备手写对接逻辑。Xiaomi Home 集成安装步骤环境检查、仓库克隆与小米账号登录安装前检查版本要求先确认你的 Home Assistant 版本满足最低要求版本过低会缺少组件依赖的接口后续排查很麻烦Core ≥ 2024.4.4Operating System ≥ 13.0同时保证系统能正常访问小米云服务登录授权环节要用到。方式一Git 克隆安装官方推荐在 HA 的配置目录下执行以下命令把组件复制到custom_components目录git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/config⚠️ 两个关键点install.sh只接受一个参数即 HA 的config目录路径填错会直接报错退出执行成功后输出提示Please restart Home Assistant必须重启 HA组件才会出现在集成列表里。官方推荐这种方式因为日后想切到某个固定版本只需git checkout对应 Tag 后重跑一次脚本即可。方式二HACS 一键安装如果已装 HACS在商店搜索框输入Xiaomi Home进入详情页点 DOWNLOAD完成后同样重启 HA。登录小米账号并选择服务地区重启后打开 HA 的设置 → 设备与服务点击添加集成搜索 Xiaomi Home按页面提示登录小米账号然后选择账号所属区域。可选区域共 6 个中国大陆、欧洲、印度、俄罗斯、新加坡、美国。不同区域的小米云数据相互隔离选错区域会导致搜不到设备。登录成功后会弹出选择家庭与设备对话框选择要导入的米家家庭该家庭内所有设备会批量导入不需要逐台添加。设备分散在多个账号或多个区域的也可以通过添加中枢继续登录其他小米账号把不同来源的设备汇到同一个 HA 实例里。验证设备导入是否成功回到设置 → 设备与服务Xiaomi Home 条目下应能看到刚导入的设备每台设备展开后有一组实体开关、传感器、选择器等。随手点一个灯的开关设备状态立刻变化且实体同步刷新说明导入成功。小米米家集成云端与本地控制通道原理及实体自动转换机制云端控制经小米云完成状态同步与指令下发云控模式下集成的两端分别对接小米云的 MQTT Broker 和 HTTP API设备属性变化、上下线事件由 MQTT Broker 主动推送给集成集成无需轮询你在 HA 里发出的控制指令则通过 HTTP API 发到云端再转发给设备。整个链路对家庭网络环境不挑剔人在外地也能远程操作家里的设备。本地控制小米中枢网关承接局域网内通信本地模式把通信终点从小米云换成小米中枢网关。网关内置标准 MQTT Broker设备状态消息和控制指令都在局域网内走一圈不经过任何外部服务器响应几乎是瞬时的传感器联动类自动化尤其受益。启用本地模式有版本门槛独立的小米中枢网关需要固件 3.3.0_0023 及以上内置中枢网关功能的设备需要软件 0.8.9 及以上且中枢网关目前仅在中国大陆发售。此外集成还提供局域网控制作为降级方案只能控制通过 WiFi 或网线连接路由器的 IP 设备管不了 BLE Mesh、ZigBee 设备官方明确建议谨慎使用启用局域网控制时相关模型参数存放在 custom_components/xiaomi_home/miot/lan/profile_models.yaml按文件内注释修改。云端控制与本地控制通道对比对比项云端控制本地控制消息中转方小米云小米中枢网关数据走向指令和状态都经过公网只在家庭局域网内传输响应速度受公网波动影响接近零延迟远程可用性断网也能远程操作家中设备仅局域网内有效前置条件能访问所选区域的小米云拥有固件 3.3.0_0023 及以上的中枢网关MIoT-Spec-V2 实体自动转换导入即用的实体生成规则设备导入后最省事的一环是集成内置的实体转换引擎。它读取每台设备的 MIoT-Spec-V2 说明书按属性访问方式自动生成对应实体可写的布尔属性 → Switch开关可写的带取值列表属性 → Select下拉选择可写的数值范围属性 → Number数值输入只读属性 → Sensor传感器只读文本属性 → Text设备事件 → Event设备方法 → Button无参数或 Notify带参数换句话说导入完成的那一刻实体就已经能用了你不需要手写任何映射。转换规则的实现在 custom_components/xiaomi_home/miot/specs/specv2entity.py配套的过滤和改写规则放在 custom_components/xiaomi_home/miot/specs/ 目录下如spec_filter.yaml可按设备型号过滤不需要的属性改动后需在集成配置 → 更新实体转换规则中刷新一次。支持的设备范围、服务地区与界面语言设备类型转换后的实体接入 Home Assistant 后的典型用途智能灯、灯带light场景照明、氛围调色智能插座、墙壁开关switch通断控制、功耗统计温湿度、人体、门窗传感器sensor / binary_sensor自动化触发条件空调伴侣、温控器climate按时间表调节室温智能风扇、循环扇fan风速与摇头控制智能加湿器humidifier湿度联动开关蓝牙设备、红外设备和虚拟设备暂不支持。界面语言方面custom_components/xiaomi_home/translations/ 目录维护了简体中文、繁体中文、英文、日文、德文等 13 种语言的翻译跟随 HA 的语言设置自动切换。小米米家集成常见故障排查状态不同步、本地控制失效怎么办症状检查项解决办法重启后集成列表里没有 Xiaomi Homeconfig/custom_components/下是否存在xiaomi_home文件夹重跑./install.sh /path/to/config再重启 HA登录成功但搜不到设备所选区域与小米账号归属地是否一致更换正确的服务区域重新登录多区域设备可分别添加实体状态长时间不更新设备在米家 App 里是否在线OAuth 授权是否过期米家 App 中重新确认设备在线必要时在小米账号的应用授权页取消 Xiaomi Home 授权后重新登录本地模式没有生效中枢网关固件是否 ≥ 3.3.0_0023网关与 HA 是否同一局域网升级网关固件核对网关 IP满足条件后集成会自动走网关通道实体行为与预期不符该型号是否在过滤规则中被裁剪查看 spec_filter.yaml必要时按注释调整并刷新转换规则组件后续的版本演进可以看 更新日志想给翻译或转换规则提改进意见可参考 中文贡献指南。随着设备越接越多你会发现真正的工作量从接入转移到了编排——那正是 Home Assistant 最擅长的部分。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考