STM32 MQTT方案选型与移植实战：Paho/自研/AT指令对比

先说一下结论，免得你在各种资料里越翻越乱：STM32 上跑 MQTT，没有绝对“最好”的方案，只有“最合适”的方案。如果项目里模组资源充足、团队不排斥引入第三方库，我首选 Eclipse Paho MQTT C 库；如果 Flash/RAM 紧巴巴，只想发几个温湿度数据点，那自己封装一个极简发布客户端或者用 AT 指令透传，反而更省心。本文把这几个主流路子掰开揉碎讲清楚，顺便附上我这几年在 STM32F1/F4/H7 上折腾 MQTT 的真实踩坑记录，希望能帮正在选型的你少走弯路。

1. 项目为什么难选？先看 MQTT 在嵌入式端的本质

很多人一开始就在 GitHub 上搜“STM32 MQTT”，结果搜出来一堆仓库，每个 README 都写着“轻量级”“低内存占用”“简单易用”，看多了反而更纠结。我先把选择问题的本质拆开：MQTT 本质是一个基于 TCP/IP 的应用层协议，它本身不关心你跑在什么芯片上，也不关心你用的是 WiFi 模组、4G 模组还是以太网，它只要求在设备端能拿到一个可靠的 TCP 连接，并且在这一层之上按协议格式收发报文。

这就引出了第一个关键分叉点：你的 STM32 拿到网络连接的方式是什么？

• 方式一：STM32 内部自带以太网 MAC，外接 PHY 芯片（比如 LAN8720A），这种情况 STM32 直接跑 LwIP 协议栈，TCP 连接是完整的，MQTT 库可以直接跑在 LwIP 的 BSD Socket API 之上。
• 方式二：STM32 外挂串口 AT 指令模组（比如 ESP8266、ESP32、Air724UG 等），单片机本身不跑 TCP/IP 协议栈，网络协议都在模组内部完成。此时 MQTT 有两种实现路径：一种是在单片机侧发 AT 指令建立 TCP 连接，然后自己实现 MQTT 协议报文；另一种是用模组自带的 MQTT AT 指令（比如 ESP-AT 的 MQTT 命令），直接把发布订阅操作交给模组。
• 方式三：STM32 外挂一个自带 MQTT 协议的模组，比如移远、广和通的某些 4G 模组，它们提供了 MQTT 相关的 AT 指令集，单片机连报文格式都不用关心。

很多新手没搞清楚自己属于哪种情况，上来就找“STM32 + MQTT 库”，然后把 Paho 拉进来，结果发现编译过了但连不上服务器，查了半天才发现 LwIP 的 Socket 还没调通。所以这篇文章第一个建议就是：先确认网络通路，再决定 MQTT 实现方案。网络通路不通，什么 MQTT 库都是白搭。

再往下拆，嵌入式 MQTT 客户端要解决的核心问题其实只有四个：

1. 连接管理：建立 TCP 连接后，按照 MQTT 协议流程发送 CONNECT 报文，处理 CONNACK 响应。
2. 报文编解码：把发布、订阅、心跳、断开等操作封装成协议规定的报文格式，并解析接收到的报文。
3. 心跳保活：在空闲时按 Keep Alive 间隔发送 PINGREQ，防止服务端断开连接。
4. 重连逻辑：网络断线、服务端重启时，如何自动重连，并恢复订阅关系。

任何 MQTT 客户端实现，本质上都是在解决这四件事，差异只是封装程度和资源开销不同。有了这个框架，你再去看那些开源库的实现，就很容易看出门道了。接下来我逐一对比主流的几种方案。

2. 主流通用 MQTT 客户端库对比，谁才是 STM32 的菜

2.1 Paho MQTT C 库：功能最全，队伍最正

Eclipse Paho 是 Eclipse 基金会旗下的开源项目，MQTT 协议的官方参考实现之一。它提供 C、Java、Python、JavaScript 等多种语言的客户端库，其中 C 语言库（paho.mqtt.c）是最常被嵌入式项目选用的。

Paho C 库有两个 API 层次：

