1. 先把路选对ha_xiaomi_home 的定位与我的选择理由在 Home Assistant 里接米家设备这件事我前后折腾了差不多两年早期用第三方轮询方案后来试过拿局域网协议自己抓包再后来换成网关直连。每次换方案都掉一层皮设备一多状态不同步、实体名乱成麻、升级一次挂一片全是家常便饭。直到用上 ha_xiaomi_home 这套由米家生态侧提供的官方 Home Assistant 集成才算真正把这件事稳定下来。这篇内容是整套ha_xiaomi_home 米家设备接入的完整落地记录从环境准备、安装、登录授权、设备同步到实体命名规范、自动化配置和线上排错按我实际跑的流程一步步写清楚目标是让你一次跑通而不是装完之后在社区里到处翻帖子。适合谁看已经有一台长期在线的 Home Assistant 主机、家里至少有五六个米家设备、并且希望把这些设备拉进统一界面做跨品牌联动的人。如果你只是想在手机上看个温湿度用米家 App 就够了没必要上这套东西但如果你想让灯光、窗帘、空调、传感器和别的品牌设备在同一个自动化里说话那这套集成基本是目前最省心的选择。下面的内容会包含完整命令、配置片段、参数取舍和踩坑记录小白可以照着抄有基础的可以直接跳到第 3 章。1.1 三条接入路线的现实差别在动手之前值得先花十分钟把路线想清楚因为选错路线后面再怎么调都是白费。市面上主流的三条路子本质差别在于「数据从哪里来」一条是纯云端轮询Home Assistant 定时去米家服务器要一次状态一条是纯局域网直连设备在本地把状态推给主机还有一条是混合模式云端拿设备清单和账号鉴权本地负责高频状态更新。第一类实现简单、兼容性最广但延迟明显一次轮询几秒钟人走过感应灯亮了又灭这种事基本做不出来第二类响应快、断网可用但对设备型号和网络环境有硬性要求稍微老一点的设备直接不支持。ha_xiaomi_home 走的是第三条路而且做得比较聪明账号登录、家庭结构、设备列表这些低频信息走云端设备的具体属性读写尽量落到局域网。这样你既不用一个个手动填 token又能拿到接近本地直连的响应速度。理解这个分层很关键因为后面 90% 的排错都绕不开一个问题——「这台设备到底走的是云端还是本地」。我在最初部署时没搞清楚这一点看到日志里一堆云端请求就以为本地没生效白折腾了半宿后来才发现是我那台老设备的固件根本不支持本地协议集成已经尽力了。顺带说一句能力边界这套集成基于米家生态统一的设备模型规范也就是说只有遵循这套规范暴露属性的设备才有可能被完整识别。纯蓝牙、纯 Zigbee 且没有网关中转的设备通常拿不到本地通道早期一些封闭协议的设备能出现在列表里但只有少量实体。这一点在后面第 6 章会展开这里先埋个伏笔安装之前先去米家 App 里把那台设备的型号、固件版本、连接方式记下来这份清单会成为你后续排错的第一手资料。1.2 它解决的核心问题把碎片化的设备统一成可编程实体抛开技术细节这套集成真正解决的问题只有一个把米家 App 里那些只能点按钮的设备变成 Home Assistant 里可以读、可以写、可以被自动化引用的实体。听起来简单但它带来的是使用方式的质变。举个具体例子我家玄关有一台人体传感器、一盏吸顶灯、一台空调在米家 App 里它们的关系是固定的、封闭的你只能在预设场景里选接进 Home Assistant 之后这三个设备变成了三个实体我可以写「有人且室内温度高于 26 度才开空调、夜间只开低亮度灯」这种复合条件而且随时改不用等固件更新。能力边界也要说清楚它负责的是「设备接入与状态同步」不负责把米家的自动化规则搬过来也不负责设备固件的升级。你在米家 App 里设置的定时、场景接入之后依然在那里跑两边是并行的。我见过不少人以为接进 Home Assistant 就能把米家 App 卸了结果发现某些设备的本地按钮逻辑还在云端判断卸载后设备直接变「傻」。稳妥做法是米家 App 保留只把它当作设备管理和固件升级的入口日常控制全交给 Home Assistant。两边分工明确出问题也容易定位是哪一层的事。另外要提醒的是账号层面的限制。集成需要用米家账号做一次授权登录授权之后拿到的是这个账号可见范围内的设备和家庭。如果你家里有多个人共用设备或者设备分散在多个「家庭」里建议用一个专门的账号做统一管理把所有设备都共享给它而不是拿主账号去授权。这样做的好处是将来改密码、换手机、家人退群都不会影响集成运行我在第二台房子上就是这么做的半年来一次掉线都没有。1.3 硬件与环境清单开工前的自我检查项目最低要求我的建议说明Home Assistant近两年的稳定版本保持每月小版本更新版本过旧会缺依赖集成加载直接报错主机性能双核 / 2GB 内存四核 / 4GB 以上设备超过 50 台时实体注册很吃内存网络主机与设备同一网段有线连接关闭客户端隔离跨网段本地通道基本不通存储剩余 2GB剩余 8GB 以上快照、日志、数据库都在涨账号可正常登录的米家账号专用账号 设备共享避免主账号变更影响集成网络出口可访问米家云服务保持稳定不要频繁切换首次授权和云端同步必需表格里最容易被忽略的是「同一网段」。我见过太多案例主机的网口插在主路由设备连在二级路由或者访客网络表面上看都是内网实际上隔了一层 NAT本地通道根本发现不了设备。表现出来就是设备能同步出来、状态也能读但控制延迟两三秒日志里全是超时重试。如果你的网络里有多个无线接入点务必确认它们工作在同一个二层网络里并且关闭了「客户端隔离」这类选项。2. 动手前的准备账号、网络、备份三件事正式安装之前我强烈建议先把这三件事做完。听起来像废话但我每次帮人远程排错十次里有七次问题出在这一步没做干净。准备工作的核心逻辑是把不确定性提前消灭掉。安装过程本身其实很简单麻烦的是安装完之后发现「设备不全」「登录不上」「升级炸了没得回滚」而这些问题全都可以在动手前规避。2.1 账号与家庭结构要先理顺打开米家 App先看「我的」里面的家庭列表。如果你有多个家庭或者设备分散在不同家庭成员名下先把它们统一到一个家庭里或者至少确认这些设备都共享给了你准备用来授权的那个账号。集成的同步逻辑是按家庭拉取设备列表的登录之后会让你选择要同步哪些家庭如果一个家庭下有几十台设备而你只想接其中几台也可以在同步阶段做筛选但前提是这些设备得先出现在列表里。我吃过的一次亏是家里老人手机上也登录着同一个账号某天他误操作把几台设备「移出家庭」导致我这边集成里的设备全部变成不可用日志刷了一屏「设备不存在」。后来我改成用专用账号管理其他账号只做共享权限收紧之后这类事再没发生过。另外账号如果开了二次验证授权登录时需要一个验证码确保你能收到别在半夜做这件事短信延迟会让你卡在中途。还有个小细节值得提前处理设备改名。米家 App 里的设备名会带到 Home Assistant 的实体名称里如果你那边叫「客厅灯1」「灯2」「新设备」接进来之后实体名会非常难看后面做自动化时全靠猜。趁还没接先在米家 App 里把设备名改成「客厅主灯」「玄关吸顶灯」这种带位置和用途的描述能省掉后面大量重命名的工作。2.2 网络同网段这件事比你想的重要前面表格提过一次这里展开说。判断标准很简单在 Home Assistant 主机的终端里对设备的局域网地址执行一次连通性测试能通说明在同一个可路由的网段如果设备没有固定地址可以先在路由器后台查一下它的地址。命令大概是这样# 在 Home Assistant 主机上执行替换成设备实际地址 ping -c 4 192.168.1.56 # 顺便看一下主机的网络接口和网段 ip addr show | grep inet 能 ping 通不代表本地协议一定能用但 ping 不通基本可以判定本地通道没戏。另外要确认主机和设备在同一个子网掩码下比如主机是 192.168.1.x/24设备是 192.168.2.x/24即使路由器做了静态路由能互通广播发现也大概率失败因为很多本地协议依赖组播或广播。遇到这种情况最省事的做法是把设备挪到主机所在的网段而不是去折腾路由配置。无线环境也值得看一眼。设备如果连的是 2.4G 频段而主机离接入点很远丢包率高的时候本地状态更新会时断时续表现出来就是「灯的实际状态和界面不一致」。我一般会用主机持续对设备做几十次连通测试看丢包率超过 5% 就考虑加一个接入点或者调整设备位置。这部分不用过度优化但至少要知道自己网络的底子。2.3 三步做一次可靠快照这一步是保命的。集成装好之后会注册大量新实体一旦出问题需要回滚没有快照就只能手动删文件。我的做法是先在「设置 - 系统 - 备份」里创建一个完整备份命名带上日期和「安装前」字样然后单独把配置目录里的关键文件导出一份放在主机之外的存储上最后确认一下备份文件的大小和完整性别备份了个空壳。# 在主机上确认配置目录关键文件的存在与修改时间 ls -lh /config/configuration.yaml ls -lh /config/.storage/ | head -20第二行是我特别推荐看的.storage目录里放的是集成注册的实体、设备、区域等运行时数据安装前后对比一下这个目录的变化能快速定位「集成到底写了什么」。有几次我怀疑集成改坏了东西就是靠对比这个目录找到问题源的。做完这三步再动手心里会踏实很多。3. 安装 ha_xiaomi_home从 HACS 到手动部署准备工作做完正式进入安装。这套集成有两种常见安装方式通过 HACS 添加自定义仓库或者手动下载解压到配置目录。前者适合绝大多数人升级方便后者适合没有 HACS、或者处于离线环境的情况。两种方式最终效果一样装完之后都是custom_components下的一个目录我把两条路都走一遍你自己挑。3.1 HACS 自定义仓库安装最省事的路径如果你已经装了 HACS这条路最快。打开 HACS进入「集成」页面点击右上角三个点选择「自定义仓库」在地址栏填入这套集成的官方仓库地址在 HACS 里搜索集成名也能直接找到找不到再走自定义仓库类别选「Integration」然后添加。添加完成后在 HACS 的集成列表里搜索集成名点进去下载选择最新稳定版本。下载完成会提示需要重启先别急着重启。这里有个我踩过的坑HACS 下载完成后有些版本会在页面里显示「需要重启才能生效」但同时集成目录里可能还在写入文件如果你手快立刻重启可能加载到一个残缺的目录表现出来就是集成列表里能看到名字但点添加就报错。稳妥做法是下载完成后等十几秒用命令行确认目录结构和文件数量正常再重启。# 确认目录存在且文件数量正常正常应在几十个文件量级 ls -la /config/custom_components/xiaomi_home/ find /config/custom_components/xiaomi_home/ -type f | wc -l第二条命令输出的数字如果只有个位数说明下载不完整回 HACS 里重新下载一次。这个检查看起来啰嗦但能省掉后面「集成加载失败」的一整轮排查。3.2 手动部署解压到 custom_components 的完整流程没有 HACS 的话手动部署也不复杂核心就一句话把集成目录整个放进/config/custom_components/下目录名必须和集成内部声明的一致不能自己改名。具体操作我一般这样走先在电脑上下载发布包解压后确认里面有一层包含清单文件的目录然后通过文件编辑器或者共享目录把整个目录传到主机的custom_components下。# 假设已经把解压后的目录放到了 /tmp ls /tmp/ha_xiaomi_home/ # 确认里面有清单文件和组件代码 mv /tmp/ha_xiaomi_home /config/custom_components/xiaomi_home chown -R root:root /config/custom_components/xiaomi_home find /config/custom_components/xiaomi_home/ -name manifest.json -maxdepth 1最后一条命令必须能输出一个清单文件路径这是 Home Assistant 识别一个目录是不是有效集成的依据。如果清单文件在更深一层的子目录里说明你解压多套了一层需要把里面的内容往上提一级。这个错误极其常见我至少帮五个人修过——他们把压缩包整个解压结果变成custom_components/xiaomi_home/ha_xiaomi_home/...集成列表里永远看不到。手动部署的另一个注意点是权限。用普通用户通过 SMB 传文件上去有时候文件的属主和权限不对集成加载时读不到文件日志里会报权限错误。上面那条chown就是干这个的如果你的环境不是以 root 运行改成对应的运行用户即可。3.3 重启后怎么确认装对了不管走哪条路最后都要重启 Home Assistant。重启完成后进入「设置 - 设备与服务」点击右下角「添加集成」搜索集成名如果能搜到并且能点进去说明安装成功。如果搜不到先看日志。# 查看启动日志里与集成相关的记录 grep -i xiaomi /config/home-assistant.log | tail -30正常情况下你应该看到集成被加载、版本号被打印出来。如果看到类似「无法导入依赖」「找不到模块」的字样大概率是 Python 依赖没装好或者版本不匹配这时候先确认 Home Assistant 版本是否太旧再检查网络能不能正常访问依赖源。还有一种情况是日志里一片安静什么也没有那基本就是目录结构或清单文件的问题回到 3.2 那一步重新确认。我个人的习惯是在这一步就把版本号记下来写到自己的运维笔记里。原因很简单这套集成更新比较频繁有些新版本会改设备同步的行为出问题时能快速判断「是不是升级导致的」。第 7 章会讲升级策略这里先留个记录。4. 配置实操登录、授权与设备同步安装只是把代码放到位真正的重头戏是配置。这一步走顺了后面基本就是一劳永逸走不顺会卡在各种奇怪的地方。我把整个流程拆成四段登录授权、控制模式选择、设备筛选与命名、更新频率调优。按顺序来不要跳步。4.1 添加集成与授权登录的完整走位在「设备与服务」里点「添加集成」搜索集成名进入配置向导。第一步通常会让你选择登录方式或者服务器区域这里要选你账号实际所属的区域选错会登录成功但设备列表是空的非常迷惑。接着会跳转到授权页面输入米家账号和密码如果开了二次验证再填一次验证码。授权成功后会回到 Home Assistant弹出家庭选择。如果你有多个家庭这里会列出来勾选需要同步的。我的建议是第一次先只勾一个家庭、且设备较少的那个跑通流程之后再逐步加这样出问题时排查范围小。勾选完成后点提交集成开始拉取设备列表设备多的话会转圈几十秒到几分钟别急着刷新页面刷新可能导致配置流程中断得从头再来。注意授权过程中如果页面停在跳转界面不动先检查主机能不能正常访问外网。这一步是纯云端交互网络不通会一直卡着。另外授权用的浏览器最好和 Home Assistant 在同一网络环境下操作避免回调地址对不上。登录成功后集成会在「设备与服务」里生成一个条目点进去能看到设备和实体数量。到这一步最难的关卡已经过了剩下的都是锦上添花。4.2 云端与本地两种模式的取舍配置过程里会涉及控制模式的选择这也是整套方案最值得理解的地方。简单说云端模式是「所有读写都经过米家服务器」优点是兼容性最好任何能同步出来的设备都能控制缺点是延迟高、依赖外网服务器抖动时体验很差。本地模式是「在局域网内直接和设备通信」优点是快、断网可用缺点是对设备和网络有要求不支持的设备只能退回云端。我的实际配置是混合默认让集成自动判断支持的走本地不支持的走云端然后在集成设置里对个别关键设备手动指定。判断某台设备走的是哪条路可以看设备页面上的标注或者在日志里看有没有本地连接建立成功的记录。这里给个实用建议照明、窗帘、开关这类需要即时响应的设备优先保证本地传感器类即使走云端也能接受因为它们本来就低频上报。还有一个常被忽略的细节本地模式要求主机能主动连到设备的端口如果你的网络里有防火墙或者设备开了隔离本地连接会一直失败然后静默退回云端界面上看不出来只有日志里有记录。我建议装完之后专门花时间确认一遍关键设备的通道类型别等到某天断网了才发现全靠云端。4.3 设备筛选、实体命名与区域规划设备同步进来之后不要急着写自动化。先做三件事筛选、命名、分区。筛选是因为有些设备你根本不需要接进来比如某个只用来看电量的插座接进来只会增加实体数量和干扰在集成设置里可以取消勾选不需要同步的设备。命名是重中之重实体名决定了你未来写自动化时的可读性switch.ka_ting_cha_zuo和switch.0674的区别在你写第 50 条自动化时会体现得淋漓尽致。# 命名参考位置 用途 类型拼音或英文均可保持一致 switch.keting_zhudeng # 客厅主灯 cover.zhufang_chuanglian # 主卧窗帘 sensor.ertongfang_wendu # 儿童房温度 binary_sensor.xuanguan_renti # 玄关人体感应分区就是把设备分配到 Home Assistant 的「区域」里。这一步很多人跳过但它直接影响界面的组织方式和语音助手的可用性。区域规划建议按房间来卫生间这种小空间也要单独建不要图省事全丢到「一楼」。我吃过亏早期全塞在一个区域里后来想做「离家时关闭所有非必要设备」结果发现根本没法按区域批量筛选只能一台台列。实体重命名要在 Home Assistant 里做而不是改米家 App 的名字。因为重新同步时集成会以米家那边的名字为准覆盖部分命名所以正确顺序是米家 App 里改好基础名同步进来再在 Home Assistant 里做最终命名和实体 ID 调整。实体 ID 一旦被自动化引用就不要再改改了会断链这个坑我踩过一条跑了半年的自动化因为改了个实体 ID 直接失效排查半天才发现。4.4 更新频率与状态同步的调优集成设置里有和设备状态更新相关的选项云端通道通常是轮询可以设置间隔。默认值一般偏保守为的是减少服务器压力。我的调法分两类对响应要求高的设备开关、灯尽量走本地本地是订阅式推送几乎是实时的走云端的传感器类轮询间隔设到 30 到 60 秒就够因为温度、湿度这类数据本来变化就慢设太快纯属浪费。判断自己的设置是否合理看两个指标一是界面状态和实际操作之间的时间差你可以手动开一盏灯看 Home Assistant 里状态多久跟上二是主机负载设备多、轮询频繁的时候数据库写入会明显增加。如果发现历史曲线很稀疏说明状态上报频率低可以在自动化里用「状态变化」触发而不是依赖轮询精度。提示不要为了追求「实时」把所有设备都设成极短间隔。我试过把几十台设备的间隔压到 5 秒结果主机 CPU 直接飙到 60% 以上数据库一天涨了几百兆。后来统一放到 30 秒体验上几乎没区别负载降了一大截。5. 落地场景把米家设备真正用起来的几套配置装好、配好、命名好接下来才是最有意思的部分——让这些设备真的干活。这一章给三套我自己在用、也帮别人配过的方案包含完整 YAML可以直接改参数用。核心思路是把「设备级控制」升级成「场景级联动」让米家设备和其他品牌的设备在同一个逻辑里协作。5.1 实体 ID 规范自动化可维护的地基在写自动化之前先把实体 ID 的规范定死。我用的规则是类型_位置_用途全小写、下划线分隔、不使用中文。这套规则看起来土但半年后回头看依然一眼能懂。写自动化时引用实体优先用实体 ID 而不是名称因为名称可能会被人改实体 ID 一般不会动。另外建议给关键设备加「标签」比如给所有照明设备打上lighting标签给所有需要离家关闭的设备打上away_off标签。Home Assistant 支持按标签批量操作做「离家模式」这种全局动作时不用一个个列实体直接按标签筛选后续加设备只要打上标签就自动纳入维护成本极低。这一招我是从一个老玩家那里学来的用上之后自动化配置量少了差不多三分之一。# 按标签批量关闭设备的服务调用示例 service: homeassistant.turn_off target: label_id: away_off这段配置的意思是关闭所有带away_off标签的实体。注意不是所有设备类型都支持统一关闭比如传感器是只读的强行调用会报错所以标签要打在可控设备上。5.2 一个跨品牌联动的完整配置示例场景描述玄关有人经过且当前光照低于阈值且时间在日落后到午夜之间则打开玄关灯并把亮度设到 30%如果这个时间家里没人在客厅电视关闭、客厅无人则同时把客厅的氛围灯也打开。这个场景里人体传感器和灯来自米家生态电视状态和氛围灯来自其他品牌正好体现跨品牌联动的价值。automation: - alias: 玄关感应开灯 id: entry_motion_light_on mode: single trigger: - platform: state entity_id: binary_sensor.xuanguan_renti to: on condition: - condition: numeric_state entity_id: sensor.xuanguan_zhaodu below: 60 - condition: time after: sunset before: 23:59:00 action: - service: light.turn_on target: entity_id: light.xuanguan_deng data: brightness_pct: 30 - choose: - conditions: - condition: state entity_id: media_player.keting_dianshi state: off - condition: state entity_id: binary_sensor.keting_youren state: off sequence: - service: light.turn_on target: entity_id: light.keting_fenwei data: brightness_pct: 20几个细节值得说明。第一mode: single防止连续触发造成重复执行人走过传感器的时候可能触发好几次。第二光照条件用的是玄关自己的照度传感器不要用天气服务的数值室内外差别太大。第三动作里用了choose做条件分支比写两条独立自动化更好维护。第四亮度用百分比而不是绝对值将来换灯泡不用改配置。再补一个反向场景人走之后延迟关灯。这个我建议单独写一条自动化触发条件是传感器变off并持续两分钟动作用for实现延迟而不是在动作里写delay。原因是delay会阻塞自动化如果期间又有人进来逻辑会乱而触发器的for是重新计时的。trigger: - platform: state entity_id: binary_sensor.xuanguan_renti to: off for: 00:02:005.3 与语音助手桥接时的注意点设备接进 Home Assistant 之后很多人会顺手把它们暴露给语音助手。这里有个容易翻车的点暴露出去的实体数量会直接决定语音识别的准确率。我最初把所有实体一股脑暴露结果语音助手经常答非所问因为存在大量命名相近的设备。后来我做了两件事一是只在桥接配置里暴露真正需要语音控制的设备传感器、诊断类实体全部排除二是把设备名改得口语化比如「客厅主灯」而不是「客厅吸顶灯_主_左」。排除实体的配置大致是这样# 桥接配置中排除不需要语音控制的实体 filter: exclude_entity_globs: - sensor.*_diagnostic - binary_sensor.*_linkquality - update.* - sensor.*_batteryupdate.*这类实体是固件更新提示暴露出去纯属噪音。电池电量倒是有用但不需要语音控制留在界面看就行。另外提醒一句桥接之后设备名如果有重名语音助手会随机选一个执行这个行为很难调最好的办法是从源头上保证设备名唯一。6. 问题排查实录我踩过的坑与速查表这一章是全文最实用的部分全部来自实际环境。我把问题分成登录类、设备与实体类、稳定性类三组每组给出典型现象、根本原因和我的处理方式。有些问题网上资料很少是我自己看日志摸索出来的记下来供你参考。6.1 登录类问题卡在授权环节怎么办最常见的现象是输入账号密码后页面一直转圈或者跳转到一个空白页。原因通常有三类主机访问外网不稳定、浏览器环境和主机不在同一网络导致回调失败、账号本身触发了风控需要额外验证。处理顺序是先确认主机能正常解析并访问外部服务再换一个和主机同网段的设备上的浏览器重试最后检查账号是不是在别的设备上刚改过密码。还有一种现象是「登录成功但设备列表为空」。这个十有八九是区域选错了账号在某个区域下没有设备自然拉不到。解决办法是回到集成配置里重新授权这次仔细看区域选项。我在帮人排错时遇到过两次都是选了默认区域但账号实际属于另一个区域改过来立刻正常。验证码收不到的情况也偶有发生特别是账号绑定的手机号很久没用过。建议在正式配置前去米家 App 里确认能正常登录、能收到验证码别等到配置流程里才发现问题。如果确实收不到先解决账号本身的问题集成这边帮不上忙。6.2 设备与实体类问题设备不显示、功能不全「设备同步出来了但只有一两个实体」是高频问题。根本原因是设备遵循的设备模型规范只暴露了部分属性或者该型号的能力没有被完整描述。这种情况没有万能解法我的处理方式是先确认固件是不是最新有些老固件的能力描述是残缺的升级之后会多出实体然后去设备页面看「诊断」信息里暴露了哪些属性如果属性本身没有那集成也无能为力。「设备列表里完全没有某台设备」的情况先确认它是否在米家 App 里属于你选择的那个家庭再确认它的连接方式。通过网关中转的子设备、纯蓝牙设备很多时候无法直接出现在集成里需要看网关本身是否被支持。我家里有一批早期传感器最后是通过把网关换成一个支持本地协议的型号才解决的设备本身没换。「实体出现了但状态一直是未知」也遇到过。这类多半是本地连接建立了但读不到值或者云端轮询失败。检查方法是看日志里有没有对应的超时记录然后临时把该设备强制切到云端模式看状态是否恢复。如果云端能读、本地不能读就是本地通道的问题回到网络那一章排查。6.3 稳定性与性能延迟、掉线、负载升高现象可能原因排查动作处理方式控制延迟 2 秒以上走了云端通道看设备页面的通道标注确认局域网连通切本地状态与实物不一致轮询间隔过长观察状态更新频率缩短间隔或改本地订阅设备频繁离线无线信号弱主机侧持续连通测试调整设备位置或加接入点主机负载升高设备多、轮询密看 CPU 与数据库增长放宽轮询间隔排除无用设备升级后集成报错版本不兼容查日志里的导入错误回滚版本或升级主机表格里最值得说的一条是「设备频繁离线」。很多人第一反应是集成有 bug实际上八成是无线环境问题。我的验证方法是在主机上对设备做长时间连通测试统计丢包率同时观察设备离接入点的距离和中间隔墙情况。有次一台阳台传感器天天离线最后发现是金属晾衣架挡在中间挪了十厘米就好了。负载问题也要重视。设备数量上去之后实体注册、状态写入都会消耗资源尤其是历史记录。我的做法是给高频变化但不需要长期记录的实体关闭历史比如某些功率传感器的瞬时值。另外定期清理数据库别让它无限增长。6.4 一次典型的排错过程记录最后分享一次完整的排错过程因为我觉得思路比结论更有价值。现象是客厅主灯在 Home Assistant 里能控制但状态永远显示为开启手动关掉之后界面过一会儿又变回开启。初步判断是状态回传有问题。第一步看日志发现这台设备的本地连接是成功的但有周期性的属性读取超时。第二步换通道强制走云端问题依旧说明不是通道的事。第三步去米家 App 里看App 里状态是准的说明设备本身没问题。第四步怀疑是实体映射错位检查设备页面发现它同时暴露了两个开关实体一个对应主灯一个对应夜灯模式我一直在用错的那个。换到正确的实体之后一切正常。这个案例的教训是遇到状态异常先确认你操作的是不是正确的实体。米家生态里有些设备会暴露多个功能相近的实体尤其是带模式切换的灯具和带多路输出的插座。我现在接完新设备的第一件事就是把所有实体逐个点一遍确认哪个对应哪个写进笔记里。7. 长期维护版本、账号与后续扩展的经验跑通只是开始能不能长期稳定运行取决于维护习惯。这一章聊聊我在长期使用中形成的几条规矩都是踩坑之后总结出来的。版本管理上我的策略是「不追新但不停更」。具体做法是集成有新版本先看更新说明涉及设备同步逻辑或登录方式的等一两天看社区反馈再升纯修复类的小版本可以直接升。升级前一定做快照升级后重点验证三件事登录是否正常、关键设备状态是否正常、自动化是否还能触发。这三项过了基本就没问题。我遇到过升级后某个设备的实体 ID 变了的情况虽然不常见但一旦发生引用了它的自动化会静默失效所以升级后我会专门检查一遍自动化列表里有没有报错。账号安全上专用账号 强密码 单独记录不要和主账号共用。授权之后不要频繁重新授权每次重新授权都可能触发设备重新同步。如果确实需要改密码改完之后集成会掉线重新走一次授权流程即可设备配置不会丢。扩展方向上这套集成只是把设备接进来了真正的价值在于后续的联动。我目前的扩展路径是先把全屋照明和窗帘接进来做统一控制再把传感器数据汇总做环境监测面板最后把能耗类设备的数据接进统计做月度报表。每一步做完再进下一步不要一次性全上出问题时才好定位。最后分享一个小技巧给集成相关的自动化单独建一个分组或者打上统一标签出问题时可以快速定位到受影响的自动化范围。这个习惯让我在一次集成异常中五分钟内就确认了影响面而不是挨个翻几十条自动化。设备接入这件事做到最后拼的不是技术是秩序。 
长河君 · 2026/10/29 16:47:22 · 阅读 1.2k Home Assistant 接入米家设备：ha_xiaomi_home 安装配置与自动化实战
1. 先把路选对ha_xiaomi_home 的定位与我的选择理由在 Home Assistant 里接米家设备这件事我前后折腾了差不多两年早期用第三方轮询方案后来试过拿局域网协议自己抓包再后来换成网关直连。每次换方案都掉一层皮设备一多状态不同步、实体名乱成麻、升级一次挂一片全是家常便饭。直到用上 ha_xiaomi_home 这套由米家生态侧提供的官方 Home Assistant 集成才算真正把这件事稳定下来。这篇内容是整套ha_xiaomi_home 米家设备接入的完整落地记录从环境准备、安装、登录授权、设备同步到实体命名规范、自动化配置和线上排错按我实际跑的流程一步步写清楚目标是让你一次跑通而不是装完之后在社区里到处翻帖子。适合谁看已经有一台长期在线的 Home Assistant 主机、家里至少有五六个米家设备、并且希望把这些设备拉进统一界面做跨品牌联动的人。如果你只是想在手机上看个温湿度用米家 App 就够了没必要上这套东西但如果你想让灯光、窗帘、空调、传感器和别的品牌设备在同一个自动化里说话那这套集成基本是目前最省心的选择。下面的内容会包含完整命令、配置片段、参数取舍和踩坑记录小白可以照着抄有基础的可以直接跳到第 3 章。1.1 三条接入路线的现实差别在动手之前值得先花十分钟把路线想清楚因为选错路线后面再怎么调都是白费。市面上主流的三条路子本质差别在于「数据从哪里来」一条是纯云端轮询Home Assistant 定时去米家服务器要一次状态一条是纯局域网直连设备在本地把状态推给主机还有一条是混合模式云端拿设备清单和账号鉴权本地负责高频状态更新。第一类实现简单、兼容性最广但延迟明显一次轮询几秒钟人走过感应灯亮了又灭这种事基本做不出来第二类响应快、断网可用但对设备型号和网络环境有硬性要求稍微老一点的设备直接不支持。ha_xiaomi_home 走的是第三条路而且做得比较聪明账号登录、家庭结构、设备列表这些低频信息走云端设备的具体属性读写尽量落到局域网。这样你既不用一个个手动填 token又能拿到接近本地直连的响应速度。理解这个分层很关键因为后面 90% 的排错都绕不开一个问题——「这台设备到底走的是云端还是本地」。我在最初部署时没搞清楚这一点看到日志里一堆云端请求就以为本地没生效白折腾了半宿后来才发现是我那台老设备的固件根本不支持本地协议集成已经尽力了。顺带说一句能力边界这套集成基于米家生态统一的设备模型规范也就是说只有遵循这套规范暴露属性的设备才有可能被完整识别。纯蓝牙、纯 Zigbee 且没有网关中转的设备通常拿不到本地通道早期一些封闭协议的设备能出现在列表里但只有少量实体。这一点在后面第 6 章会展开这里先埋个伏笔安装之前先去米家 App 里把那台设备的型号、固件版本、连接方式记下来这份清单会成为你后续排错的第一手资料。1.2 它解决的核心问题把碎片化的设备统一成可编程实体抛开技术细节这套集成真正解决的问题只有一个把米家 App 里那些只能点按钮的设备变成 Home Assistant 里可以读、可以写、可以被自动化引用的实体。听起来简单但它带来的是使用方式的质变。举个具体例子我家玄关有一台人体传感器、一盏吸顶灯、一台空调在米家 App 里它们的关系是固定的、封闭的你只能在预设场景里选接进 Home Assistant 之后这三个设备变成了三个实体我可以写「有人且室内温度高于 26 度才开空调、夜间只开低亮度灯」这种复合条件而且随时改不用等固件更新。能力边界也要说清楚它负责的是「设备接入与状态同步」不负责把米家的自动化规则搬过来也不负责设备固件的升级。你在米家 App 里设置的定时、场景接入之后依然在那里跑两边是并行的。我见过不少人以为接进 Home Assistant 就能把米家 App 卸了结果发现某些设备的本地按钮逻辑还在云端判断卸载后设备直接变「傻」。稳妥做法是米家 App 保留只把它当作设备管理和固件升级的入口日常控制全交给 Home Assistant。两边分工明确出问题也容易定位是哪一层的事。另外要提醒的是账号层面的限制。集成需要用米家账号做一次授权登录授权之后拿到的是这个账号可见范围内的设备和家庭。如果你家里有多个人共用设备或者设备分散在多个「家庭」里建议用一个专门的账号做统一管理把所有设备都共享给它而不是拿主账号去授权。这样做的好处是将来改密码、换手机、家人退群都不会影响集成运行我在第二台房子上就是这么做的半年来一次掉线都没有。1.3 硬件与环境清单开工前的自我检查项目最低要求我的建议说明Home Assistant近两年的稳定版本保持每月小版本更新版本过旧会缺依赖集成加载直接报错主机性能双核 / 2GB 内存四核 / 4GB 以上设备超过 50 台时实体注册很吃内存网络主机与设备同一网段有线连接关闭客户端隔离跨网段本地通道基本不通存储剩余 2GB剩余 8GB 以上快照、日志、数据库都在涨账号可正常登录的米家账号专用账号 设备共享避免主账号变更影响集成网络出口可访问米家云服务保持稳定不要频繁切换首次授权和云端同步必需表格里最容易被忽略的是「同一网段」。我见过太多案例主机的网口插在主路由设备连在二级路由或者访客网络表面上看都是内网实际上隔了一层 NAT本地通道根本发现不了设备。表现出来就是设备能同步出来、状态也能读但控制延迟两三秒日志里全是超时重试。如果你的网络里有多个无线接入点务必确认它们工作在同一个二层网络里并且关闭了「客户端隔离」这类选项。2. 动手前的准备账号、网络、备份三件事正式安装之前我强烈建议先把这三件事做完。听起来像废话但我每次帮人远程排错十次里有七次问题出在这一步没做干净。准备工作的核心逻辑是把不确定性提前消灭掉。安装过程本身其实很简单麻烦的是安装完之后发现「设备不全」「登录不上」「升级炸了没得回滚」而这些问题全都可以在动手前规避。2.1 账号与家庭结构要先理顺打开米家 App先看「我的」里面的家庭列表。如果你有多个家庭或者设备分散在不同家庭成员名下先把它们统一到一个家庭里或者至少确认这些设备都共享给了你准备用来授权的那个账号。集成的同步逻辑是按家庭拉取设备列表的登录之后会让你选择要同步哪些家庭如果一个家庭下有几十台设备而你只想接其中几台也可以在同步阶段做筛选但前提是这些设备得先出现在列表里。我吃过的一次亏是家里老人手机上也登录着同一个账号某天他误操作把几台设备「移出家庭」导致我这边集成里的设备全部变成不可用日志刷了一屏「设备不存在」。后来我改成用专用账号管理其他账号只做共享权限收紧之后这类事再没发生过。另外账号如果开了二次验证授权登录时需要一个验证码确保你能收到别在半夜做这件事短信延迟会让你卡在中途。还有个小细节值得提前处理设备改名。米家 App 里的设备名会带到 Home Assistant 的实体名称里如果你那边叫「客厅灯1」「灯2」「新设备」接进来之后实体名会非常难看后面做自动化时全靠猜。趁还没接先在米家 App 里把设备名改成「客厅主灯」「玄关吸顶灯」这种带位置和用途的描述能省掉后面大量重命名的工作。2.2 网络同网段这件事比你想的重要前面表格提过一次这里展开说。判断标准很简单在 Home Assistant 主机的终端里对设备的局域网地址执行一次连通性测试能通说明在同一个可路由的网段如果设备没有固定地址可以先在路由器后台查一下它的地址。命令大概是这样# 在 Home Assistant 主机上执行替换成设备实际地址 ping -c 4 192.168.1.56 # 顺便看一下主机的网络接口和网段 ip addr show | grep inet 能 ping 通不代表本地协议一定能用但 ping 不通基本可以判定本地通道没戏。另外要确认主机和设备在同一个子网掩码下比如主机是 192.168.1.x/24设备是 192.168.2.x/24即使路由器做了静态路由能互通广播发现也大概率失败因为很多本地协议依赖组播或广播。遇到这种情况最省事的做法是把设备挪到主机所在的网段而不是去折腾路由配置。无线环境也值得看一眼。设备如果连的是 2.4G 频段而主机离接入点很远丢包率高的时候本地状态更新会时断时续表现出来就是「灯的实际状态和界面不一致」。我一般会用主机持续对设备做几十次连通测试看丢包率超过 5% 就考虑加一个接入点或者调整设备位置。这部分不用过度优化但至少要知道自己网络的底子。2.3 三步做一次可靠快照这一步是保命的。集成装好之后会注册大量新实体一旦出问题需要回滚没有快照就只能手动删文件。我的做法是先在「设置 - 系统 - 备份」里创建一个完整备份命名带上日期和「安装前」字样然后单独把配置目录里的关键文件导出一份放在主机之外的存储上最后确认一下备份文件的大小和完整性别备份了个空壳。# 在主机上确认配置目录关键文件的存在与修改时间 ls -lh /config/configuration.yaml ls -lh /config/.storage/ | head -20第二行是我特别推荐看的.storage目录里放的是集成注册的实体、设备、区域等运行时数据安装前后对比一下这个目录的变化能快速定位「集成到底写了什么」。有几次我怀疑集成改坏了东西就是靠对比这个目录找到问题源的。做完这三步再动手心里会踏实很多。3. 安装 ha_xiaomi_home从 HACS 到手动部署准备工作做完正式进入安装。这套集成有两种常见安装方式通过 HACS 添加自定义仓库或者手动下载解压到配置目录。前者适合绝大多数人升级方便后者适合没有 HACS、或者处于离线环境的情况。两种方式最终效果一样装完之后都是custom_components下的一个目录我把两条路都走一遍你自己挑。3.1 HACS 自定义仓库安装最省事的路径如果你已经装了 HACS这条路最快。打开 HACS进入「集成」页面点击右上角三个点选择「自定义仓库」在地址栏填入这套集成的官方仓库地址在 HACS 里搜索集成名也能直接找到找不到再走自定义仓库类别选「Integration」然后添加。添加完成后在 HACS 的集成列表里搜索集成名点进去下载选择最新稳定版本。下载完成会提示需要重启先别急着重启。这里有个我踩过的坑HACS 下载完成后有些版本会在页面里显示「需要重启才能生效」但同时集成目录里可能还在写入文件如果你手快立刻重启可能加载到一个残缺的目录表现出来就是集成列表里能看到名字但点添加就报错。稳妥做法是下载完成后等十几秒用命令行确认目录结构和文件数量正常再重启。# 确认目录存在且文件数量正常正常应在几十个文件量级 ls -la /config/custom_components/xiaomi_home/ find /config/custom_components/xiaomi_home/ -type f | wc -l第二条命令输出的数字如果只有个位数说明下载不完整回 HACS 里重新下载一次。这个检查看起来啰嗦但能省掉后面「集成加载失败」的一整轮排查。3.2 手动部署解压到 custom_components 的完整流程没有 HACS 的话手动部署也不复杂核心就一句话把集成目录整个放进/config/custom_components/下目录名必须和集成内部声明的一致不能自己改名。具体操作我一般这样走先在电脑上下载发布包解压后确认里面有一层包含清单文件的目录然后通过文件编辑器或者共享目录把整个目录传到主机的custom_components下。# 假设已经把解压后的目录放到了 /tmp ls /tmp/ha_xiaomi_home/ # 确认里面有清单文件和组件代码 mv /tmp/ha_xiaomi_home /config/custom_components/xiaomi_home chown -R root:root /config/custom_components/xiaomi_home find /config/custom_components/xiaomi_home/ -name manifest.json -maxdepth 1最后一条命令必须能输出一个清单文件路径这是 Home Assistant 识别一个目录是不是有效集成的依据。如果清单文件在更深一层的子目录里说明你解压多套了一层需要把里面的内容往上提一级。这个错误极其常见我至少帮五个人修过——他们把压缩包整个解压结果变成custom_components/xiaomi_home/ha_xiaomi_home/...集成列表里永远看不到。手动部署的另一个注意点是权限。用普通用户通过 SMB 传文件上去有时候文件的属主和权限不对集成加载时读不到文件日志里会报权限错误。上面那条chown就是干这个的如果你的环境不是以 root 运行改成对应的运行用户即可。3.3 重启后怎么确认装对了不管走哪条路最后都要重启 Home Assistant。重启完成后进入「设置 - 设备与服务」点击右下角「添加集成」搜索集成名如果能搜到并且能点进去说明安装成功。如果搜不到先看日志。# 查看启动日志里与集成相关的记录 grep -i xiaomi /config/home-assistant.log | tail -30正常情况下你应该看到集成被加载、版本号被打印出来。如果看到类似「无法导入依赖」「找不到模块」的字样大概率是 Python 依赖没装好或者版本不匹配这时候先确认 Home Assistant 版本是否太旧再检查网络能不能正常访问依赖源。还有一种情况是日志里一片安静什么也没有那基本就是目录结构或清单文件的问题回到 3.2 那一步重新确认。我个人的习惯是在这一步就把版本号记下来写到自己的运维笔记里。原因很简单这套集成更新比较频繁有些新版本会改设备同步的行为出问题时能快速判断「是不是升级导致的」。第 7 章会讲升级策略这里先留个记录。4. 配置实操登录、授权与设备同步安装只是把代码放到位真正的重头戏是配置。这一步走顺了后面基本就是一劳永逸走不顺会卡在各种奇怪的地方。我把整个流程拆成四段登录授权、控制模式选择、设备筛选与命名、更新频率调优。按顺序来不要跳步。4.1 添加集成与授权登录的完整走位在「设备与服务」里点「添加集成」搜索集成名进入配置向导。第一步通常会让你选择登录方式或者服务器区域这里要选你账号实际所属的区域选错会登录成功但设备列表是空的非常迷惑。接着会跳转到授权页面输入米家账号和密码如果开了二次验证再填一次验证码。授权成功后会回到 Home Assistant弹出家庭选择。如果你有多个家庭这里会列出来勾选需要同步的。我的建议是第一次先只勾一个家庭、且设备较少的那个跑通流程之后再逐步加这样出问题时排查范围小。勾选完成后点提交集成开始拉取设备列表设备多的话会转圈几十秒到几分钟别急着刷新页面刷新可能导致配置流程中断得从头再来。注意授权过程中如果页面停在跳转界面不动先检查主机能不能正常访问外网。这一步是纯云端交互网络不通会一直卡着。另外授权用的浏览器最好和 Home Assistant 在同一网络环境下操作避免回调地址对不上。登录成功后集成会在「设备与服务」里生成一个条目点进去能看到设备和实体数量。到这一步最难的关卡已经过了剩下的都是锦上添花。4.2 云端与本地两种模式的取舍配置过程里会涉及控制模式的选择这也是整套方案最值得理解的地方。简单说云端模式是「所有读写都经过米家服务器」优点是兼容性最好任何能同步出来的设备都能控制缺点是延迟高、依赖外网服务器抖动时体验很差。本地模式是「在局域网内直接和设备通信」优点是快、断网可用缺点是对设备和网络有要求不支持的设备只能退回云端。我的实际配置是混合默认让集成自动判断支持的走本地不支持的走云端然后在集成设置里对个别关键设备手动指定。判断某台设备走的是哪条路可以看设备页面上的标注或者在日志里看有没有本地连接建立成功的记录。这里给个实用建议照明、窗帘、开关这类需要即时响应的设备优先保证本地传感器类即使走云端也能接受因为它们本来就低频上报。还有一个常被忽略的细节本地模式要求主机能主动连到设备的端口如果你的网络里有防火墙或者设备开了隔离本地连接会一直失败然后静默退回云端界面上看不出来只有日志里有记录。我建议装完之后专门花时间确认一遍关键设备的通道类型别等到某天断网了才发现全靠云端。4.3 设备筛选、实体命名与区域规划设备同步进来之后不要急着写自动化。先做三件事筛选、命名、分区。筛选是因为有些设备你根本不需要接进来比如某个只用来看电量的插座接进来只会增加实体数量和干扰在集成设置里可以取消勾选不需要同步的设备。命名是重中之重实体名决定了你未来写自动化时的可读性switch.ka_ting_cha_zuo和switch.0674的区别在你写第 50 条自动化时会体现得淋漓尽致。# 命名参考位置 用途 类型拼音或英文均可保持一致 switch.keting_zhudeng # 客厅主灯 cover.zhufang_chuanglian # 主卧窗帘 sensor.ertongfang_wendu # 儿童房温度 binary_sensor.xuanguan_renti # 玄关人体感应分区就是把设备分配到 Home Assistant 的「区域」里。这一步很多人跳过但它直接影响界面的组织方式和语音助手的可用性。区域规划建议按房间来卫生间这种小空间也要单独建不要图省事全丢到「一楼」。我吃过亏早期全塞在一个区域里后来想做「离家时关闭所有非必要设备」结果发现根本没法按区域批量筛选只能一台台列。实体重命名要在 Home Assistant 里做而不是改米家 App 的名字。因为重新同步时集成会以米家那边的名字为准覆盖部分命名所以正确顺序是米家 App 里改好基础名同步进来再在 Home Assistant 里做最终命名和实体 ID 调整。实体 ID 一旦被自动化引用就不要再改改了会断链这个坑我踩过一条跑了半年的自动化因为改了个实体 ID 直接失效排查半天才发现。4.4 更新频率与状态同步的调优集成设置里有和设备状态更新相关的选项云端通道通常是轮询可以设置间隔。默认值一般偏保守为的是减少服务器压力。我的调法分两类对响应要求高的设备开关、灯尽量走本地本地是订阅式推送几乎是实时的走云端的传感器类轮询间隔设到 30 到 60 秒就够因为温度、湿度这类数据本来变化就慢设太快纯属浪费。判断自己的设置是否合理看两个指标一是界面状态和实际操作之间的时间差你可以手动开一盏灯看 Home Assistant 里状态多久跟上二是主机负载设备多、轮询频繁的时候数据库写入会明显增加。如果发现历史曲线很稀疏说明状态上报频率低可以在自动化里用「状态变化」触发而不是依赖轮询精度。提示不要为了追求「实时」把所有设备都设成极短间隔。我试过把几十台设备的间隔压到 5 秒结果主机 CPU 直接飙到 60% 以上数据库一天涨了几百兆。后来统一放到 30 秒体验上几乎没区别负载降了一大截。5. 落地场景把米家设备真正用起来的几套配置装好、配好、命名好接下来才是最有意思的部分——让这些设备真的干活。这一章给三套我自己在用、也帮别人配过的方案包含完整 YAML可以直接改参数用。核心思路是把「设备级控制」升级成「场景级联动」让米家设备和其他品牌的设备在同一个逻辑里协作。5.1 实体 ID 规范自动化可维护的地基在写自动化之前先把实体 ID 的规范定死。我用的规则是类型_位置_用途全小写、下划线分隔、不使用中文。这套规则看起来土但半年后回头看依然一眼能懂。写自动化时引用实体优先用实体 ID 而不是名称因为名称可能会被人改实体 ID 一般不会动。另外建议给关键设备加「标签」比如给所有照明设备打上lighting标签给所有需要离家关闭的设备打上away_off标签。Home Assistant 支持按标签批量操作做「离家模式」这种全局动作时不用一个个列实体直接按标签筛选后续加设备只要打上标签就自动纳入维护成本极低。这一招我是从一个老玩家那里学来的用上之后自动化配置量少了差不多三分之一。# 按标签批量关闭设备的服务调用示例 service: homeassistant.turn_off target: label_id: away_off这段配置的意思是关闭所有带away_off标签的实体。注意不是所有设备类型都支持统一关闭比如传感器是只读的强行调用会报错所以标签要打在可控设备上。5.2 一个跨品牌联动的完整配置示例场景描述玄关有人经过且当前光照低于阈值且时间在日落后到午夜之间则打开玄关灯并把亮度设到 30%如果这个时间家里没人在客厅电视关闭、客厅无人则同时把客厅的氛围灯也打开。这个场景里人体传感器和灯来自米家生态电视状态和氛围灯来自其他品牌正好体现跨品牌联动的价值。automation: - alias: 玄关感应开灯 id: entry_motion_light_on mode: single trigger: - platform: state entity_id: binary_sensor.xuanguan_renti to: on condition: - condition: numeric_state entity_id: sensor.xuanguan_zhaodu below: 60 - condition: time after: sunset before: 23:59:00 action: - service: light.turn_on target: entity_id: light.xuanguan_deng data: brightness_pct: 30 - choose: - conditions: - condition: state entity_id: media_player.keting_dianshi state: off - condition: state entity_id: binary_sensor.keting_youren state: off sequence: - service: light.turn_on target: entity_id: light.keting_fenwei data: brightness_pct: 20几个细节值得说明。第一mode: single防止连续触发造成重复执行人走过传感器的时候可能触发好几次。第二光照条件用的是玄关自己的照度传感器不要用天气服务的数值室内外差别太大。第三动作里用了choose做条件分支比写两条独立自动化更好维护。第四亮度用百分比而不是绝对值将来换灯泡不用改配置。再补一个反向场景人走之后延迟关灯。这个我建议单独写一条自动化触发条件是传感器变off并持续两分钟动作用for实现延迟而不是在动作里写delay。原因是delay会阻塞自动化如果期间又有人进来逻辑会乱而触发器的for是重新计时的。trigger: - platform: state entity_id: binary_sensor.xuanguan_renti to: off for: 00:02:005.3 与语音助手桥接时的注意点设备接进 Home Assistant 之后很多人会顺手把它们暴露给语音助手。这里有个容易翻车的点暴露出去的实体数量会直接决定语音识别的准确率。我最初把所有实体一股脑暴露结果语音助手经常答非所问因为存在大量命名相近的设备。后来我做了两件事一是只在桥接配置里暴露真正需要语音控制的设备传感器、诊断类实体全部排除二是把设备名改得口语化比如「客厅主灯」而不是「客厅吸顶灯_主_左」。排除实体的配置大致是这样# 桥接配置中排除不需要语音控制的实体 filter: exclude_entity_globs: - sensor.*_diagnostic - binary_sensor.*_linkquality - update.* - sensor.*_batteryupdate.*这类实体是固件更新提示暴露出去纯属噪音。电池电量倒是有用但不需要语音控制留在界面看就行。另外提醒一句桥接之后设备名如果有重名语音助手会随机选一个执行这个行为很难调最好的办法是从源头上保证设备名唯一。6. 问题排查实录我踩过的坑与速查表这一章是全文最实用的部分全部来自实际环境。我把问题分成登录类、设备与实体类、稳定性类三组每组给出典型现象、根本原因和我的处理方式。有些问题网上资料很少是我自己看日志摸索出来的记下来供你参考。6.1 登录类问题卡在授权环节怎么办最常见的现象是输入账号密码后页面一直转圈或者跳转到一个空白页。原因通常有三类主机访问外网不稳定、浏览器环境和主机不在同一网络导致回调失败、账号本身触发了风控需要额外验证。处理顺序是先确认主机能正常解析并访问外部服务再换一个和主机同网段的设备上的浏览器重试最后检查账号是不是在别的设备上刚改过密码。还有一种现象是「登录成功但设备列表为空」。这个十有八九是区域选错了账号在某个区域下没有设备自然拉不到。解决办法是回到集成配置里重新授权这次仔细看区域选项。我在帮人排错时遇到过两次都是选了默认区域但账号实际属于另一个区域改过来立刻正常。验证码收不到的情况也偶有发生特别是账号绑定的手机号很久没用过。建议在正式配置前去米家 App 里确认能正常登录、能收到验证码别等到配置流程里才发现问题。如果确实收不到先解决账号本身的问题集成这边帮不上忙。6.2 设备与实体类问题设备不显示、功能不全「设备同步出来了但只有一两个实体」是高频问题。根本原因是设备遵循的设备模型规范只暴露了部分属性或者该型号的能力没有被完整描述。这种情况没有万能解法我的处理方式是先确认固件是不是最新有些老固件的能力描述是残缺的升级之后会多出实体然后去设备页面看「诊断」信息里暴露了哪些属性如果属性本身没有那集成也无能为力。「设备列表里完全没有某台设备」的情况先确认它是否在米家 App 里属于你选择的那个家庭再确认它的连接方式。通过网关中转的子设备、纯蓝牙设备很多时候无法直接出现在集成里需要看网关本身是否被支持。我家里有一批早期传感器最后是通过把网关换成一个支持本地协议的型号才解决的设备本身没换。「实体出现了但状态一直是未知」也遇到过。这类多半是本地连接建立了但读不到值或者云端轮询失败。检查方法是看日志里有没有对应的超时记录然后临时把该设备强制切到云端模式看状态是否恢复。如果云端能读、本地不能读就是本地通道的问题回到网络那一章排查。6.3 稳定性与性能延迟、掉线、负载升高现象可能原因排查动作处理方式控制延迟 2 秒以上走了云端通道看设备页面的通道标注确认局域网连通切本地状态与实物不一致轮询间隔过长观察状态更新频率缩短间隔或改本地订阅设备频繁离线无线信号弱主机侧持续连通测试调整设备位置或加接入点主机负载升高设备多、轮询密看 CPU 与数据库增长放宽轮询间隔排除无用设备升级后集成报错版本不兼容查日志里的导入错误回滚版本或升级主机表格里最值得说的一条是「设备频繁离线」。很多人第一反应是集成有 bug实际上八成是无线环境问题。我的验证方法是在主机上对设备做长时间连通测试统计丢包率同时观察设备离接入点的距离和中间隔墙情况。有次一台阳台传感器天天离线最后发现是金属晾衣架挡在中间挪了十厘米就好了。负载问题也要重视。设备数量上去之后实体注册、状态写入都会消耗资源尤其是历史记录。我的做法是给高频变化但不需要长期记录的实体关闭历史比如某些功率传感器的瞬时值。另外定期清理数据库别让它无限增长。6.4 一次典型的排错过程记录最后分享一次完整的排错过程因为我觉得思路比结论更有价值。现象是客厅主灯在 Home Assistant 里能控制但状态永远显示为开启手动关掉之后界面过一会儿又变回开启。初步判断是状态回传有问题。第一步看日志发现这台设备的本地连接是成功的但有周期性的属性读取超时。第二步换通道强制走云端问题依旧说明不是通道的事。第三步去米家 App 里看App 里状态是准的说明设备本身没问题。第四步怀疑是实体映射错位检查设备页面发现它同时暴露了两个开关实体一个对应主灯一个对应夜灯模式我一直在用错的那个。换到正确的实体之后一切正常。这个案例的教训是遇到状态异常先确认你操作的是不是正确的实体。米家生态里有些设备会暴露多个功能相近的实体尤其是带模式切换的灯具和带多路输出的插座。我现在接完新设备的第一件事就是把所有实体逐个点一遍确认哪个对应哪个写进笔记里。7. 长期维护版本、账号与后续扩展的经验跑通只是开始能不能长期稳定运行取决于维护习惯。这一章聊聊我在长期使用中形成的几条规矩都是踩坑之后总结出来的。版本管理上我的策略是「不追新但不停更」。具体做法是集成有新版本先看更新说明涉及设备同步逻辑或登录方式的等一两天看社区反馈再升纯修复类的小版本可以直接升。升级前一定做快照升级后重点验证三件事登录是否正常、关键设备状态是否正常、自动化是否还能触发。这三项过了基本就没问题。我遇到过升级后某个设备的实体 ID 变了的情况虽然不常见但一旦发生引用了它的自动化会静默失效所以升级后我会专门检查一遍自动化列表里有没有报错。账号安全上专用账号 强密码 单独记录不要和主账号共用。授权之后不要频繁重新授权每次重新授权都可能触发设备重新同步。如果确实需要改密码改完之后集成会掉线重新走一次授权流程即可设备配置不会丢。扩展方向上这套集成只是把设备接进来了真正的价值在于后续的联动。我目前的扩展路径是先把全屋照明和窗帘接进来做统一控制再把传感器数据汇总做环境监测面板最后把能耗类设备的数据接进统计做月度报表。每一步做完再进下一步不要一次性全上出问题时才好定位。最后分享一个小技巧给集成相关的自动化单独建一个分组或者打上统一标签出问题时可以快速定位到受影响的自动化范围。这个习惯让我在一次集成异常中五分钟内就确认了影响面而不是挨个翻几十条自动化。设备接入这件事做到最后拼的不是技术是秩序。