1. 为什么ESPHome玩家都会卡在“API还是MQTT”上玩ESPHome接Home Assistant下文统一叫HA的朋友迟早都会撞上同一个问题设备固件里到底配api:还是mqtt:网上翻教程有人吹原生API零配置自动发现有人坚持MQTT解耦灵活最后结论往往是“看你的需求”等于没说。我在这个坑里折腾了三年多家里从最早的几个ESP8266温湿度计到后来陆续加了窗帘电机、继电器开关、人体传感器、蓝牙温湿度网关前前后后二十多个设备。两种接入方式都用过有一段时期甚至同一批设备里一半走原生API、一半走MQTT纯粹是为了做对比测试。这篇文章不打算给你“都行”这种废话而是把两套接入逻辑背后的机制差异、配置过程、以及我在真实网络环境里踩过的坑全部摊开讲。先说结论原生API适合“以HA为唯一中枢、设备数量多、需要蓝牙代理或低延迟本地联动”的家庭MQTT适合“有多平台共存需求、HA之外还有其他系统要消费设备数据、或者你希望设备与平台彻底解耦”的场景。但这句话背后的判断依据才是真正需要理解的东西。这篇文章适合谁手上有一块ESP32或者ESP8266打算刷ESPHome接HA但是被API和MQTT的选择弄晕的DIY玩家已经跑通了其中一种方案但想搞明白另一种方案到底好在哪、值不值得迁移的进阶玩家以及像我一样纠结过“要不要为了省一个MQTT broker把全家都迁到原生API”的人。下面先把两套模式的底层差异说清楚因为不搞懂机制后面任何配置都是盲抄。2. 原生API和MQTT到底差在哪两套接入逻辑的三个关键差异2.1 通信模型一条永活的长连接 vs 一堆短消息报文原生APIESPHome Native API走的是TCP长连设备在启动之后主动连上HA连接建立之后这条通道是活的。它的本质是“设备与HA之间的一条双向实时通道”数据交互用的是一种二进制协议基于protobuf序列化HA在本地监听端口默认6053设备通过API key校验身份。这条长连接能承载的东西远超你的直觉它不只传传感器数值还顺带承担了设备日志流、实体状态变更推送、OTA固件推送。换句话说你在HA界面里能看到ESPHome设备的实时日志、能在HA里直接给设备升级固件靠的都是这条连接。这是原生API一个非常隐蔽但极其实用的价值——你不需要另开窗口去看串口日志或者用命令行刷固件直接在HA里操作就行。MQTT则是完全不同的思路设备不跟HA直接对话而是连到一个MQTT broker通常部署在HA里作为一个附加组件然后以发布/订阅的模式收发主题。设备把状态发到一个topicHA订阅这个topicHA要控制设备就往另一个topic发命令设备订阅后执行。设备跟broker之间是一条短连接也好、长连接也好都无所谓关键是它们的对话方式变成了一条条的“消息”而不是一个持续的会话。打个比方原生API像你直接加了对方微信随时可以发起视频通话、传文件、看对方在线状态MQTT像你俩都在一个邮件群里所有沟通都通过群邮件中转好处是谁走了都不影响邮件群继续运转坏处是实时视频会话这种事没法干只能靠来回发消息模拟。2.2 设备“见光”的方式自带实体注册 vs 靠discovery广播原生API模式下设备里写了哪些传感器、哪些开关、哪些二进制传感器ESPHome固件在连接HA时直接把这些实体信息推给HA。HA不需要你手动写任何配置文件不需要你定义topic不需要你指定device class它收到实体注册信息之后自动在后台创建对应的entity。这也是为什么很多人第一次刷完固件打开HA的ESPHome集成页面就看到设备自动躺在那里的原因。MQTT模式下设备在broker上发布状态topicHA并不知道这个topic对应什么实体直到设备发送一条特殊的discovery消息。这条消息里包含实体类型、名称、状态topic地址、命令topic地址、设备标识等信息HA收到后在后台解析然后注册实体。discovery消息的格式是homeassistant/component/node_id/object_id/config比如homeassistant/switch/esp01/relay/config这样的topic。如果你在自己写MQTT设备的固件这个格式必须完全正确否则HA那边只会看到一堆原始topic不会自动变成实体。这背后是个很实际的差异原生API的实体注册是“声明式”的HA完全相信设备给的数据MQTT的discovery是“协商式”的HA解析discovery消息后还要处理topic映射。原生API改实体名称、改传感器类型只要重新烧录固件HA里自动同步MQTT方案如果改动了topic结构或者discovery字段HA里可能会留下僵尸实体需要做清理。2.3 资源占用与可靠性省一个broker还是多一层缓冲原生API设备只依赖HAHA挂了重启之后设备会自动重连网络波动时API连接断开设备上的本地逻辑照样运行。但有一个关键细节API连接本身有超时和重连机制如果HA长时间不可用设备会在内存里保留一长串待推送的状态变化极端情况下可能出现状态堆积。MQTT设备多了一层broker缓冲。HA重启期间设备依然连在broker上继续发布消息HA恢复之后订阅到最新状态。如果你的网络环境恶劣、HA升级频繁这个缓冲层确实能减少“设备离线告警”的误报。但代价是你多了个broker要维护而且MQTT包体大、频率高的时候ESP8266这种小内存设备会明显感觉吃力尤其是跟原生API那种二进制定制协议相比。下面这个表可以帮你快速建立整体印象对比项原生APIMQTT连接模型TCP长连接双向实时broker中转发布/订阅实体注册设备直接声明实体通过discovery消息广播日志查看HA内直接看实时日志需要额外订阅日志topicOTA推送HA集成内直接推送固件一般要另配OTA服务蓝牙/Sub-G代理原生支持数据经API推送很难实现效果很差外部系统联动只能走HAbroker一开谁都能订阅设备离线感知HA与设备断连判定broker用Last Will广播离线资源消耗内存占用略少无broker依赖多一条消息链路需维护broker3. 原生API接入实操三段式配置加HA侧零干预3.1 最小可用的yaml长什么样如果你的目标是“先跑起来”原生API是最快的。我以一个ESP32-dev开发板为例最小配置只要四段esp32: board: esp32dev framework: type: arduino wifi: ssid: 你的WiFi名 password: 你的WiFi密码 api: encryption: key: base64编码的32字节密钥 ota: - platform: esphome password: ota更新密码这里有两个重点必须说。第一个是api.encryption.key很多人第一次配置时直接省略encryption设备也能正常工作但我强烈建议不要省。原生API默认没有任何认证局域网内任何人只要能连到你的设备IP和端口就能拿到设备上所有实体的读写权限。你想想你家的灯、窗帘、门锁要是都挂在ESPHome上不加密钥等于把你的家门钥匙放在门口脚垫下面。生成密钥的方式很简单在部署ESPHome的机器上跑一句python3 -c import secrets; print(secrets.token_hex(32))拿到一串64位十六进制字符后需要转成base64格式放进配置。如果你嫌麻烦更省事的办法是先把encryption:注释掉让ESPHome首次运行时自动生成一个随机密钥然后它会显示在日志里你复制回配置文件就行。我实际测试中大部分时间还是用secrets.token_hex这种方式因为这样我可以把密钥统一存进密码管理器方便后面给多台设备用同一个key轮换。3.2 HA侧装好集成一切自动原生API在HA这一侧几乎是零配置的。你只需要在HA的“设备与服务”里添加“ESPHome”集成填入设备的IP地址它会自动要求你提供API密钥填进去之后所有实体立刻出现。这个“自动”的背后就是前面说的实体声明机制ESPHome固件里写的每个sensor:、switch:、binary_sensor:固件启动时都会把它们的定义和唯一ID上报给HA。所以你在HA里不需要手动创建任何东西设备掉线重连之后实体状态自动恢复。这带来一个很实际的好处固件版本升级后如果加了新的传感器或改了某个传感器的类型HA里不需要删掉旧实体重新添加重新编译烧录之后HA自动同步。我后来给某个ESP32设备加了两个继电器输出重启设备、进HA刷新一下页面两个新switch实体就出现了整个过程不超过一分钟。3.3 原生API免费附带的三个功能别忽略选择原生API有一个很容易被忽略的回报HA和ESPHome生态是深度打通的。最典型的三件套第一OTA集成。HA的ESPHome设备页面里直接有“更新”按钮可以在HA里上传编译好的固件bin文件。你不需要命令行、不需要打开网页上传等于少了一套运维工具链。第二实时日志。设备页面里能看到滚动日志排查问题的时候比看串口日志方便一个数量级。我调试某个人体传感器上报频率问题的时候直接在HA里开日志传感器事件实时刷屏比对着串口监视器舒服多了。第三蓝牙代理与Sub-G通信支持。如果设备配置了esp32_ble_tracker蓝牙扫描到的温度计、湿度计、ibeacon数据会通过原生API通道直接推送HA并生成实体同理还有ESP32 CC1101之类的Sub-G通信模块它们要往HA实时推送大流量状态数据MQTT那套基于文本topic的模型根本接不住只有原生API的二进制长连接能力能够承载。这也是我后来把蓝牙网关全部迁回原生API的决定性原因。3.4 网络环境差的时候这几个参数能救命原生API虽然连接机制可靠但对WiFi的依赖是硬性的。如果你的设备部署在信号死角或者你家路由器经常切换信道导致设备掉线就会出现一种很烦人的情况设备不断重启HA里一会儿在线一会儿离线。原因多半出在api.reboot_timeout这个参数上。默认情况下如果API连接失败持续一段时间设备会自动重启以尝试恢复网络。这个机制的出发点是好的但在WiFi不稳定的环境里会变成“重启怪圈”设备刚重启完还没连上WiFiAPI连接失败倒计时又开始了还没等到网络恢复就再次重启永远循环。我的处理方式是在设备配置里显式关掉或者调大这个超时api: encryption: key: 你的base64密钥 reboot_timeout: 30min # 连不上HA时最多30分钟后重启避免无限循环同时搭配WiFi层的兜底策略让ESPHome在连不上主WiFi时自己开一个热点方便现场调试wifi: ssid: 主WiFi password: 主WiFi密码 fallback: ssid: esp-hotspot password: 临时热点密码 ap_timeout: 2min这套组合拳下来即使HA重启或者路由器闪断设备也会等一段时间再做应对而不是像没头苍蝇一样疯狂重启。我在实际测试里观察过WiFi断开20秒再恢复原生API连接能自己兜回来没有产生离线告警。4. MQTT方案接入broker搭建、双通道配置和discovery原理4.1 先装一个brokerHA里其实有官方组件如果你决定走MQTT第一步是有一个MQTT broker。HA里最常用的是附加组件里的“Mosquitto broker”在HA的Supervisor附加组件商店里搜索安装然后设置一个用户名和密码就行。安装好之后账号权限只需要给一个能读写的账号。很多新手在这里会困惑“是不是要给每个设备建一个账号”没必要家庭环境一个账号所有ESPHome设备共用就够broker会按topic区分设备。4.2 ESPHome的MQTT配置discovery和主题命名是关键ESPHome设备开启MQTT的方式同样简单在yaml里加一段mqtt: broker: 192.168.1.100 port: 1883 username: esphome password: 你的密码 discovery: true discovery_prefix: homeassistant id_prefix: esp01discovery: true表示设备启动时自动发送discovery消息。discovery_prefix默认就是homeassistant一般不用改。id_prefix建议设置成有意义的设备名它会影响实体ID的命名。比如一个叫relay1的开关设置id_prefix: esp01后HA里实体的ID就会带esp01前缀设备多了之后方便归类。设备的实体topic是怎么构成的需要说清楚。连接成功之后设备会往homeassistant/switch/esp01_relay1/config发一条JSON格式的discovery消息内容大致包括{ name: relay1, state_topic: esp01/switch/relay1/state, command_topic: esp01/switch/relay1/command, unique_id: esp01_relay1, device: { identifiers: [esp01], name: ESP01 } }HA收到这条消息之后才知道这个设备存在知道状态topic是哪个、命令topic是哪个。之后你在HA里打开或关闭这个开关HA往esp01/switch/relay1/command发一条ON或OFF报文ESPHome设备收到后控制继电器并把实际状态写回esp01/switch/relay1/state。这个回路虽然比原生API绕但每一步都非常直观出问题也好定位用MQTT调试工具直接订阅topic就能看到消息到底有没有发出来。4.3 MQTT真正擅长的地方多平台消费数据和自定义消息MQTT最迷人的地方在于整个通信系统里HA不是一个必需的角色。同样一包状态数据HA订阅了可以做自动化另一台树莓派上跑的Node-RED订阅了可以另做一套逻辑甚至你自己写的一个Python脚本也可以订阅同一批topic。设备根本不知道也不关心谁在消费它的数据。我在测试阶段做过一个实验用一个ESP32模拟一个窗磁传感器同时接入MQTT然后在同一台机器上跑了一个Python脚本收到了消息就打印出来。整个过程中HA完全不在数据链路上设备通过broker直接跟外部脚本对话。这种“控制权在多平台”的架构在特定场景下有巨大价值比如你想把家里的设备接入一套自己写的告警系统或者你打算从HA迁移到另一个智能家居平台MQTT设备不需要改固件、不需要重新刷机新平台只需要订阅已有的topic设备数据立刻就能被新平台消费。原生API的生态绑定做不到这一点。4.4 MQTT里的几个坑状态灯、Last Will和availability用MQTT最容易栽跟头的点其实不在连接本身而在“在线状态”的表达。原生API模式里HA和设备之间的连接状态是平台直接感知的设备离线就是真离线。MQTT模式不一样设备断线时broker这边只能通过Last Will遗嘱消息感知设备连上broker时发一条遗嘱声明“如果我不见了请帮我广播一条离线消息”broker检测到设备异常断开后就广播这条遗嘱HA收到后把实体标记为离线。ESPHome默认已经做好了这套逻辑。但你自己写固件或者用其他MQTT设备时很容易漏掉这一点然后你会看到HA里实体永远显示在线——因为没人告诉它设备已经断了。这是新手最容易踩的坑。另一个坑是availability topic和state topic混用。ESPHome里可以给MQTT配置availability设置比如设备上报一个状态topic用于HA判断在线离线但如果你手写topic的时候漏掉了availability设置就得自己处理“离线时状态会不会回退”的问题。我的经验是尽量用ESPHome官方MQTT默认配置不要自己造topic轮子除非你的确知道自己在做什么。还有一个细节ESPHome刷了MQTT配置之后设备上如果同时保留api:HA里会看到设备同时被API和MQTT两种方式发现导致实体重复。这个问题后面会专门说。5. 我的选型判断按设备形态和网络规模做决定5.1 什么情况直接无脑原生API我的一个明确原则只要设备要往HA上报高频数据或者需要HA实时下发控制优先原生API。我家里目前在跑的蓝牙温湿度计网关每个几分钟就要刷一次各个房间的温度数据再加上ibeacon信息数据量对MQTT来说不是大问题但MQTT的消息频率和体积会让HA那边产生明显的实体刷新延迟而且调试起来要开三个窗口追踪topic。原生API下这些数据以一种压缩的二进制格式走同一条长连接HA接收跟本地刷新差不多体验完全不一样。还有一类设备必须原生API需要启用蓝牙代理或者Sub-G通信的ESP32设备。esp32_ble_tracker产生的那些扫描信息量太大了一次扫描能带出几十个BLE设备的信号强度数据用MQTT的文本topic承载既不合适也容易把broker的消息量堆积成灾。我现在所有跑BLE扫描的设备都统一用原生API没有例外。设备数量越多的用户原生API的维护成本优势越明显。二十个设备全是原生API只要HA里管好集成就行二十个设备走MQTT你得管理topic命名规范、discovery消息格式、设备ID去重光是想一想头就大。5.2 什么情况考虑MQTT如果你的设备数据要同时被多个系统消费那MQTT是正解。比如你在跑一个自己的告警服务或者想用一个第三方面板展示传感器数据MQTT的发布订阅模型天然支持而原生API的数据只能被HA消费。还有一类场景是“设备控制链路不希望被HA AS依赖”。假设你有一个设备需要被外部脚本直接控制MQTT模式下外部脚本直接往command topic发消息设备执行不经过HA。原生API模式下外部脚本要么通过HA的WebSocket API间接控制要么自己实现一套protobuf客户端成本高得多。也有一点要诚实如果你家的HA经常升级、偶尔重启且你不想在HA重启期间看到一批设备离线告警MQTT的broker缓冲确实能减少误报。但我实测下来原生API在HA重启后重连速度很快这个优势并不明显。5.3 混合模式两者同时开不算浪费很多人不知道ESPHome允许同时启用API和MQTT。你把两段配置都写进yaml设备就会同时通过API连接HA、通过broker发布MQTT消息。这样做有个好处你可以把HA集成要看的数据走原生API同时把某些需要外部系统消费的数据发布成MQTT topic。我在某个ESP32设备上就同时开了两套通道HA用原生API管理实体和OTA同一台设备另发一套MQTT消息给自动化脚本两边互不干扰。但要注意这在这个配置下设备在HA里可能会产生两套实体一套来自API、一套来自MQTT discovery。解决的办法是明确哪个是你真正要用的另一个在HA里禁用掉。我遇到的情况是同时开启后HA里同一个传感器出现了两个实体名一模一样的情况需要在HA里手动给其中一组禁用实体否则自动化选错实体就会乱套。6. 三年折腾经验里的避坑清单6.1 API模式下设备反复重启根因在reboot_timeout前面提过设备在WiFi信号差或者HA短暂不可用时如果开着默认的API重启超时会陷入重启循环。这个坑我实际遇到过不止一次。第一次出现时我还以为是WiFi路由器的问题排查了几天路由器配置最后发现是ESPHome API模块在持续连接失败后主动重启设备。解决很简单要么把reboot_timeout调成0s永远不自动重启要么像我一样调成30分钟。设置成0秒有个小风险设备遇到网络问题后不会自愈只能靠WiFi模块自己重连。所以我个人更推荐调大时间、做一次兜底而不是彻底关掉。6.2 MQTT配置改版后的僵尸实体清理MQTT方案里我最想提醒的一点是不要频繁改设备的id_prefix和topic格式。每改一次就相当于HA要重新经历一次discovery流程而旧topic对应的实体往往不会自动清理。HA的MQTT集成里会残留一堆“离线”状态的僵尸实体。我踩过最惨的一次是把一个继电器设备的id_prefix从esp01改成了esp01s结果HA里出现了两套实体一套在线一套永远离线自动化里已经引用了旧实体改了半小时才清理干净。后面我的原则是id_prefix和设备名在初期就想好尽量不要再改如果非要改先去HA的MQTT集成里手动清理discovery缓存。6.3 为了省资源禁用API结果失去HA集成有个朋友分享过一种“优化”方式为了省内存把ESP8266设备上的API关掉只留MQTT理由是HA反正走MQTT也能发现设备。结果等他想要在HA里直接看日志的时候傻眼了——没有API连接HA的ESPHome集成就识别不到设备了日志只能通过MQTT的日志topic或者串口看OTA升级也没有了入口。原生API其实承担了HA集成层的设备发现和会话管理。MQTT模式走的是另一条家路但HA对ESPHome设备的很多高级管理功能OTA、日志流、设备标识都绑在API通道上。设备资源再紧张也不要去掉API除非你只把它当成一个纯MQTT传感器节点用。6.4 ESP8266上同时跑APIMQTT的资源账本ESP8266系列芯片资源是出了名的紧张尤其是ESP-01S这种只有1MB flash的型号。一个功能全开的ESPHome固件WiFi API MQTT OTA 主控逻辑全部启用编译完固件体积很容易超过700KBflash剩余空间会很紧。我的建议是1MB flash的ESP8266设备尽量只选一种接入方式别同时开API和MQTT如果非要双通道考虑用ESP32或者换用4MB flash的ESP8266型号。固件编译时也可以主动去掉不需要的组件比如不用OTA就把它注释掉能给flash腾出一些空间。我最早一批ESP-01S继电器模块甚至只保留了WiFi MQTT连API都去掉了因为它只是配合一个外部网关设备使用省出来的flash非常可观。6.5 加密密钥的管理宁可多存一份不要随手丢最后聊一个安全习惯。API加密密钥如果泄露等于设备被同网络的其他人接管。我见过有人把密钥直接写进家庭群分享的“给全屋设备升级固件”的过程中然后过阵子发现某些设备被人动过查了一圈发现是密钥已经暴露在外网备份里了。我的做法是所有ESPHome设备的密钥统一存在一个密码管理器里按设备单独建条目OTA密码也单独建条目。设备多了之后密钥管理混乱是必然的早点养成习惯后面轻松很多。另外如果怀疑密钥泄露直接换一批新密钥重新编译固件别嫌麻烦。最后再分享一个小经验如果你现在手上正好有一个ESP8266或ESP32在纠结选哪边先别急着看结论把两套配置各跑一遍。原生API从烧录到HA发现全程可能不到十分钟MQTT虽然多一个broker但你能亲眼看到设备在broker上发消息、HA通过discovery建实体这个理解比读十篇文章都管用。我自己就是在对比完两套流程之后才真正把每种方案的适用边界想清楚的。后面再看自家的设备清单哪些走API、哪些走MQTT根本不用纠结。