• 同步 API（MQTTClient）：面向应用层，提供 MQTTClient_create、MQTTClient_connect、MQTTClient_publish、MQTTClient_subscribe 等函数，内部封装了报文构造、发送、接收解析等细节，并且支持阻塞式调用，适合简单流程的业务。
• 异步 API（MQTTAsync）：以回调函数驱动，适合需要处理大量并发消息或复杂状态机的场景。

嵌入式场景下，大多数项目用的是同步 API，因为它简单直接，在裸机或 RTOS 里都好用。Paho 的 C 库还提供了“嵌入式专用版本”（paho.mqtt.embedded-c），这个版本去掉了 Linux 依赖，抽象出网络接口，可以轻松适配 LwIP、W5500 甚至自定义的 TCP 栈，内存占用也做了裁剪。

优点：

• 协议实现完整度最高，各种 MQTT 报文类型、标志位、QoS 0/1/2 都覆盖到位。
• 社区活跃，文档多，遇到问题容易搜到方案。
• 与主流云平台（阿里云、腾讯云、AWS IoT、EMQX 等）兼容性好，证书、TLS 等扩展支持也完善。
• 同步 API 上手门槛低，代码可读性强。

缺点：

• 代码体积偏大。即使裁剪后，在 Keil/EWARM 里全量编译下来，Flash 占用约 15KB~25KB，RAM 占用还要看发送接收缓冲区的配置。
• 依赖网络接口抽象层，如果你用的是 AT 模组而不是 lwIP，适配网络接口需要自己写钩子函数。
• 同步 API 在某些实时性要求高的场景里，发送阻塞可能影响其他业务，需要配合 RTOS 使用或者手工拆分状态机。

我在实际项目中用 Paho embedded-c 跑过 STM32F407 + LAN8720A + LwIP，连接阿里云物联网平台，效果很稳。具体接入要点在第 3 节展开讲。

2.2 mongoose-mqtt：全家桶里的轻骑兵

Mongoose（cesanta/mongoose）是一个非常出名的嵌入式网络库，号称“Everything in one file”，一个 mongoose.c 文件就把 HTTP、MQTT、WebSocket、CoAP 等都实现了。如果你已经用了 Mongoose 做 HTTP 服务或者 WebSocket 管理，那么顺手用它的 MQTT 客户端是极其自然的。

Mongoose 的 MQTT 实现也提供发布、订阅、心跳、重连等基本能力，API 风格是事件驱动的，你需要注册回调函数处理 MG_EV_MQTT_CONNACK、MG_EV_MQTT_PUBLISH 等事件。

优点：

• 麻雀虽小五脏俱全，这一个文件就包含了多个协议支持，项目里省去很多依赖管理。
• 事件驱动模型非常适合网络并发场景，可以用很小的 RAM 支撑多个连接。
• 对嵌入式裸机友好，不依赖操作系统，也能移植到 RTOS。
• 教科书级别的代码结构，值得学习。

缺点：

• MQTT 的功能深度不如 Paho，高级特性（比如遗嘱消息、保留消息、Topic Alias 等）支持有限。
• 如果只为了 MQTT 而引入 Mongoose，有点大材小用，毕竟它的核心是通用网络连接管理。
• API 设计偏节点化，和 Paho 的“对象化”风格差距明显，团队切换有学习成本。

2.3 wolfMQTT：面向物联网安全的硬核选手

wolfMQTT 是 wolfSSL 团队出的 MQTT 客户端库，和 wolfSSL（嵌入式 TLS 库）配合得非常好。如果你的设备需要启用 TLS 加密连接 MQTT 服务器（比如 MQTTS 端口，阿里云/华为云企业版常见），而且你对代码安全性有强诉求，那 wolfMQTT 值得认真考虑。

优点：

• 和 wolfSSL 无缝集成，TLS 加解密性能好，证书管理方便。
• 代码风格严谨，安全审计级别高，适合医疗、工控等对信息安全有严格要求的行业。
• 支持 MQTT 3.1.1 和 5.0。

缺点：

• 学习曲线稍陡，配置项多。
• 内存开销比 Paho 裁剪版还要大，F103 级别的芯片比较吃力。
• 社区文档偏少，典型例程不够丰富。

2.4 自研轻量级客户端：从零写一个 MQTT 发布器

