米家接入 Home Assistantha_xiaomi_home 完整安装与使用指南——3 种安装方式与本地控制一次讲清【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_home 是小米官方提供的米家集成组件可把米家设备批量导入 Home Assistant在同一个面板里完成状态查看、指令下发与自动化编排。本文按一条从零到可用的路径讲清版本要求、3 种安装方式、登录配置、本地控制与实体映射规则。安装前的两项检查与地区清单先确认两个硬指标不满足则配置流程无法走通检查项最低要求Home Assistant Core2024.4.4Operating SystemOS 镜像13.0云服务接口部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国共 6 个地区各地区用户数据相互隔离。首次配置时必须选择自己所在地区的机房选错会直接导致设备列表为空不同地区的米家设备之后仍可汇入同一个 Home Assistant 区域。品类覆盖上绝大多数米家设备可用纯蓝牙、红外及虚拟设备暂不支持。小米 HA 插件 3 种安装方式对比三条路径最终都落在config/custom_components/xiaomi_home目录差别只在于获取与更新组件的方式方式适合人群后续升级方式Git 克隆官方推荐熟悉终端命令的用户git fetch后 checkout 对应标签重跑./install.sh /configHACS习惯用社区商店的用户HACS 内一键更新Samba / FTP 手动复制不想接触终端的用户手动覆盖custom_components/xiaomi_home文件夹Git 方式的关键命令只有 4 行cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /configinstall.sh 会先清掉旧版本再复制新组件完成后按提示重启 Home Assistant 即可生效。以后想升级或回退到某个版本切到对应 tag 再执行一次./install.sh /config就行。HACS 自 2025 年 5 月起已将 Xiaomi Home 收录为默认仓库直接搜索安装即可。米家设备导入OAuth 登录与批量选择家庭重启后进入设置 设备与服务 添加集成搜索Xiaomi Home按提示点击登录。登录走 OAuth 2.0 第三方授权全程不提交小米账号密码Home Assistant 里也不会保存你的密码。登录成功后弹出选择家庭与设备对话框勾选要导入的米家家庭该家庭下所有设备随即批量入网。⚠️ 避坑提示受平台限制登录成功后设备信息、证书、token 等会明文写入 HA 配置文件这份文件一旦泄露他人可冒用你的身份登录。请妥善保管配置文件怀疑令牌泄露时可到米家 APP 的 我的 小米账号页面 应用授权 中找到 Xiaomi Home (Home Assistant Integration) 取消授权。多账号场景第一个账号配置完成后在 Xiaomi Home 集成页点添加中枢再走一遍登录即可接入第二个小米账号不同账号的设备允许放进同一区域统一管理。米家本地控制云端与局域网两条链路默认情况下状态更新与指令全部经小米云中转部署小米中枢网关固件 3.3.0_0023 及以上或内置中枢网关的米家设备软件 0.8.9 及以上后链路切换为局域网闭环。中枢网关目前仅在中国大陆可用。云端链路局域网链路状态订阅集成订阅小米云 MQTT Broker设备变化由云端推送无需轮询集成订阅中枢网关内置的 MQTT Broker设备变化由网关推送指令下发通过 MIoT 云端 HTTP 接口发送由云端转发设备向网关 Broker 发布消息由网关转发设备特点依赖外网仅配置完成时全量拉取一次属性云端压力小设备 → 网关 → 集成全程局域网完成响应更快、少依赖云端MQTT 可理解为订阅制快递只收你订过的消息。⚠️ 还有一项更新局域网控制配置选项设置 设备与服务 已配置 Xiaomi Home 配置可让同一局域网内的 IP 设备WiFi 或网线接入走本地控制全球可用、不受地区限制但只能覆盖 IP 设备蓝牙 Mesh、ZigBee 设备无效。官方明确提示该功能可能引起个别异常建议不要开启局域网内已有中枢网关时该选项也不会生效。MIoT-Spec-V2 说明书如何变成 HA 实体MIoT-Spec-V2 是小米 IoT 平台为每台设备定义的标准说明书描述设备有哪些服务、状态与动作。集成按这份说明书自动把功能翻译成 HA 实体无需手写实体配置。一个产品即一台设备设备下挂若干服务服务再分为属性、动作、事件三类一般转换规则如下MIoT 类型条件生成的 HA 实体属性可写、字符串格式Text属性可写、布尔格式Switch属性可写、带取值列表value-listSelect属性可写、带取值范围value-rangeNumber属性只读Sensor事件任意Event事件参数传入_trigger_event动作无输入参数Button动作有输入参数Notify开 Action 调试模式时额外生成 Text举例风扇的工作模式是带取值列表的可写属性生成 Select 实体童锁布尔属性生成 Switch无线开关的长按事件生成 Event 实体触发时携带按键类型参数可直接被自动化订阅。Notify 实体的输入参数是有序列表详情页 Attributes 会显示格式例如某音箱方法格式为[Text Content(str), Silent Execution(bool)]发送[Hello, true]即可。不想要的设备或功能可用spec_filter.yaml按实例号过滤支持通配符。多语言显示与实体转换规则定制实体名称的语言来自两层一是从小米云下载的设备厂商多语言文件二是本地维护的multi_lang.json词典可按设备 urn 与实例代码如service:002:property:001补充或改写翻译。生效优先级为本地 multi_lang.json 云端厂商语言包 默认英文。集成界面本身支持简体中文、繁体中文、英文、西班牙语、俄语、法语、德语、日语、意大利语、荷兰语、葡萄牙语、巴西葡萄牙语、土耳其语共 13 种语言。⚠️ 改完custom_components/xiaomi_home/miot/specs/目录下的任何文件spec_filter.yaml、spec_modify.yaml、multi_lang.json等必须到集成的配置页执行一次更新实体转换规则改动才会生效。Action 调试模式手动发指令验证控制链路Action 调试模式入口在 设置 设备与服务 已配置 Xiaomi Home 配置。开启后带参数的设备动作会额外以一个文本实体呈现你可以手动填写参数直接向设备发送 Action 指令适合排查自动化触发但设备无反应这类链路问题。同一配置页还能修改用户昵称、更新从米家 APP 导入的设备列表。下一步与延伸资源让 Home Assistant 与米家设备保持同一局域网用区域功能对设备分组把设备事件接进自动化。关注版本节奏当前版本 v0.5.0更新日志见 CHANGELOG.md。阅读源码入口 custom_components/xiaomi_home/miot/miot_cloud 封装 OAuth 登录与云 HTTP 接口miot_device 处理设备实体的属性/事件/动作miot_spec 负责解析 MIoT-Spec-V2miot_lan 负责局域网设备发现与控制。完整中文文档见 doc/README_zh.md。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考