企业官网建设流程全解析

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 一堆短消息报文

原生API（ESPHome Native API）走的是TCP长连，设备在启动之后主动连上HA，连接建立之后，这条通道是活的。它的本质是“设备与HA之间的一条双向实时通道”，数据交互用的是一种二进制协议（基于protobuf序列化），HA在本地监听端口（默认6053），设备通过API key校验身份。

这条长连接能承载的东西远超你的直觉：它不只传传感器数值，还顺带承担了设备日志流、实体状态变更推送、OTA固件推送。换句话说，你在HA界面里能看到ESPHome设备的实时日志、能在HA里直接给设备升级固件，靠的都是这条连接。这是原生API一个非常隐蔽但极其实用的价值——你不需要另开窗口去看串口日志或者用命令行刷固件，直接在HA里操作就行。

MQTT则是完全不同的思路：设备不跟HA直接对话，而是连到一个MQTT broker（通常部署在HA里，作为一个附加组件），然后以发布/订阅的模式收发主题。设备把状态发到一个topic，HA订阅这个topic；HA要控制设备，就往另一个topic发命令，设备订阅后执行。设备跟broker之间是一条短连接也好、长连接也好，都无所谓，关键是它们的对话方式变成了一条条的“消息”，而不是一个持续的会话。

打个比方：原生API像你直接加了对方微信，随时可以发起视频通话、传文件、看对方在线状态；MQTT像你俩都在一个邮件群里，所有沟通都通过群邮件中转，好处是谁走了都不影响邮件群继续运转，坏处是实时视频会话这种事没法干，只能靠来回发消息模拟。

2.2 设备“见光”的方式：自带实体注册 vs 靠discovery广播

原生API模式下，设备里写了哪些传感器、哪些开关、哪些二进制传感器，ESPHome固件在连接HA时直接把这些实体信息推给HA。HA不需要你手动写任何配置文件，不需要你定义topic，不需要你指定device class，它收到实体注册信息之后自动在后台创建对应的entity。这也是为什么很多人第一次刷完固件，打开HA的ESPHome集成页面就看到设备自动躺在那里的原因。

MQTT模式下，设备在broker上发布状态topic，HA并不知道这个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设备只依赖HA，HA挂了，重启之后设备会自动重连；网络波动时API连接断开，设备上的本地逻辑照样运行。但有一个关键细节：API连接本身有超时和重连机制，如果HA长时间不可用，设备会在内存里保留一长串待推送的状态变化，极端情况下可能出现状态堆积。

MQTT设备多了一层broker缓冲。HA重启期间，设备依然连在broker上继续发布消息，HA恢复之后订阅到最新状态。如果你的网络环境恶劣、HA升级频繁，这个缓冲层确实能减少“设备离线告警”的误报。但代价是：你多了个broker要维护，而且MQTT包体大、频率高的时候，ESP8266这种小内存设备会明显感觉吃力，尤其是跟原生API那种二进制定制协议相比。

下面这个表可以帮你快速建立整体印象：

3. 原生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不稳定的环境里会变成“重启怪圈”：设备刚重启完还没连上WiFi，API连接失败倒计时又开始了，还没等到网络恢复就再次重启，永远循环。

我的处理方式是，在设备配置里显式关掉或者调大这个超时：

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 先装一个broker，HA里其实有官方组件

如果你决定走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: esp01

discovery: 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上同时跑API+MQTT的资源账本

ESP8266系列芯片资源是出了名的紧张，尤其是ESP-01S这种只有1MB flash的型号。一个功能全开的ESPHome固件，WiFi + API + MQTT + OTA + 主控逻辑全部启用，编译完固件体积很容易超过700KB，flash剩余空间会很紧。

我的建议是：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，根本不用纠结。