简介：一份面向物联网与嵌入式开发者的 paho-mqtt-c 通信实现代码，围绕 C 语言环境下的 MQTT 客户端接入展开，涉及连接 broker、发布与订阅消息、遗嘱设置、断线自动重连以及 SSL/TLS 加密通信等常见场景，适合需要快速验证 MQTT 链路或为设备端集成安全连接的初中级开发者参考。压缩包共 2 个文件，包含 1 个 c 源文件和 1 个 h 头文件，整体约 2KB，源码实现与接口声明分离，便于纳入现有工程编译并进行二次修改。已有 3366 人学习下载，说明该主题在物联网通信实践中具备一定关注度。读者可从中了解 MQTTClient 的创建、连接参数配置、消息收发回调注册，以及证书与密钥相关的加密连接选项设置，并据此梳理断线重连和遗嘱消息的处理思路，可作为设备端 MQTT 模块搭建、联调与问题排查时的参考实现。
1. 用 paho-mqtt-c 打通 MQTT 通讯：TLS 那一步才是真正的分水岭
在边缘网关上跑 MQTT，把 paho-mqtt-c 编进工程只花十分钟，把ssl://连上却可能耗掉一个通宵。明文 1883 跑通只能算热身，真正决定这套通讯能不能上生产的是三件事：证书链对不对、主机名校验过不过、掉线之后能不能自己回来。paho-mqtt-c 是 C 写的 MQTT 客户端库，同步MQTTClient和异步MQTTAsync两套 API，编译时把PAHO_WITH_SSL打开就带 TLS 能力，适合网关、工控盒子、车载终端这类连运行时都没有的裸环境。下面按「编进来 → 连上去 → 掉线能自己回来 → 出问题怎么查」的顺序走一遍，命令和参数都是能直接抄的。
2. 编译与接入：四种库文件选哪个，CMake 怎么挂
拿到源码先别急着make，先想清楚要哪一种产物。paho-mqtt-c 编译出来是四个库，区别只有两个维度：同步还是异步、带不带 TLS。选错了不会编译报错，而是在运行到MQTTClient_connect返回-1的时候才让你知道，那时候排查成本就高了。
| 库文件 | API 模型 | TLS | 典型场景 |
|---|---|---|---|
| libpaho-mqtt3c | 同步MQTTClient | 否 | 单线程小工具、命令行验证 |
| libpaho-mqtt3cs | 同步MQTTClient | 是 | 采集频率低、逻辑简单的网关 |
| libpaho-mqtt3a | 异步MQTTAsync | 否 | 高吞吐、需要非阻塞的场合 |
| libpaho-mqtt3as | 异步MQTTAsync | 是 | 多主题并发、上报与下发混跑 |
带s的那个才是 SSL 版本，这个字母很多人第一次都会看漏。我一般会同时编出静态库和动态库：联调阶段用动态库方便替换，出厂固件里链静态库省得处理LD_LIBRARY_PATH。
2.1 打开 PAHO_WITH_SSL 的编译参数
发行版仓库里那份libpaho-mqtt3c大概率没开 TLS，即使开了也未必对应你要的目标架构，所以交叉编译环境下基本只能自己编。下面这套参数我用了很久，出问题最少：
cmake -S . -B build \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/opt/paho-mqtt-c \ -DPAHO_WITH_SSL=TRUE \ -DPAHO_BUILD_SHARED=TRUE \ -DPAHO_BUILD_STATIC=TRUE \ -DPAHO_BUILD_SAMPLES=TRUE \ -DPAHO_ENABLE_TESTING=FALSE \ -DPAHO_HIGH_PERFORMANCE=TRUE cmake --build build -j"$(nproc)" cmake --install build几个参数值得单独说清楚：
PAHO_WITH_SSL=TRUE是总开关，它会让 CMake 去找系统的 TLS 库头文件和库文件。找不到的时候不会静默跳过，而是直接报Could NOT find OpenSSL，这时候要么装开发包，要么用-DOPENSSL_ROOT_DIR=/path/to/your/tls指过去。PAHO_BUILD_SAMPLES=TRUE在联调阶段一定要开。源码里的示例工程里有现成的 TLS 连接代码，字段名和当前版本的头文件是严格对齐的，比自己照着记忆写靠谱得多。PAHO_HIGH_PERFORMANCE=TRUE会去掉库内部的内存跟踪和堆调试逻辑，减少每次收发时的额外开销。代价是出问题时少一层可观测性，所以我的习惯是：联调分支不开，出固件才开。CMAKE_INSTALL_PREFIX装到独立前缀而不是/usr/local，是为了同一台机器上能并存多个版本，也方便打包时整目录拷走。
交叉编译时加-DCMAKE_TOOLCHAIN_FILE=xxx.cmake，同时务必在工具链文件里显式指定OPENSSL_ROOT_DIR和目标平台的CMAKE_FIND_ROOT_PATH。这里有个非常隐蔽的失败：CMake 找到了宿主机的 TLS 库，编译能过，链接也能过，但产物在目标板上跑起来段错误或者握手直接失败，因为链接进去的是 x86 的.so。查这个问题最快的办法是装完跑一次：
# 看产物到底依赖了什么、是不是目标架构 file /opt/paho-mqtt-c/lib/libpaho-mqtt3cs.so* readelf -d /opt/paho-mqtt-c/lib/libpaho-mqtt3cs.so | grep NEEDED输出里如果出现宿主机路径下的库，或者架构显示成 x86-64 而目标板是 arm，那就是找错了。别怀疑代码，怀疑工具链文件。
2.2 把库挂进自己的工程：导入目标与手写链接
安装完成之后，lib/cmake目录下会有配置文件，工程里用find_package挂进去最省事：
# 指向自己安装的前缀，CMAKE_PREFIX_PATH 也可以在命令行 -D 传 list(APPEND CMAKE_PREFIX_PATH "/opt/paho-mqtt-c") find_package(eclipse-paho-mqtt-c REQUIRED) add_executable(gateway gateway.c) # 同步 + TLS 选 3cs；异步 + TLS 换成 3as target_link_libraries(gateway PRIVATE eclipse-paho-mqtt-c::paho-mqtt3cs)导入目标的名字在不同小版本之间有过调整，有的带命名空间前缀、有的不带，最稳的做法是装完之后ls /opt/paho-mqtt-c/lib/cmake/看一眼配置文件里add_library(... IMPORTED)那几行，照着写。找不到配置文件（比如为了省体积只留了.a和头文件）就退回手写链接：
gcc -O2 -o gateway gateway.c \ -I/opt/paho-mqtt-c/include \ -L/opt/paho-mqtt-c/lib \ -lpaho-mqtt3cs -lssl -lcrypto -lpthread -lm链接顺序不能乱，-lpaho-mqtt3cs必须排在-lssl -lcrypto前面，否则静态链接时会报一堆undefined reference to SSL_xxx。这不是玄学，是链接器从左到右解析依赖的老规矩，静态库场景下顺序错了就是过不去，血泪经验。
运行时如果是动态库，记得让加载器找得到：
# 临时验证 export LD_LIBRARY_PATH=/opt/paho-mqtt-c/lib:$LD_LIBRARY_PATH # 长期方案：写进 /etc/ld.so.conf.d/ 后刷新 echo "/opt/paho-mqtt-c/lib" | sudo tee /etc/ld.so.conf.d/paho.conf sudo ldconfig3. TLS 链路：证书怎么发、MQTTClient_SSLOptions 怎么填
明文能通之后，把地址改成ssl://host:8883就以为完事，这是最常见的翻车起点。TLS 这一层有四个独立环节会各自失败：证书链能不能验、主机名对不对得上、客户端证书 broker 认不认、协议版本和加密套件有没有交集。任何一个环节断了，paho 给你的返回码往往都只是-1，看不出所以然，所以这一章的重点是把校验真正打开，再给它配一个能说话的通道。
3.1 一套能过校验的证书：SAN、EKU 和 CA 链
自签证书最容易踩的坑是只填了CN，没写subjectAltName。现在的校验逻辑基本都看 SAN，不看 CN，只填 CN 的证书在客户端开verify=1之后一定失败，而且报错信息通常藏在底层 TLS 库里，不抓出来根本看不到。
# 测试环境的一套最小证书：CA / 服务端 / 客户端 # 生产请走企业 CA 签发流程，下面这套只用于内网验证 openssl genrsa -out ca.key 2048 openssl req -new -x509 -days 3650 -key ca.key -out ca.pem \ -subj "/CN=site-mqtt-test-ca" # 服务端：SAN 必须同时写上域名和 IP，客户端用哪个地址连就得有哪个 openssl genrsa -out server.key 2048 openssl req -new -key server.key -out server.csr -subj "/CN=mqtt.local" openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \ -out server.pem -days 825 -sha256 \ -extfile <(printf "subjectAltName=DNS:mqtt.local,IP:127.0.0.1\nextendedKeyUsage=serverAuth") # 客户端证书：EKU 必须是 clientAuth，方向写反了握手照样失败 openssl genrsa -out client.key 2048 openssl req -new -key client.key -out client.csr -subj "/CN=edge-gw-01" openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial \ -out client.pem -days 825 -sha256 \ -extfile <(printf "subjectAltName=DNS:edge-gw-01\nextendedKeyUsage=clientAuth")几个容易忽略的点：-days 825不是随便写的，部分平台的根信任策略对有效期有上限；ca.pem交给客户端当trustStore，如果中间还有一级签发 CA，必须把整条链按「叶子在上、根在下」或者反过来按库的期望顺序拼成一个文件，只放根证书而 broker 只发叶子证书时，补链失败一样过不去。服务端那边配的证书文件同理，最好是server.pem里已经把中间证书拼在叶子后面。
3.2 SSLOptions 的六个关键字段
MQTTClient_SSLOptions里字段不少，但真正决定成败的就那么几个。下面这张表是我自己排查时对着看的：
| 字段 | 建议值 | 作用与坑点 |
|---|---|---|
| trustStore | CA 证书或证书链路径 | 只认文件路径，不认内存里的一串 PEM |
| keyStore | 客户端证书路径 | 单向认证时可留空，双向认证必填 |
| privateKey | 客户端私钥路径 | 可以独立于 keyStore 单独放，权限要给到运行用户 |
| enableServerCertAuth | 1 | 不设成 1，服务端证书链根本不会被校验 |
| verify | 1 | 只做主机名和证书 SAN 的比对，不等于链校验 |
| sslVersion | MQTT_SSL_VERSION_DEFAULT | 让握手自己协商；写死低版本会被现代 broker 拒绝 |
enableServerCertAuth和verify是两个开关，很多人只设了后者，以为开了校验，实际上服务端证书链压根没验，等于裸奔。这两个一起置 1 才是完整校验。
还有一个救命的字段是ssl_error_cb。TLS 握手失败时库对外只返回一个笼统的失败码，真正的错误信息（比如certificate verify failed、hostname mismatch、no shared cipher）要通过这个回调才能拿到：
/* 回调签名固定，str 是底层 TLS 库吐出来的错误串，len 是长度 */ static int on_ssl_error(const char *str, size_t len, void *context) { (void)context; fprintf(stderr, "[tls] %.*s\n", (int)len, str); return 0; /* 返回非 0 会中断握手，调试阶段返回 0 让它继续把错误吐完 */ }联调期把这个回调挂上，等于给自己留了一支后悔药，能省掉大量「连不上但不知道为什么」的时间。
3.3 从连接到发布的完整闭环
把上面几块拼起来，就是一个能跑的最小闭环。下面这段代码我删掉了业务逻辑，只保留链路相关的部分：
/* gateway.c —— 同步客户端 + TLS 的最小闭环 */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <unistd.h> #include "MQTTClient.h" #define TOPIC_SUB "site/+/gw/+/telemetry" #define QOS 1 static volatile int g_connected = 1; static int on_ssl_error(const char *str, size_t len, void *context) { (void)context; fprintf(stderr, "[tls] %.*s\n", (int)len, str); return 0; } static void conn_lost(void *context, char *cause) { (void)context; fprintf(stderr, "[mqtt] lost: %s\n", cause ? cause : "unknown"); g_connected = 0; /* 回调里只置标志，重连交给主线程 */ } static int on_message(void *context, char *topic, int topic_len, MQTTClient_message *msg) { (void)context; (void)topic_len; printf("recv %s (%d) %.*s\n", topic, msg->payloadlen, msg->payloadlen, (char *)msg->payload); /* 这两个释放一个都不能少，漏了就是稳定每小时涨一点内存 */ MQTTClient_freeMessage(&msg); MQTTClient_free(topic); return 1; } static void on_delivered(void *context, MQTTClient_deliveryToken dt) { (void)context; (void)dt; } int main(void) { MQTTClient client; /* 地址前缀决定走不走 TLS：只有 ssl:// 才会去读 conn_opts.ssl */ int rc = MQTTClient_create(&client, "ssl://127.0.0.1:8883", "edge-gw-01", MQTTCLIENT_PERSISTENCE_DEFAULT, "/var/lib/mqtt/state"); if (rc != MQTTCLIENT_SUCCESS) { fprintf(stderr, "create failed rc=%d\n", rc); return 1; } MQTTClient_setCallbacks(client, NULL, conn_lost, on_message, on_delivered); MQTTClient_connectOptions opts = MQTTClient_connectOptions_initializer; opts.keepAliveInterval = 30; /* 中间设备多，30 秒比 60 秒稳 */ opts.cleansession = 0; /* 保留会话，离线消息才有意义 */ opts.connectTimeout = 10; opts.retryInterval = 0; /* 库内不重试，重连由外层退避控制 */ MQTTClient_SSLOptions ssl = MQTTClient_SSLOptions_initializer; ssl.trustStore = "/etc/mqtt/ca/ca-chain.pem"; ssl.keyStore = "/etc/mqtt/client/client.pem"; ssl.privateKey = "/etc/mqtt/client/client.key"; ssl.enableServerCertAuth = 1; /* 打开证书链校验 */ ssl.verify = 1; /* 打开主机名校验 */ ssl.sslVersion = MQTT_SSL_VERSION_DEFAULT; ssl.enabledCipherSuites = "ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256"; ssl.ssl_error_cb = on_ssl_error; ssl.ssl_error_context = NULL; opts.ssl = &ssl; rc = MQTTClient_connect(client, &opts); if (rc != MQTTCLIENT_SUCCESS) { fprintf(stderr, "connect failed rc=%d\n", rc); MQTTClient_destroy(&client); return 2; } MQTTClient_subscribe(client, TOPIC_SUB, QOS); MQTTClient_message msg = MQTTClient_message_initializer; const char *payload = "{\"gw\":\"edge-gw-01\",\"temp\":21.4}"; MQTTClient_deliveryToken token; msg.payload = (void *)payload; msg.payloadlen = (int)strlen(payload); msg.qos = QOS; msg.retained = 0; MQTTClient_publishMessage(client, "site/a/gw/edge-gw-01/telemetry", &msg, &token); MQTTClient_waitForCompletion(client, token, 5000L); /* 等 PUBACK，超时说明链路有问题 */ while (g_connected) sleep(1); MQTTClient_disconnect(client, 1000); MQTTClient_destroy(&client); return 0; }几个参数值得再强调一下。keepAliveInterval决定心跳周期，设成 60 秒在实验室没问题，到了现场只要中间隔一层会主动回收空闲会话的设备，就会出现「每几分钟掉一次、重连又正常」的规律性现象，改成 30 秒以内通常就消失。cleansession=0要求客户端 ID 稳定且唯一，同一时刻两个进程用同一个 ID 会互相踢下线，表现是连接成功后几秒内被断开，而且没有明显报错。waitForCompletion给 5 秒是经验值，QoS 1 下它等的是 PUBACK，超时就说明上行链路或者 broker 那边有问题，早发现比晚发现好。
4. 断线与投递：把示例代码改成能在现场跑的实现
示例代码里连接成功就while(1)死循环，这种写法在办公室跑一天不出事，装到现场第二天就掉线后再也连不回来。原因很简单：网络断了之后MQTTClient_connect那一步没人重新调，而库本身没有义务替你无限重连。这一章解决两件事：连接怎么自动回来，以及 QoS 1 的消息在断线期间怎么办。
4.1 connlost 回调与指数退避重连
connlost回调是在库的内部线程里触发的，这里有个严格的纪律：回调里不要调用任何会阻塞等响应的 MQTT API。有人在connlost里直接MQTTClient_connect重连，或者在消息回调里直接MQTTClient_publishMessage加waitForCompletion，运气好时能跑，运气差时就是随机卡死。同步客户端在内部线程里再进一次同步调用，等的是自己，典型的死锁现场。
正确做法是回调只做最少的事：置标志、把消息塞进自己的队列，真正的收发放主线程或工作线程。
/* 主循环里的重连：1s 起步，翻倍到 60s 封顶，连上后重置 */ static int reconnect_with_backoff(MQTTClient client, MQTTClient_connectOptions *opts) { int delay = 1; for (int attempt = 0; attempt < 12; ++attempt) { int rc = MQTTClient_connect(client, opts); if (rc == MQTTCLIENT_SUCCESS) { return 0; } fprintf(stderr, "connect rc=%d, retry in %ds\n", rc, delay); sleep(delay); delay = (delay * 2 > 60) ? 60 : delay * 2; /* 封顶，别让间隔无限涨 */ } return -1; } /* 重连成功后必须重新订阅：cleansession=1 时会话是新的，订阅全丢 */ static void resubscribe_all(MQTTClient client) { MQTTClient_subscribe(client, "site/+/gw/+/telemetry", QOS); MQTTClient_subscribe(client, "site/+/gw/+/cmd", QOS); }退避一定要封顶。我见过上线版本里间隔一路涨到几十分钟的，现场断电重启后设备半小时才恢复上报，监控上看着就像彻底失联。另外退避只对「连不上」生效，一旦连上就必须把delay重置回 1，否则下次短暂抖动会直接等 60 秒。
cleansession的选择直接影响重连逻辑：设成 1，每次重连都是全新会话，broker 不留离线消息，重连后必须自己重新订阅；设成 0，会话保留，订阅关系还在，但要求客户端 ID 固定、状态目录可写、broker 侧允许长会话。工控场景我一般选 0，配合持久化目录，能少掉一批「断网期间下发的指令丢了」的扯皮。
4.2 QoS1 落盘、去重与 cleansession 的选择
QoS 1 的语义是「至少一次」，也就是说重复投递是设计行为，不是 bug。指望库帮你做到精确一次会失望，去重必须在业务侧做。常见做法是在 payload 里带一个单调递增的序号，接收端维护一个滑动窗口，见到旧序号直接丢弃：
/* 接收侧去重：只保留最近 64 个序号，够覆盖乱序和重投 */ #define WIN 64 static unsigned long long g_seen[WIN]; static int g_seen_pos = 0; static int is_duplicate(unsigned long long seq) { for (int i = 0; i < WIN; ++i) { if (g_seen[i] == seq && seq != 0) return 1; } g_seen[g_seen_pos] = seq; g_seen_pos = (g_seen_pos + 1) % WIN; return 0; }发送侧要持久化的是「还没收到 PUBACK 的消息」。同步客户端配MQTTCLIENT_PERSISTENCE_DEFAULT并把目录指到可写分区，库会把未确认的 QoS 1/2 消息落到本地，重连后按会话状态补发。这里有个必须验证的点：目录所在分区是不是可写、掉电后文件会不会损坏、重启后能不能正常加载。我遇到过状态文件写在只读的 rootfs 上，写失败但库不报错，表现就是断网期间的消息在重启后全部消失，查了半天才发现是分区权限问题。
吞吐量上去之后，同步客户端会成为瓶颈——publishMessage加waitForCompletion的往返时间直接乘进发送周期。这时候换MQTTAsync，用MQTTAsync_sendMessage加MQTTAsync_setCallbacks的完成回调，把发送和确认解耦，单连接跑到几千条每秒是能做到的，前提是 broker 侧和对端也扛得住。
5. 避坑与排查：五个把联调拖到凌晨的问题
5.1 连上就断，日志里什么都没有
现象：MQTTClient_connect返回成功，一两秒后连接被断开，connlost里cause是空字符串或者一句很笼统的话。
原因：几乎都是客户端 ID 冲突。同一套测试环境里有人用同一个 ID 起了第二个进程，broker 按协议把前一个踢掉，客户端侧看到的就是「莫名断开」。
解决：客户端 ID 拼上设备唯一标识或进程号后缀，联调环境尤其要做。确认办法很简单，在connlost里打印当前 ID，然后grep一下有多少个进程在用同一个。
5.2 TLS 握手失败，返回码只有 -1
现象：地址从tcp://改成ssl://之后连不上，控制台只有connect failed rc=-1。
原因：没有挂ssl_error_cb，底层真正的错误被吞了。常见的几种是证书链不全、SAN 里没有连接用的那个 IP、enableServerCertAuth没置 1 导致校验逻辑走的另一条路径。
解决：先挂ssl_error_cb把底层错误打出来，再用openssl s_client -connect 127.0.0.1:8883 -servername mqtt.local -CAfile /etc/mqtt/ca/ca-chain.pem -cert /etc/mqtt/client/client.pem -key /etc/mqtt/client/client.key -tls1_2 -brief做一次纯握手。命令行能过而程序过不了，问题就在参数映射上；命令行也过不了，问题在证书本身。
5.3 服务器时间不对，证书永远「未生效」
现象：证书明明刚签发，客户端报校验失败，换一台机器同样的证书就正常。
原因：设备没有 RTC 电池，启动后系统时间停在很久以前，证书的生效时间还没到。
解决：启动流程里必须先对时再建连，或者启动时先不清 TLS 直接连一个授时端点。这是最容易忽略的一条，因为实验室的设备连着网络自动对时，永远复现不出来。
5.4 回调里发包，偶发卡死
现象：跑几小时后进程假死，gdb挂上去看到两个线程都在等锁。
原因：在connlost或消息回调里调用了同步 API。回调线程是库内部的，同步 API 在等库内部状态，互相等。
解决：回调只做投递，把消息memcpy进自己的队列，工作线程负责发布。这条规则在 paho-mqtt-c 里没有例外，写进代码规范比写在文档里管用。
5.5 私钥读了但没权限，报错指向证书
现象：配置文件和路径都对，程序就是握手失败，命令行用同一个用户跑又正常。
原因：私钥文件的权限是 600 且属主是 root，服务以普通用户运行，读不到私钥，但底层报错往往先指向证书链校验。
解决：把私钥的属主或属组调到服务运行用户，权限保持 640，别图省事改成 644——私钥可读等于认证形同虚设。上线前用sudo -u <运行用户> cat把三个文件各读一遍，确认都能读，比事后猜强。
6. 上线前的验证：握手、抓包与一轮压测
功能跑通不等于能交付，我一般会做三件事再打标签。第一件是纯握手验证，用openssl s_client带上完整的客户端证书跑一次，看协商出来的协议版本和加密套件是不是预期的那一档，输出里出现Verify return code: 0 (ok)才算过。第二件是抓包复核，tcpdump -i any -s 0 -w mqtt.pcap port 8883抓一轮连接建立，确认 ClientHello 的 SNI、证书链长度、握手指数都正常，这条路径能发现「客户端悄悄降级到旧协议」这种在代码里看不出来的问题。
第三件是一轮小压测，重点是看waitForCompletion的耗时分布而不是平均值：
# 单连接连发 1000 条 QoS1，统计每条等待 PUBACK 的耗时 # 程序里在 waitForCompletion 前后取 CLOCK_MONOTONIC，输出到 csv awk -F, '{s+=$2; if($2>m)m=$2; n++} END{printf "avg=%.2fms max=%.2fms n=%d\n", s/n, m, n}' pub.csv平均 3 ms、最大 800 ms 这种分布很常见，最大值才是你该关心的，它往往对应 broker 的磁盘刷写或者 GC 抖动。把最大值和 keepAlive 放在一起看，如果最大值接近 keepAlive 的一半，就说明这条链路的抖动已经能威胁到心跳了，得往下降 QoS 或者加批量聚合。
从那以后我每次改完连接参数，都会把「s_client 握手 + 抓包 + 一轮 1000 条压测」这三步固定走一遍，不管改动多小。踩过的坑告诉我，TLS 和重连这两块的问题从来不会在改完的那一刻暴露，它们只会在设备装到现场之后的某个凌晨两点出现。希望帮到你。
本文还有配套的精品资源，点击获取
