★ FEATURED ARTICLE 玩 Home Assistant 的到 ESPHome 这一步基本都逃不过一个问题手里的设备固件烧好了到底用原生 API 跟 HA 对接还是走 MQTT我早期也是照着网上教程无脑选了 MQTT觉得听说过的东西就是主流方案结果折腾了好几个晚上topic 写了一堆排错排到头大。后来换回原生 API 才发现官方默认给的东西其实早就够用了。这篇就专门把这两种接入方式放在一起讲透——它们背后是怎么工作的、实际用起来差在哪、什么时候真的需要 MQTT以及各自落地时我踩过的坑和给到的建议。如果你手里已经有几块 ESP32 或 ESP8266正准备接入 HA这篇能帮你少走不少弯路。1. 两种接入方式到底是什么1.1 原生 API官方默认给的直连通道ESPHome 固件里默认就启用了 API 组件注意是“默认”不是“额外安装”。你把固件刷进去之后这块开发板实际上已经在 local network 里开了一个长期运行的 TCP 服务端口是 6053。HA 这边只要安装了官方的 ESPHome 集成通过集成去连接这个端口两边就建立了实时的双向长连接。这意味着设备端状态一旦变化直接就推给了 HA不需要轮询也没有中间人转发。我打个比方原生 API 就像是两个工位挨着坐的同事有问题转头就能说不需要通过前台也不需要写邮件。因为是长连接数据从设备到 HA 面板的链路非常短实时性和稳定性天然就有优势。而且 HA 在集成管理页面里能自动发现 ESPHome 设备刷完固件点两下实体就全部自动出现了不需要你手工定义任何一个 entity——这是原生 API 体验上最爽的地方。当然这个“默认”是有条件的。新版 ESPHome 编译时如果你没有显式去掉 api 配置那 api 就是开着的。如果你在 YAML 里写了 api:这代表你明确开启了它。需要注意的是老版本存在 API 加密不强制的情况但从某个版本开始加密变成默认推荐后面我会专门说你实际配置时怎么处理这个加密 key。1.2 MQTT加一个中间层换来独立和解耦MQTT 的逻辑则完全不同。设备不直接跟 HA 说话而是通过一个独立的消息代理broker做中转。设备端把状态数据发布到某个主题topic上HA 订阅这些主题反过来 HA 发指令也是发布到另一个主题设备再订阅它。你不再需要 API 的长连接设备跟 HA 之间可以说完全解耦了——甚至 HA 掉线了设备照样能跟 broker 通信跟其他节点通信。MQTT 的优点是生态和标准。它是物联网领域的事实消息协议不光 HA 支持Node-RED、手机 App、各种其他的智能家居系统基本都认它。如果你后期有把设备数据接出去做可视化、做日志分析或者自建一套不依赖 HA 的监控系统MQTT 的用途就突显出来了。但缺点也很明显多引入了一个 broker网络链路变成了 设备 → broker → HA。配置复杂度也上了一大截每个实体都要设计主题传感器状态要写 state_topic开关要写 command_topic设备上下线还得维护 availability topic这些头一回碰的人绝对会头疼。1.3 直接对比一张表看懂两边的差异对比维度原生 APIMQTT额外依赖不需要HA 内置集成直连需要 MQTT broker一般用 HA 官方 Mosquitto 插件设备发现自动HA 能直接发现需要 MQTT discovery 配合若不用则需手动配置 topic实体配置零手工配置固件里定义什么HA 自动生成需要逐实体维护 topic或依赖 discovery 自动创建链路结构设备 → HA直接长连接设备 → broker → HA经中间层转发加密支持内置 API encryption开箱可用TLS 需单独配置且 ESPHome 配置相对繁琐跨系统能力基本绑定 HA 生态标准协议任何 MQTT 客户端都能接调试方式HA 日志 ESPHome 日志定位链路短可直接订阅 topic 观察报文但链路环节多设备离线检测HA 集成自动维护连接状态需配置 availability topic否则离线状态不准2. 选型之前必须搞懂的三个底层逻辑2.1 依赖关系HA 挂了你的设备还能干活吗原生 API 模式下ESPHome 设备跟 HA 之间是强耦合的依赖关系。HA 死了设备确实不会死——设备本身的自动化逻辑照常跑比如你用 ESPHome 写了本地继电器逻辑那 HA 掉线后该开关还是能开关。但如果你依赖 HA 侧做的自动化、仪表盘、语音控制那这一整条就全部断掉了。HA 恢复之后设备会自动重新建立连接这个恢复过程不算慢实测一般十秒左右。而 MQTT 模式下解耦程度取决于 broker 跑在哪。如果你用的是 HA 的“Mosquitto broker”加载项那 HA 挂掉等于 broker 也跟着挂所谓解耦其实并没有真正出现只是链路中间加了一个跟 HA 同生共死的代理。只有当 broker 跑在独立设备上比如某台树莓派、软路由甚至云服务器MQTT 的解耦价值才真正落在实处。我见过不少玩家把 MQTT 挂在自己路由器上HA 重装、升级或日常抽风时家里的 ESPHome 设备照常通过 MQTT 相互通信——这才叫解耦。如果你只是想在 HA 上面简化配置那这个逻辑对你就不重要。2.2 状态同步谁推谁拉决定了调试手感原生 API 的通信模型是设备主动推状态。ESPHome 设备上任何一个传感器更新了比如温度变了 0.1 度它会立刻把新值通过长连接推给 HA。HA 不需要问推了它收。所以你在 HA 仪表盘上观察温度曲线、开关状态几乎是零延迟的而且状态乱序、缺失这类问题极少出现因为链路是一对一的完整通道。MQTT 呢设备也是主动往 broker publishHA 也是订阅理论上也是推但由于中间隔着 broker汇报频率、QoS、retain 设置都会影响实际体验。你设置了 retain 标志设备发送的最后一条消息会被 broker 存下来HA 订阅时马上能拿到旧值如果不设HA 只有等设备下一次发布才能收到数据。ESPHome 的 MQTT 组件对 retain 的默认行为跟不同平台、不同实体类型还有细微差别我自己就被“为什么开关状态面板上不刷新”这个问题坑过一次最后发现就是 retain 没设置对。从调试手感来说MQTT 让人又爱又恨好处是你可以在电脑上用 MQTT Explorer 之类的工具直接盯着那些 topic 的实时内容设备发啥都看得清清楚楚坏处是消息在流转过程中的任何一个环节出了问题你都得分别排查设备、broker、订阅端三段链路而原生 API 只有两端出问题定位起来要快得多。2.3 设备数量和刷固件频率的影响网上有个说法是设备一多MQTT 才更好用。这个我只能说部分认可。从资源占用上看原生 API 每个设备跟 HA 之间是一条独立长连接如果家里有三十个 ESP 设备HA 就要维护三十条连接。MQTT 同样也是三十个连接但都汇聚到了 brokerHA 只跟 broker 有一条连接。在 HA 本身负载就比较高的时候三十条连接和一条连接确实存在性能差异不过实际上 HA 对这些 ESPHome 连接的并发处理能力并不弱普通设备数量根本到不了瓶颈。真正的瓶颈反而在配置管理上。原生 API 的设备只要固件里定义好实体HA 侧完全不需要额外维护。而 MQTT 越用得多topic 数量就越爆炸——每个设备至少三四个 topic三十个设备就是上百个。如果你依赖 MQTT discovery 自动生成实体那还稍微省点心一旦需要手动配置某个阈值传感器或者 fallback 逻辑光翻 topic 记录就够呛。换一个角度说如果你频繁改固件、反复刷机测试原生 API 的体验完胜。刷完机设备自动出现在 HA 里即使改名刷机删除旧设备重新接入也是很自然的流程。MQTT 的话刷一次机broker 里残留的 retained 消息可能要手动清理discovery 清理不及时还容易出现“幽灵实体”这个细节可能只有折腾多了才感同身受。3. 原生 API 接入实操记录3.1 三步完成接入从烧录到实体出现第一步确认 ESPHome 配置里有 API 组件。ESPHome 的 YAML 里正常会长这样esphome: name: living_room_sensor platform: esp32 board: devkitv1 api: encryption: key: base64编码的加密密钥如果你没有特别写过 api 配置块很可能固件默认还是带着加密的 API。这时你需要用esphome命令行重新生成密钥或者在编辑配置时让它自动生成。要注意不同版本对 api 配置块的默认行为不一样最稳的做法是显式写上api:并且把加密 key 也写上。第二步编译并刷入固件。这一步对 ESPHome 老手没什么可说的但如果你是第一次折腾建议直接用 ESPHome Dashboard 网页端操作可视化选择设备、查看日志都更友好。刷完把开发板接上电源等待它在局域网内广播。第三步在 HA 里添加集成。打开“设置 → 设备与服务 → 添加集成 → ESPHome”如果设备跟 HA 在同一局域网HA 会自动列出设备名你点一下就完成接入。如果没发现可以手动输入设备的 IP 地址前提是你路由器的 DHCP 给设备绑定过固定 IP。集成添加后设备里所有传感器、开关、灯等实体直接就出现在 HA 实体列表里了不用你做任何映射。这里有个小提示如果加密 key 填错了HA 集成会提示“handshake failed”这时候不必怀疑网络先回 ESPHome 配置里核对 key 是否跟 HA 填的一致。3.2 加密配置失败的经历我早期被加密这个细节坑过一次。当时固件里写了 API 加密但 HA 集成里添加设备时直接收到的提示不是“要填 key”而是“连接失败”。差了半天日志才发现是新版 ESPHome 要求必须先把加密 key 填进集成而且这个 key 跟固件的 base64 字符串必须是完全一致的。后来我总结了一套稳妥的流程先在 ESPHome 配置文件里手动指定一个 key比如用esphome config命令或者在线生成工具生成一段 base64 字符串填进 YAML然后刷固件再然后在 HA 中添加集成时直接粘贴同一个 key。这样操作之后后续每次改配置刷固件只要 key 没变HA 都不用重新配置设备重启后自动重连。顺带一句API 加密默认走的是 Noise 协议加密隧道比早期完全没有加密的状态安全得多。虽然家庭局域网内被恶意篡改的概率很小但智能家居设备如果带了状态上报功能加密之后固件升级、远程访问这些场景就都稳当很多。3.3 原生 API 接入后的扩展玩法很多刚接触 ESPHome 的人不知道原生 API 不止能同步传感器状态它还能直接调用 ESPHome 暴露的服务。你在 ESPHome 配置里写一个自定义脚本比如一键重启某个外设或者复杂一点的本地自动化HA 侧通过 call service 也能触发它不需要走任何 MQTT 指令。API 模式下 ESPHome 的任何实体天然支持 HA 的“设备触发器”比如设备的按键状态可以被 HA 自动化直接捕获。这比 MQTT 里要额外配置 binary_sensor 再写模板要省事得多。再比如你想在 HA 里查看“每台设备的连接信号强度”或者 WiFi 信号原生 API 模式下 ESPHome 会默认上报一些诊断信息包括 IP、MAC、信号强度、编译版本这些在 HA 的设备页面直接能看到。MQTT 模式下这些信息能不能上报、上报哪些就完全取决于你在 ESPHome YAML 里有没有写对应的 sensor 配置了。4. MQTT 接入实操记录4.1 先准备好 brokerMosquitto 就不是点了就完的MQTT 方案的第一步是 broker。最简单的是在 HA 里装 “Mosquitto broker” 加载项装完启动默认监听 1883 端口但注意没有配置任何账号。你需要至少创建一个 HA 用户作为 MQTT 账号然后在加载项配置里它默认会用 HA 用户体系做认证。我不止一次看到有人在 MQTT 集成配置时逻辑混乱HA 集成的 MQTT 配置要求填 broker 地址、端口、账号密码但是默认的 Mosquitto 插件文档写得并不直白新人很容易在上面的“配置”里填写了账号密码后依然连不上。这里窍门在于加载项的配置面板里默认就有“username”和“password”字段你要先用这两项创建一个专用 MQTT 用户然后 MQTT 集成配置里填同样的账号密码。如果你的目标是真正独立运行建议把 Mosquitto 装到树莓派或者软路由上设置独立的用户名密码然后用 HA 的 MQTT 集成去连接这个外部 broker。这样 HA 重启升级不会影响 brokerMQTT 设备之间的消息也完全不依赖 HA。4.2 ESPHome 的 MQTT 配置与 topic 设计思路在 ESPHome 里开启 MQTT 很简单YAML 里加这样一段mqtt: broker: 192.168.1.100 port: 1883 username: mqtt_user password: mqtt_pass discovery: true discovery_prefix: homeassistant这里的关键是discovery: true。开启了 discovery 之后ESPHome 会按照 Home Assistant 的 MQTT Discovery 规范自动发布一批配置消息HA 收到后会自动创建实体省去手动配置 topic 的麻烦。对于传感器、二进制传感器、开关这些基本实体类型ESPHome 的 discovery 工作得很顺畅基本你刷完固件设备出现在 HA 里也就是半自动的事。但如果你想要更大的自由度比如某些实体不想被 discovery 发现或者要定制 availability 提示、设置 entity_id那还是要回到手动配置。手写 topic 时我习惯按“设备名/实体类型/实体名”的层级设计比如living_room_sensor/temperature/state、living_room_lamp/command。结构化的 topic 命名在后期维护多设备时要能少死很多脑细胞。从我自己使用体验来看ESPHome 的 MQTT 组件并不是完全照搬所有实体类型的自动发现能力。复杂一点的比如模板开关、风扇、RGB 灯MQTT 方式下你要配置的属性会多很多经常需要反复翻文档确认字段。而原生 API 模式下根本没有这个概念这也解释了为什么很多人用 MQTT 一次两次就放弃了。4.3 MQTT 接入比想象中麻烦的几个点第一是 availability 的坑。ESPHome 设备通过 MQTT 上报传感器数据但设备本身掉线了HA 那边实体还保留着最后的值看起来像可用但实际上已经死了。原生 API 的集成会自动把实体标为不可用而 MQTT 下你需要额外配置 availability topic。ESPHome 在配置里其实有默认的 availability 逻辑但前提是你要把它打开并设置好 retained 消息。这块漏了后面排查“为什么传感器一直显示旧值”会耗费大量时间。第二是 discovery 的清理。每次刷固件ESPHome 都会重新发布 discovery 消息但它不会每次都把旧消息删干净。HA 端如果残留了旧的实体或者旧的 device registry设备改名之后经常出现旧实体扔不掉。要彻底清除往往得去 HA 的 MQTT 集成里手动删除“已发现的实体”重开 MQTT discovery 或者删除 broker 里残留的 topic。第三是状态上报频率。ESPHome 的 MQTT 组件对每个传感器的上报频率是可以设置的默认如果传感器频繁变化那它发出的消息量也大。MQTT broker 本身没问题但如果你在一个弱网的 WiFi 环境下消息频繁发布可能导致丢包。原生 API 的推送通道通常更稳毕竟是一对一的会话帮我解决了之前 MQTT 偶尔漏状态的问题。5. 实测对比响应速度、稳定性、断线重连5.1 响应速度到底差多少我自己做了个最简单的测试用 ESP32 接一个开关按钮分别在原生 API 和 MQTT 下触发看 HA 前端状态变化需要多久。原生 API 模式下按下去到 HA 面板反映基本是瞬时体感 50 到 100 毫秒内MQTT 模式下经过本机 broker 中转稍微多一点延迟但也只有 150 到 250 毫秒左右。日常使用中你根本感觉不出这个差别除非你是拿着秒表去掐或者要求毫秒级联动的场景比如传感器触发里连着多路继电器那原生 API 的低延迟优势才有质的体现。移动端接入的话HA 前端从手机到 HA 的链路消耗其实占了大头设备到 HA 那一段的 100 毫秒差异在远程访问场景下根本不值一提。所以不要因为“MQTT 会慢”这种说法就直接否定它绝大多数家庭应用场景延迟差异可忽略。5.2 网络异常时的表现我用一个常见的场景来说家里的 WiFi 出现抖动或者路由器重新拨号。原生 API 模式下ESPHome 设备跟 HA 的连接会断掉然后设备会按照指数退避策略持续重连。由于这种连接是专用的长连接恢复之后门锁、传感器状态会在几秒内补齐并推送全部当前状态整体是无感的。MQTT 模式下设备跟 broker 的连接同样会断掉但只要 broker 还活着重连之后 retained 消息可以帮你拉起最后的“已上报状态”但前提是你把 retain 全部正确配置了而且消息的 QoS 设置也要合适。如果 QoS 为 0消息可能直接就丢了。我在实际使用中碰到过 WiFi 信号弱的场景MQTT 模式漏传感器数据的频率明显更高因为 Wi-Fi 环境里 MQTT 包很容易因为无线干扰而丢失而 ESPHome 原生 API 的长连接在链路层有更多重传机制兜底。当然如果你把 MQTT 的 QoS 调到 1这个差距可以缩小但设备端的计算和消息开销也会增加。5.3 重连恢复与 HA 重启的差异另一个体感差异明显的是 HA 重启。HA 重启时原生 API 那边的连接全部会断掉设备端收到断开后自动重连整个过程大概几秒到十几秒。重启完成后设备会重新连接并推送当前状态基本你看到仪表盘恢复时数据已经是最新的。MQTT 方案下HA 重启意味着如果你用的是 HA 内置的 Mosquitto那 broker 也一起重启了客户端全部断开重启后设备重连 broker再重新上报状态恢复周期和 API 差不多。但如果 broker 是独立的那 HA 重启过程中设备跟 broker 的通信完全不中断HA 起来后去订阅 topic 能立刻拿到 retained 旧值然后再等设备发新值。我在实际项目中更偏好独立 broker 下的 MQTT 方案因为 HA 本身升级、重启的频率其实不低设备通信不被 HA 拖累这套方案在折腾阶段让人省心很多。6. 怎么选我的建议与决策清单6.1 大多数人直接用原生 API 就够了如果你满足下面这些条件直接原生 API不用犹豫HA 是你唯一的智能家居平台没有自建 Node-RED也不用把数据接到其他平台设备数量二三十个以内基本都是常规传感器和开关你不想维护 broker不想理解 topic 结构你希望刷完固件就能在 HA 里自动用起来不要任何额外配置你主要在本地网络使用不做复杂的多系统联动这些条件其实涵盖了家庭 DIY 玩家里的绝大多数场景。原生 API 是 ESPHome 官方默认路径维护成本和对新手友好程度都是最优的。包括驱动 GoGo 设备接入 HA 这种需求如果设备的是 ESPHome 固件直接用 API 接入比 MQTT 明显省心得多。6.2 该选 MQTT 的场景看重解耦和跨平台MQTT 的真正价值不在延迟而在解耦和标准化。符合下面任一情况的你可以认真考虑 MQTT你已经有独立的 MQTT broker比如在路由器或树莓派上跑着 Mosquitto你希望设备数据能被其他系统消费比如 Node-RED、自定义 Python 脚本、其他监控平台等你希望设备即使 HA 挂了也能互相通信、保留状态你已经有大量其他 MQTT 设备比如 Tasmota 刷机设备、传感器等希望统一走 MQTT 接入你愿意付出配置和维护成本换来更大的自由度坦白说我自己目前家里是混合策略ESPHome 固件的主力设备全部走原生 API个别需要接外部系统的设备单独走 MQTT。这样既享受了 API 的简单和稳定又保留了和外部系统通信的通道两边都不耽误。6.3 一张决策清单照着勾就行你的需求推荐方案备注只要能本地接入 HA不想折腾原生 API默认配置即可需要 HA 之外的系统读设备数据MQTT独立 broker 效果更佳担心 HA 掉线影响设备联动MQTTbroker 必须独立于 HA 运行设备特别多想减掉 HA 侧连接MQTT 或分流实际瓶颈很低以维护习惯为主频繁刷固件调试原生 API对开发流程最友好需要看完整 MQTT 报文调试MQTT配合 MQTT Explorer 很方便极低延迟联动比如多设备互锁原生 API链路最直接接入第三方传感器或 Tasmota 设备MQTT它们本来就只会 MQTT我个人的体会是这个问题没有标准答案因为它本质是“你更在意自动化的方便还是更在意系统的灵活”。原生 API 是把简单留给用户把复杂度封装在内部MQTT 是给你最大的控制权但所有细节也一并交到你手里。对大部分人来说先原生 API 用起来正儿八经把 HA 玩明白了再考虑要不要把个别设备切到 MQTT 也不迟。最后再说一个小技巧如果你确实想两个都试可以在 ESPHome 配置里同时打开 api 和 mqtt 两块不用二选一刷完固件两种接入方式并行实体也会重复出现在 HA 里——自己实测对比一晚上比看任何文章都直观。
阅读完成 · 觉得有帮助？
