1. 为什么要在 HomeAssistant 里折腾小米集成把家里一堆小米设备接进 HomeAssistant这件事我从 2021 年就开始反复折腾。最开始用官方米家 App 凑合后来设备数量上来了——灯、插座、温湿度计、人体传感器、门窗传感器、扫地机——米家 App 的自动化能力就明显不够用了。跨品牌联动做不了本地化控制做不了数据也没法自己拿来做看板。HomeAssistant 的价值就在这里它把不同协议、不同品牌的设备统一到一个平台用一套自动化引擎驱动还能把数据留在本地。小米生态的设备接入 HomeAssistant主流路线有两条。一条是走官方xiaomi_miio集成另一条是走社区维护的Xiaomi Miot Auto后面简称 Miot Auto。前者是 HomeAssistant 核心自带的稳定但支持的设备型号有限很多新出的蓝牙 Mesh 设备、带加密协议的设备它认不出来。后者是 HACS 里的第三方集成覆盖广、更新快几乎你能在米家 App 里看到的设备它都能接而且支持本地和云端两种模式。所以现在绝大多数玩家的选择是用 HACS 装 Miot Auto。HACS 是什么全称 Home Assistant Community Store你可以把它理解成 HomeAssistant 的“应用商店”。HomeAssistant 核心只带官方集成第三方集成、前端卡片、主题这些都得靠 HACS 来统一管理。没有 HACS你就得手动往custom_components目录里丢文件升级还得自己盯 GitHub非常麻烦。装好 HACS 之后小米集成的安装和后续更新就是点几下按钮的事。这篇内容适合三类人刚装好 HomeAssistant、准备接第一批小米设备的新手已经装了 HACS 但小米设备接不进来、卡在配置向导报错的老玩家以及想搞清楚本地模式和云端模式到底怎么选、为什么有时候会报 500 错误的进阶用户。我会把整个流程拆开讲包括每一步背后的原因、参数怎么填、报错怎么排查尽量让你少走我当年走过的弯路。2. 装小米集成前的环境准备与思路拆解2.1 先搞清楚你的 HomeAssistant 是怎么部署的这一步很多人跳过结果后面踩坑。HomeAssistant 的部署方式直接决定了你装 HACS 的路径、文件放哪、以及能不能用某些高级功能。常见的部署方式有这么几种HomeAssistant OSHAOS官方整机镜像烧到树莓派、NUC 或者虚拟机里。这是最省心的方式Supervisor 自带HACS 有官方的一键脚本推荐新手用。HomeAssistant ContainerDocker用 Docker 跑homeassistant/home-assistant镜像。灵活但没有 SupervisorHACS 得手动装部分依赖 Supervisor 的集成用不了。HomeAssistant Supervised在 Debian 上手动装 Supervisor介于上面两者之间现在官方支持力度在下降。Corepip 安装直接在 Python 环境里跑最原始不推荐除非你是开发者。为什么先讲这个因为 HACS 的安装方式在不同部署下差别很大。HAOS 和 Supervised 可以直接用终端加载项跑脚本Container 和 Core 就得手动下载解压。你要是没搞清楚自己是哪种照着别人的教程操作十有八九会卡在某一步。提示在 HomeAssistant 的“设置 → 关于”里能看到你的安装类型Installation Type先确认这个再往下走。2.2 HACS 的安装路径选择与理由HACS 官方推荐两种安装方式一种是脚本安装一种是手动安装。脚本安装适合 HAOS 和 Supervised因为它需要访问 Supervisor 的 API。手动安装适合所有方式本质就是把 HACS 的代码放到config/custom_components/hacs目录然后重启。我个人的建议是能用脚本就用脚本脚本跑不通再手动。脚本的好处是它会自动处理依赖、自动创建目录、自动拉取最新版本省去你手动核对版本号的麻烦。手动安装的坑在于你得自己确认下载的是 release 版本而不是开发分支还得保证目录结构正确少一层多一层都会导致 HACS 加载失败。手动安装的核心步骤就三步下载 HACS 的 release 压缩包、解压出hacs文件夹、把它放到config/custom_components/下。听起来简单但实际操作的坑在于很多人下载的是 GitHub 的源码压缩包Source code而不是 Release 里的hacs.zip。源码包解压出来的目录结构和 Release 包不一样直接丢进去 HACS 会报“无法加载”。这个坑我见过太多人踩。2.3 小米集成选 Miot Auto 而不是官方 miio 的原因前面提过官方xiaomi_miio集成支持的设备有限。具体来说它主要支持老一代的 Wi-Fi 设备比如初代扫地机、部分空气净化器、Yeelight 灯。对于蓝牙 Mesh 设备、Zigbee 设备通过多模网关、以及大量新出的 Wi-Fi 设备官方集成要么不支持要么支持得很勉强。Miot Auto 的优势在于设备覆盖广基于 miot-spec 协议理论上米家 App 能控制的设备它都能接。本地 云端双模式Wi-Fi 设备可以走本地局域网控制延迟低、断网也能用蓝牙 Mesh 和 Zigbee 设备通过网关走本地实在不行的走云端。自动更新设备型号库跟着米家更新新设备出来很快就能支持。实体丰富一个设备能拆出很多实体比如一个扫地机能拆出电量、状态、清扫模式、耗材寿命等。代价是它比官方集成复杂配置项多偶尔会有设备识别不准的情况。但综合来看对于设备多、型号杂的家庭Miot Auto 是更实际的选择。3. HACS 安装小米集成的完整实操流程3.1 第一步确认 HACS 已经正确安装并登录在装小米集成之前先确认 HACS 本身是好的。打开 HomeAssistant左侧边栏应该能看到 HACS 的图标。点进去如果能看到“集成”“前端”“自动化”这些分类说明 HACS 正常工作。如果侧边栏没有 HACS或者点进去报错那得先把 HACS 修好。HACS 第一次使用需要 GitHub 授权。它会给你一个设备码让你去 GitHub 页面输入。这一步很多人卡住原因是网络问题导致 GitHub 授权页面打不开。我的经验是多试几次或者换个时间段。授权成功后HACS 会显示你的 GitHub 用户名。注意HACS 的 GitHub 授权只需要做一次之后除非你清空了配置否则不用重复。如果你换了 HomeAssistant 实例需要重新授权。确认 HACS 正常后点进 HACS右上角搜索框输入Xiaomi Miot Auto。如果搜不到检查一下你的 HACS 是不是只显示了已安装的集成——需要在 HACS 设置里确认“显示未安装的集成”是开着的。3.2 第二步通过 HACS 下载并安装 Miot Auto搜索到Xiaomi Miot Auto后点进去右下角有个“下载”按钮。点击后会让你选版本一般选最新的 release 版本。下载完成后HACS 会提示你需要重启 HomeAssistant。这里有个细节HACS 下载集成只是把文件放到了config/custom_components/xiaomi_miot目录但 HomeAssistant 还没加载它。必须重启才能让 HomeAssistant 识别到这个新集成。重启的方式设置 → 系统 → 右上角电源按钮 → 重启 HomeAssistant。如果你用的是 HAOS也可以重启整个主机但没必要重启 HomeAssistant 核心就够了。重启完成后去“设置 → 设备与服务 → 添加集成”搜索Xiaomi Miot Auto。如果能搜到说明安装成功。搜不到的话检查custom_components/xiaomi_miot目录是否存在以及里面有没有manifest.json文件。3.3 第三步添加小米账号并选择接入模式点开Xiaomi Miot Auto集成后会进入配置向导。第一步是选择接入方式通常有三个选项自动模式推荐集成会自动尝试本地连接失败则走云端。本地模式只走局域网要求设备和 HomeAssistant 在同一网段。云端模式全部走小米云依赖外网。我一般选自动模式省心。选完之后会让你输入小米账号和密码。这里要注意建议用小米账号 ID 而不是手机号或邮箱。小米账号 ID 是一串数字在小米账号中心能查到。用手机号登录有时候会因为地区问题失败。输入账号密码后集成会去拉取你账号下的设备列表。这一步如果卡住或者报错大概率是网络问题或者账号地区不对。设备列表拉出来后会让你勾选要接入的设备。建议第一次不要全选先选一两个测试确认能用了再批量加。3.4 第四步处理配置向导 500 错误的实战排查热词里提到的“无法加载配置向导: 500 internal server error”是很多人装小米集成时会遇到的。这个错误的本质是 HomeAssistant 后端在处理配置流程时抛了异常前端只看到一个笼统的 500。可能的原因有好几类我按出现频率排一下可能原因表现排查方法集成版本与 HA 版本不兼容添加集成时直接 500看 HA 日志里xiaomi_miot相关报错降级或升级集成Python 依赖缺失日志里有ImportError或ModuleNotFoundError检查manifest.json里的 requirements手动装依赖账号登录失败日志里有登录相关异常换账号 ID 登录确认账号地区配置文件损坏之前配置残留导致冲突删除config/.storage/xiaomi_miot相关文件后重试HA 核心 bug特定版本已知问题查 HA release notes升级或降级核心排查 500 错误的核心是看日志。设置 → 系统 → 日志把级别调到 debug然后重新触发一次配置向导看日志里xiaomi_miot抛了什么异常。大部分情况下日志会直接告诉你缺哪个依赖或者哪一步失败了。我遇到过一次典型的 500日志里显示Cannot connect to Xiaomi cloud原因是账号密码里有个特殊字符在配置流程里被转义了。改成纯数字账号 ID 后就好了。所以遇到 500 别慌先看日志日志比前端报错信息有用得多。4. 小米设备接入后的配置与优化4.1 实体命名与区域划分的实操建议设备接进来之后HomeAssistant 会给每个实体自动生成一个名字通常是“设备名_功能”这种格式比如mi_light_xxx。这些名字又长又乱做自动化的时候很难找。我的做法是接入后第一时间重命名实体并按房间划分区域。重命名的原则是“房间 设备 功能”比如“客厅主灯亮度”“卧室温湿度计温度”。区域划分在“设置 → 区域”里做把设备分配到对应房间。这样在自动化和仪表盘里按区域筛选就能快速找到设备。这一步看起来是体力活但后期收益巨大。我一开始偷懒没改名结果做自动化时在一堆mi_xxx_yyy里找设备找得眼睛疼。后来花了一个晚上全部重命名之后做联动效率高了很多。4.2 本地模式与云端模式的取舍Miot Auto 支持本地和云端两种模式很多人不知道怎么选。我的经验是Wi-Fi 设备优先本地只要设备和 HA 在同一网段本地模式延迟能低到几十毫秒而且断网也能用。本地模式需要设备支持 miot 本地协议大部分新设备都支持。蓝牙 Mesh 和 Zigbee 设备走网关本地这些设备本身不联网是通过网关接入的。只要网关在本地控制就是本地的。实在不行的走云端有些设备协议加密本地拿不到只能走云端。云端模式依赖外网延迟高断网就废。判断一个设备能不能本地控制可以在集成里看设备详情会标注“本地”还是“云端”。如果显示云端但你确定设备在同一网段可以尝试在集成配置里强制本地模式有时候是自动探测没识别出来。提示本地模式的一个前提是 HomeAssistant 能直接访问设备的 IP。如果你的 HA 跑在 Docker 里网络模式是 bridge可能访问不到局域网设备需要改成 host 模式。4.3 自动化联动的几个实用场景设备接进来只是第一步真正体现价值的是自动化。分享几个我实际在用的场景人体传感器 灯卫生间人体传感器检测到人自动开灯2 分钟无人自动关灯。这个用本地模式响应快不会出现人进去了灯还没亮的情况。温湿度计 空调/加湿器温度高于 28 度自动开空调湿度低于 40% 自动开加湿器。这个走云端也行因为不需要秒级响应。门窗传感器 报警门窗打开且家里无人时推送通知并触发警报。这个建议本地因为涉及安全不能依赖外网。做自动化的时候建议先用“自动化编辑器”图形界面搭跑通了再考虑要不要转 YAML。图形界面直观不容易写错语法。等熟练了YAML 更灵活能做一些图形界面做不了的复杂逻辑。5. 常见问题与排查技巧实录5.1 设备接入后显示“不可用”怎么办设备接进来但显示“不可用”是最常见的问题之一。原因通常有这么几个设备离线先去米家 App 确认设备在线。设备本身离线HA 里肯定不可用。IP 变了本地模式依赖设备 IP如果设备重启后 IP 变了HA 就找不到。解决办法是在路由器里给设备设静态 IP 或 DHCP 保留。token 失效小米设备的本地控制依赖 tokentoken 会变。Miot Auto 会自动更新 token但如果更新失败设备就不可用。可以在集成里手动触发一次更新。网关问题蓝牙 Mesh 和 Zigbee 设备依赖网关网关离线下面所有设备都不可用。排查顺序先看米家 App再看 HA 日志最后看网络。大部分“不可用”都是设备离线或 IP 变化导致的。5.2 集成更新后设备失效的处理Miot Auto 更新频繁有时候更新完会发现某些设备失效了。这是因为新版本可能改了设备识别逻辑或者依赖了新版本的 miot-spec。处理办法先看 HACS 里有没有更新提示有就更新到最新。更新后重启 HA再看设备状态。如果还不行去集成里删除该设备重新添加。实在不行去 GitHub 的 issue 区搜设备型号看有没有人遇到同样问题。我的经验是不要盲目追新。如果当前版本用着稳定没必要每次更新都跟。等一两个版本确认没大问题再更新。我吃过一次亏更新完扫地机的实体全乱了折腾了半天才恢复。5.3 500 错误速查表把前面提到的 500 错误排查整理成速查表方便对照日志关键词可能原因解决动作ModuleNotFoundError依赖缺失手动 pip 安装缺失模块Cannot connect to Xiaomi cloud账号或网络问题换账号 ID检查网络Invalid tokentoken 失效重新登录账号Timeout网络超时检查 HA 到设备/云的网络KeyError/AttributeError集成 bug升级或降级集成版本Config flow could not be loaded集成未正确加载检查 custom_components 目录这张表覆盖了我遇到过的绝大多数 500 场景。核心思路还是那句话看日志日志里什么都有。5.4 几个我踩过的坑和独家技巧最后分享几个文档里不会写、但实际很有用的经验账号地区要匹配小米账号有地区之分中国大陆账号和设备用中国大陆服务器。如果你账号地区设成了别的设备列表可能拉不出来。不要用主账号建议专门注册一个小米账号把要接入 HA 的设备分享给这个账号。这样主账号的隐私数据不会暴露而且账号出问题不影响主账号。批量接入要分批一次接几十个设备配置流程容易超时。建议一次接 5 到 10 个接完确认没问题再继续。备份配置HA 的配置定期备份尤其是.storage目录。集成配置都在里面出问题了能快速恢复。关注 GitHub issueMiot Auto 的 issue 区是宝藏很多问题别人已经遇到并解决了。搜设备型号往往能找到现成答案。这套流程我前前后后在不同环境里跑过五六次从树莓派到 NUC 到 Docker每次都会遇到点新问题但核心逻辑没变装好 HACS装好 Miot Auto配好账号选好模式剩下的就是耐心排查。小米设备接入 HA 这件事门槛主要在前期配置一旦跑通后面的自动化才是真正好玩的开始。