如果项目真的很简单，比如某传感器节点每隔 30 秒上报一次数据，QoS 只用 0，不需要订阅读取任何指令，那完全没有必要拉一个库进来。自己手写一个 MQTT 发布客户端，核心代码可以控制在 200 行以内。

MQTT 协议最核心的报文结构并不复杂：

• 固定报头：控制报文类型（4位）+标志位（4位），后续字节是剩余长度。
• 可变报头：根据报文类型不同，连接报文里要带协议名、协议版本、连接标志、心跳时间等。
• 载荷：发布消息的 Topic 和 Payload。

以 CONNECT 报文为例，你需要拼接以下内容：

// 假设 client_id 为 "stm32_dev_01"，clean_session 为 1 uint8_t payload[] = { 0x00, 0x04, 'M', 'Q', 'T', 'T', // 协议名 "MQTT" 0x04, // 协议级别 4 (MQTT 3.1.1) 0x02, // 连接标志: clean session 0x00, 0x3C, // Keep Alive 60秒 0x00, 0x0C, 's', 't', 'm', '3', '2', '_', 'd', 'e', 'v', '_', '0', '1' };

然后要做的事情就是把这个 payload 包在 CONNECT 报文里，固定报头第一个字节是 0x10，剩余长度根据 payload 长度算出来，封装后发送。接着等待服务端返回 CONNACK，解析其返回值即可。发布报文类似，只是多了 Topic 字符串。

我当时为了验证一个 8 位单片机能不能直接用串口发 MQTT 协议包，照着协议文档写了一个最小实现，整个文件不到 150 行，跑在 STM32F103C8T6 上，内存占用不到 2KB，连系统时钟都不需要专门调整。

优点：

• 代码量极低，Flash 和 RAM 占用几乎可以忽略。
• 没有依赖，不需要适配任何网络接口抽象层。
• 调试方便，每一行代码都了如指掌。

缺点：

• 没有现成的重连逻辑、心跳超时处理，需要自己补全。
• 只支持有限功能（如只支持 QoS 0，不支持遗嘱），扩展困难。
• 踩坑成本高：协议细节错了很难排查，比如剩余长度的编码规则、可变字节整数等。

2.5 我在选型时的决策思路

根据上面这些对比，我给出一个比较通用的决策建议：

项目场景	推荐方案
STM32 + 以太网（LwIP），需要发布订阅完整功能，团队有一定经验	Paho embedded-c
STM32 + AT 模组，网络协议在模组内，MQTT 透传	模组 AT 指令（如 ESP-AT，或移远 MCU 的 MQTT 指令）
STM32 + 以太网，想同时支持 HTTP/WEB 等管理功能	Mongoose
STM32 资源极小，只做周期性上报数据	自研轻量级客户端（200行内）
需要 MQTTS，安全等级高，团队能啃 wolfSSL	wolfMQTT

如果你是新项目，还没有历史包袱，我建议优先考虑 Paho embedded-c。因为它的协议实现最规范，后续你增加 QoS 1、遗嘱消息、离线消息这些需求时，库已经支持了，不需要推翻重来。我就经历过两次因为一开始自研客户端，后面需求加了 QoS 1 和遗嘱消息，不得不重写的痛苦，教训深刻。

3. 核心细节解析：Paho embedded-c 在 STM32 上的完整接入流程

3.1 移植前的准备：网络接口抽象层怎么填

Paho embedded-c 的源码里有一个MQTTClient.h文件，它定义了Network结构体，你需要在NetworkConnect、NetworkRead、NetworkWrite、NetworkDisconnect这些函数里把实际网络操作填充进去。

以 STM32 + LwIP 为例，关键代码如下：

