Fyfutdr如果你的程序是用 C 写的，又必须在设备和服务器之间走 MQTT 协议，那 Eclipse Paho MQTT C 客户端库大概率是你绕不开的名字。我最早接触它是在一个车载数据网关项目里：设备端是 ARM Linux，业务代码是 C，要把 GPS 和 CAN 总线数据上行到云端 Broker，还要接收云端下发的控制指令。当时我用一个下午对比了各种 C 语言 MQTT 方案，最后还是留下了 Paho，因为它的成熟度、文档完整度和代码活跃度都明显高于同类开源库。
这篇文章不是照着 README 翻译一遍，而是把我从选型、编译、同步 API、异步 API 到 QoS、遗嘱消息、断线重连这些实战环节里积累下来的经验整理出来。如果你是第一次用 Paho MQTT C 客户端库，或者已经在用但经常遇到连接异常、收不到消息、回调卡死这类问题，这篇内容能帮你少走不少弯路。
1. Paho MQTT C客户端库在MQTT生态里的角色与两个容易混淆的分支
1.1 Paho到底是个库还是一个服务
先澄清一个概念：Paho 不是 Broker，也不是一套完整的云平台方案。Eclipse Paho 是 Eclipse 基金会下面的开源项目，提供多种语言实现的 MQTT 客户端。C 版本解决的是“我的程序用 C 编写，需要稳定、可控地连接一个 MQTT Broker，完成发布和订阅”这件事。
MQTT 本身是发布订阅协议，Broker 负责消息路由，客户端负责收发。Paho C 库就是那个客户端。它能处理的细节包括 TCP 长连接维护、心跳保活、QoS 1/2 的确认流程、遗嘱消息、会话恢复、TLS 加密连接等。如果你只是想用 C 快速地连上一个本地 Broker，Paho 给你封装好了底层状态机，你不必自己去拼 CONNECT 报文、解析 PUBLISH 报文。
我还记得早期项目里有个同事觉得 MQTT 报文格式不复杂，协议头就那么几个字节，于是自己写了一套解析代码。单看报文收发确实跑通了，但一到弱网环境就开始出问题：断线后重连要重建会话、QoS 1 的 PUBACK 丢失后消息重复、心跳超时判定不准、Broker 主动断开时客户端毫不知情。这些恰恰是 Paho 已经处理得很成熟的领域。
1.2 paho.mqtt.c 和 paho.mqtt.embedded-c 不是同一个库
网上搜“Paho MQTT C”会出两个项目，这是初学者最容易搞混的地方。
一个是 eclipse/paho.mqtt.c，全功能 C/C++ 客户端库，主要跑在 Linux、Windows、macOS 或者有完整 POSIX 环境的嵌入式系统上。它内置 TCP 和 TLS 能力，API 分为同步和异步两套。这个库会帮你管好 socket、线程、重连、持久化，适合“设备端跑着 Linux，内存有余量”的场景。
另一个是 eclipse/paho.mqtt.embedded-c，定位是资源受限的 MCU。它更像一个协议编解码器，网络 I/O 是交给你自己实现的。你需要自己提供连接 socket、读写字节流的能力，库只负责把 MQTT 报文的编码和解码处理好。STM32、裸机环境、极小 RAM 的嵌入式设备更倾向于用它，或者直接用厂商自己封装的 MQTT 库。
这两者选错会很痛苦。我在一个 RTOS 项目上看到有人硬把 paho.mqtt.c 交叉编译出来，结果线程库、动态内存、ssl 依赖一大堆，最后换成了 embedded-c 才把资源占用降下来。反过来，在 Linux 网关上用