int NetworkConnect(Network* n, const char* addr, int port) { // 解析服务器地址，通常是域名或 IP ip_addr_t server_ip; struct netconn *conn; // 注意：这里需要 DNS 解析，如果服务器是域名，需要调用 dns_gethostbyname 等函数 // 如果是 IP 字符串，可以直接 inet_aton 转换 // 也可以省事，直接使用一个已经解析好的 IP 地址 err_t err = netconn_gethostbyname(addr, &server_ip); if (err != ERR_OK) return -1; conn = netconn_new(NETCONN_TCP); if (conn == NULL) return -1; err = netconn_connect(conn, &server_ip, port); if (err != ERR_OK) return -1; n->conn = conn; // 保存连接句柄 return 0; }

这里提一个重要细节：LwIP 下的netconn_connect是阻塞还是非阻塞，取决于你配置的 LwIP 超时机制。如果没开超时，阻塞时间会很长，影响主循环响应。我的建议是，在调用netconn_connect之前，设置好conn->recv_timeout和conn->send_timeout，这样连接失败时能快速返回错误，而不是卡死整个系统。当然，底层的超时机制，最好用操作系统信号量配合完成。

3.2 配置裁剪：哪些宏定义决定了你的内存占用

Paho embedded-c 的MQTTClient.h里有一组宏定义，决定了客户端的工作模式和内存开销，例如：

• MQTT_TASK：如果定义为 1，则使用独立任务处理收发；如果定义为 0，则应用层手动调用MQTTYield处理收发。
• MQTT_TASK_STACK_SIZE：独立任务的栈大小。
• MQTT_BUFFER_SIZE：发送接收缓冲区大小，这个值越大，单次能处理的消息越长，但 RAM 占用也越高。
• MQTT_CLIENT_APPEND_PUBLISH：是否在发布时自动附加 Topic 字符串，默认可以不启用。

我个人的经验值是：MQTT_BUFFER_SIZE默认 256 字节，如果只是传温度、湿度、电压等几字节的数据，完全够用；如果要传大包（比如 OTA 固件分片），需要调整到 1024 甚至 2048。但是每加 1024 字节，就是 1KB RAM，这在 STM32F103 上是肉疼的，所以要用多少加多少，不要贪大。

3.3 核心业务逻辑：连接服务器、发布消息、订阅主题

在主循环里，Paho 的典型流程是这样的：

1. 初始化网络接口，填充 Network 结构体。
2. 初始化 MQTTClient 结构体，调用MQTTClientConnect建立 MQTT 连接。
3. 连接成功后，调用MQTTClientSubscribe订阅所需主题。
4. 业务逻辑循环里，手动调用MQTTClientYield（或MQTTReceive）来驱动数据收发。
5. 定期发布数据时，调用MQTTClientPublish。

下面是一段精简但完整的示例代码：

#include "MQTTClient.h" #include "stm32f4xx_hal.h" // 网络、客户端全局变量 Network network; MQTTClient client; // 断线重连、订阅回调等函数略 void mqtt_task(void *arg) { // 服务器地址和端口 MQTTClient_connectOptions conn_opts; // 填充连接参数 memset(&conn_opts, 0, sizeof(conn_opts)); conn_opts.keepAliveInterval = 60; conn_opts.cleansession = 1; conn_opts.clientID = "stm32_demo_device"; // 建立网络连接 if (NetworkConnect(&network, "broker.emqx.io", 1883) < 0) { Error_Handler(); } // 初始化 MQTT 客户端 MQTTClientInit(&client, &network, 256, (uint8_t*)malloc(256), 256, (uint8_t*)malloc(256)); // 建立 MQTT 连接 if (MQTTClientConnect(&client, &conn_opts) < 0) { Error_Handler(); } // 订阅主题 MQTTClientSubscribe(&client, "/stm32/data", QOS1, NULL); while(1) { // 驱动底层收包 MQTTClientYield(&client, 100); // 每 5 秒发布一次模拟数据 static uint32_t last_pub = 0; if (HAL_GetTick() - last_pub > 5000) { last_pub = HAL_GetTick(); char payload[64]; sprintf(payload, "{\"temp\":%.2f,\"hum\":%.2f}", read_temp(), read_hum()); if (MQTTClientPublish(&client, "/stm32/data", payload, strlen(payload), QOS1, 0) < 0) { // 发布失败，这里可以置一个断线标志 } } } }

这段代码看似简单，但实际项目里有两个陷阱：

• 陷阱一：MQTTClientInit需要传入发送和接收缓冲区，很多人图省事直接用静态数组，这没问题，但大小必须大于MQTT_BUFFER_SIZE，否则越界。
• 陷阱二：如果cleansession设为 1，则每次重连后不会收到离线消息，而且需要重新订阅。如果业务上要求离线消息，要把它设为 0，并用固定 ClientID，这样服务端才能找到历史会话。

3.4 断线重连实战：不能让设备死等

嵌入式设备最怕的不是断线，而是断线后不知道怎么恢复。我在真实项目里积累的断线重连逻辑是这样的：

void mqtt_task(void *arg) { while (1) { if (!is_connected) { // 尝试网络层连接 if (NetworkConnect(&network, "broker.emqx.io", 1883) != 0) { // 失败则延时一段时间，避免频繁重试 delay_ms(5000); continue; } // 尝试 MQTT 连接 if (MQTTClientConnect(&client, &conn_opts) != 0) { delay_ms(5000); continue; } is_connected = 1; // 重连成功后重新订阅 MQTTClientSubscribe(&client, SUB_TOPIC, QOS1, NULL); } // 正常的 yield 和 publish 逻辑 if (MQTTClientYield(&client, 100) < 0) { is_connected = 0; // 关闭网络连接，释放资源 NetworkDisconnect(&network); } } }

这里的关键原则是：重连不能死循环，每次失败后增加退避时间（比如第一次失败 2 秒后重试，第二次失败 5 秒后重试，最多不超过 30 秒），否则会一直干耗资源。另外，网络连接失败之后，NetworkDisconnect一定要调用，否则 socket 句柄泄漏，重试几百次后系统资源耗尽。

4. 实操过程：一步步把 MQTT 跑起来（附关键步骤）

这一节我不讲太虚的，就基于最常见的“STM32F407 + LAN8720A + LwIP + Paho embedded-c”组合，带你走一遍完整的实操流程，保证能照着跑通。

4.1 环境准备与工程搭建

1. 准备好开发板：STM32F407 最小系统板 + LAN8720A 模块，或者直接用正点原子/野火的探索者板子，因为他们都有现成的 LwIP 例程。
2. 从 GitHub 拉取 Paho embedded-c 源码：

git clone https://github.com/eclipse/paho.mqtt.embedded-c.git

3. 在 Keil/IAR 里新建一个工程，把 paho 源码中MQTTClient-C/src目录下的文件全部加入：

   • MQTTClient.c
   • MQTTConnectClient.c
   • MQTTConnectServer.c
   • MQTTPacket.c
   • MQTTSerializePublish.c
   • MQTTDeserializePublish.c
   • MQTTSubscribeClient.c
   • MQTTUnsubscribeClient.c
   • MQTTFormat.c

4. 将MQTTClient-C/src和MQTTClient-C/inc都加入 include 路径。

这里要提醒一个坑：Paho embedded-c 的源码有一些插件式依赖，比如在某些编译器里MQTTClient.c会引用inttypes.h，这个头文件在 Keil 的 ARMCC 环境下可能不直接可用，需要你自己添加一个inttypes.h空文件或者配置宏__STDC_LIMIT_MACROS。我在 GCC 环境下没遇到过，但 Keil 下遇到一次，折腾了半天。

4.2 LwIP 配置检查

LwIP 的lwipopts.h里有两个关键宏需要检查：

• NO_SYS：如果为 0，则使用 netconn 或 socket API；如果为 1，则只能使用 raw API。Paho embedded-c 的网络抽象层需要 netconn 或 socket，所以NO_SYS必须设为 0。
• LWIP_SOCKET和LWIP_NETCONN：这两个宏需要使能，否则没有 socket 相关函数。

我最初在 CubeMX 里生成 LwIP 工程时，默认NO_SYS是 0，但LWIP_SOCKET没有使能，导致编译报错找不到socket函数。这一点在检查配置时需要特别留意。

4.3 连接公共 Broker 验证连通性

先用公共 Broker（如broker.emqx.io:1883、broker.hivemq.com:1883）做连通性验证，不要一上来就连云平台，因为云平台的鉴权逻辑会干扰 debug。用公共 Broker 的好处是不要注册、不要密钥，直接把NetworkConnect里的服务器地址改成broker.emqx.io，端口写 1883，就能跑通。

连上以后，用 MQTTX 或 MQTT Explorer 在电脑上订阅同一个 Topic，就能看到数据刷出来。这一步能确认你的 LwIP 网络通路、DNS 解析、TCP 连接都没有问题。等到跑通了，再换到正式服务器的地址，加上鉴权参数。

4.4 局域网模式下的地址解析技巧

很多人在内网测试时，直接把服务器 IP 写死在代码里，比如192.168.1.100。但如果你把NetworkConnect里的地址传的是十进制字符串（比如"192.168.1.100"），要确认 LwIP 已经支持字符串转 IP 地址的函数。在netconn_gethostbyname里需要用到 DNS 模块，但内网 IP 通常不需要 DNS，建议用ipaddr_aton先转成ip_addr_t再连接：

ip_addr_t server_ip; IP_ADDR4(&server_ip, 192, 168, 1, 100); err_t err = netconn_connect(conn, &server_ip, 1883);

这样比走 DNS 更直接，也更稳定，尤其是在你还不确定 DNS 模块是否正常工作的时候。

4.5 发布订阅联调验证

用 MQTTX 同时订阅/stm32/data和/server/cmd两个主题，然后：

1. 在 STM32 侧定时发布模拟数据，看电脑端能否收到。
2. 在电脑端向/server/cmd发指令，看 STM32 侧能否通过订阅回调收到，并做出控制动作（比如开关 LED）。

这一步能验证双向通信链路，如果只是单向发布，后面要加下行命令时就又要折腾一遍。

5. 常见问题与排查技巧实录

5.1 连不上 Broker，报连接超时

现象：NetworkConnect能通（TCP 握手成功），但MQTTClientConnect卡住超时，或者干脆在NetworkConnect阶段就失败。

排查：

• 先 ping 一下 Broker 地址，确认网络层可达。
• 检查 LwIP 是否真的连接上路由器，有没有获取到 IP。我遇到过一次是开发板插了网线但 LwIP 的 DHCP 没有成功，导致后面所有连接都失败，打印一下netif.ip_addr就能看到。
• 确认端口是否正确。MQTT 默认端口是 1883（非加密），如果服务器在 8883（TLS）端口上监听，你的裸 TCP 连接过去是不会有任何响应的。
• 使用 Wireshark 抓包看一下 TCP 握手是否成功，如果在 SYN 阶段就失败，大概率是 IP 或路由问题；如果握手成功但没收到 MQTT CONNACK，可能是服务器不接受该 client ID 或协议版本不对。

5.2 发布消息收不到

现象：设备端打印发布成功，但电脑端 MQTTX 订阅同一个 Topic 没有收到消息。

排查：

• 确认 Topic 是否完全一致，MQTT 的 Topic 是严格区分大小写的。
• 确认 QoS 是否为 0，如果为 0，消息可能因为网络抖动丢失；如果为 1，是否收到了 PUBACK。可以在代码里检查MQTTClientPublish的返回值，它不只是发送成功，还包括 QoS 1 的确认。
• 检查 Broker 的订阅关系是否生效。我之前做一个项目时，设备连接时设了cleansession=1，每次重连都会清掉所有订阅和离线消息，如果电脑端在设备重连前发布消息，那设备根本收不到。
• 检查 Broker 的消息保留配置，有些 Broker 默认不保留消息，你发布的时候没有设保留标志，那后来订阅的客户端自然收不到之前的消息。

5.3 记忆体爆掉：Flash/RAM 不够用的对策

现象：工程编译后，Keil 报Area 'FLASH' ... overflowed by xxx bytes，或者运行时HardFault。

原因：Paho embedded-c 全量编译确实有体积，加上 LwIP 本身也挺占空间，许多 STM32F103 的芯片内部 Flash 只有 64KB~128KB，很容易吃紧。

对策：

• 将编译器优化等级从-O0调到-Os（Optimize for size），通常能省 20%~30% 代码空间。
• 裁剪 Paho 库本身：把不需要的 QoS 2 相关代码注释掉，或者直接定义宏禁用。
• 用 LwIP 的 raw API 替代 netconn/socket，省掉一层封装，但需要自己写更底层的移植代码。
• 换用更小的库，比如回到第 2.4 节的自研方案，或者用 AT 指令透传方案。
• 最实在的方案：换用更大 Flash 的芯片，比如从 STM32F103C8T6（64KB）升级到 STM32F103RCT6（256KB），成本几乎没差几块钱，但开发效率提升一个量级。

5.4 重连风暴：服务端被设备打崩

现象：设备因为网络波动掉线，然后每秒钟疯狂重连服务器，导致服务器 CPU 飙升，甚至把其他设备的连接也挤掉。

原因：重连逻辑没有做退避，代码里while(1)里直接connect，失败就立即循环重试。

对策：

• 加上退避算法，具体策略是：第一次失败后等 1 秒，第二次等 2 秒，第三次等 4 秒，最大 30 秒封顶。
• 重连前检查网络层状态，如果本地网卡没有起来或者 DHCP 没成功，根本不用尝试 TCP 连接。
• 如果用了 RTOS，把重连逻辑放到独立任务里，并且用信号量或事件标志组控制，避免在主循环里死等。

5.5 升级/断电后突然连不上

现象：固件升级后，或者设备断电重启后，发布消息失败，但之前是好的。

排查：

• 检查服务器端是否设置了“黑名单”或者“设备限制”，比如单一 client ID 只能允许一个连接。某些云平台对重复 client ID 连接会踢掉旧连接，但如果有旧的连接占用，新连接可能失败。
• 检查设备侧是否保存了错误的配置参数，比如服务器地址变更、端口变更，但 Flash 里的配置还是旧的。
• 检查 MQTT 版本是否被服务端禁用。有些平台禁用 MQTT 3.1.0 或 3.1.1，只允许 5.0。

5.6 证书/TLS 相关：嵌入式 TLS 的教训

现象：使用 MQTTS（8883 端口）时，无法建立连接，或者连接后立刻断开。

排查：

• 确保启用 wolfSSL 或 mbedTLS 时，证书格式正确（PEM 或 DER）。
• 嵌入式系统的时钟如果不对，TLS 证书验证会失败。STM32 很多开发板没有 RTC 电池，默认时间是 2000 年，证书有效期校验直接不通过。我当时踩过一次，加了一个小补丁：先通过网络 NTP 校时，再建立 TLS 连接，问题就解决了。
• 检查堆空间是否足够。TLS 握手及加密过程的开销比裸 MQTT 大很多，栈空间不够会出现随机性失败。

6. 我最终给你的选择清单

写到这里，我不想给你灌太多“要综合考量”的空话，直接给一份可操作的选择清单：

1. 如果你用的是常用开发板（F407/F429 级别），项目里已经或计划跑 LwIP，且要做实时双向通信、又比较看重社区生态，直接无脑选 Paho embedded-c。
2. 如果你用的是 AT 模组，比如 ESP8266、ESP32、Air724UG，建议先用模组自带 MQTT AT 指令，别在 STM32 侧自己实现协议。比如 ESP-AT 里直接输入AT+MQTTCONN、AT+MQTTPUB，省时省力，而且速度和稳定性都更好。
3. 如果你的芯片只有 48KB Flash / 20KB RAM，连 LwIP 都跑得艰难，那就自研最小 MQTT 发布端，并通过查询方式上报数据。等以后升级硬件再考虑完整功能。
4. 如果你对安全要求高，且网络环境比较恶劣，优先考虑 wolfMQTT 或 Paho + mbedTLS/wolfSSL 的 TLS 方案，但是嵌入式 TLS 对整个系统的资源消耗要有心理准备。
5. 如果你的团队已经熟悉 Mongoose，那就顺水推舟用它。前提是它的 MQTT 功能已经覆盖你的需求，否则不要为了 MQTT 硬引入。

最后分享一个我个人的习惯：选型不只看“库能不能用”，更要看“出了问题能不能救”。Paho 因为玩的人多，几乎每种异常都能在搜索引擎里找到类似案例；自研方案一旦出问题，只能自己读协议文档干瞪眼。所以在资源允许的前提下，我倾向于选生态更成熟的库，而不是一味追求小。本文篇幅有限，没法把每一步配置都展开到文档级，如果你在移植中卡住了，欢迎按我的思路一步步排查，多数问题都出在网络通路而非 MQTT 协议本身，稳住心态、打印几行日志，很快就能定位。