Paho MQTT C 与 C++ 客户端库完全指南：从概念到 Ubuntu 26.04 下的编译、安装与使用

你之前执行的那串 git clone + cmake 命令，是在从源码编译安装 Eclipse Paho MQTT C 客户端库。Paho 是 Eclipse 基金会旗下的开源物联网项目，提供多种语言的 MQTT 客户端实现。其中，C 库是协议实现的基础，C++ 库则构建在 C 库之上，提供面向对象的封装。

既然你的应用决定采用 C++17 标准，在 Ubuntu 26.04 上，安装流程可以大幅简化：不需要再从源码编译 C 或 C++ 库，直接用 apt 安装即可。但理解底层原理和编译链接的细节，仍然对排查问题至关重要。这篇文章会详细介绍 Paho C 与 C++ 的关系、版本要求、apt 安装方式，以及完整的编译与链接方法（包括 CMake 和手动 g++ 两种方式）。

一、Paho MQTT C：根基所在

Paho MQTT C 客户端库是用 ANSI 标准 C 编写的全功能 MQTT 客户端，设计目标是最大化可移植性。它主要面向 Linux、Windows 等具备完整操作系统支持的环境（依赖 Socket、线程等系统调用），而非资源受限的裸机嵌入式设备（后者有专门的 Embedded C 版本）。

它提供两套 API：

  • 同步 API（MQTTClient）：调用阻塞直到操作完成，逻辑直观，适合常规场景。
  • 异步 API（MQTTAsync）：非阻塞，结果通过回调通知，适合需要保持主线程响应的应用。

编译后通常产生四个动态库变体，对应不同功能组合：libpaho-mqtt3c（同步无 SSL）、libpaho-mqtt3cs（同步带 SSL）、libpaho-mqtt3a（异步无 SSL）、libpaho-mqtt3as（异步带 SSL）。

二、Paho MQTT C++：C 库之上的现代封装

Paho MQTT C++ 本质上是对 C 库的面向对象封装，并非独立的底层协议实现。它的价值在于：利用 C++ 语言特性（std::string、智能指针、异常处理）让代码更简洁安全，并在 C 库能力之上提供自动重连、离线消息缓冲、消息持久化等生产环境常用特性。

关键依赖关系：C++ 库必须依赖 C 库才能工作。Ubuntu 26.04 源中的 libpaho-mqttpp3-1 包明确声明依赖 libpaho-mqtt1.3 (>= 1.3.14)。这意味着安装 C++ 库时，apt 会自动确保 C 库版本满足要求。

三、关键版本分水岭：C++17 要求从何而来

这是你之前纠结的核心问题。Paho MQTT C++ 官方说明：从 v1.5 版本开始，库使用 C++17 特性，需要完全兼容 C++17 的编译器（GCC v8 或更高）。Ubuntu 26.04 (resolute) 源中提供的 libpaho-mqttpp3-1 版本是 1.5.3（根据 Ubuntu 包详情页），libpaho-mqttpp-dev 的版本则更新至 1.6.0（根据 Ubuntu 源目录索引）。无论具体是 1.5.3 还是 1.6.0，都要求 C++17。

所以，你的决定是正确的：应用改用 C++17，一切矛盾迎刃而解。Debian 包描述里可能仍写着 “C++11 applications”，那是上游历史遗留的模板文字，不代表 1.5+ 的二进制库仍为 C++11 ABI 做保证。版本号本身才是判断依据。

四、Ubuntu 26.04 上的安装方式：直接 apt，无需编译

4.1 安装 Paho MQTT C 库

Ubuntu 26.04 源中的 libpaho-mqtt-dev 版本满足 C++ 库的要求。直接安装：

sudo apt update
sudo apt install libpaho-mqtt-dev

安装后，头文件位于 /usr/include，库文件位于 /usr/lib/x86_64-linux-gnu/。

4.2 安装 Paho MQTT C++ 库

apt 会自动处理对 C 库的依赖：

sudo apt install libpaho-mqttpp-dev

这一步安装的版本要求你的应用以 C++17 编译。安装完成后无需手动 ldconfig。

4.3 验证安装

dpkg -l | grep paho

应该能看到 libpaho-mqtt-dev 和 libpaho-mqttpp-dev 两个包。还可以检查库文件是否存在：

ls /usr/lib/x86_64-linux-gnu/libpaho-mqtt*

五、编译方法详解（核心部分）

安装只是第一步，编译链接才是把库用起来的关键。以下给出两种方式，并解释每一步的含义。

5.1 方式一：使用 CMake（推荐，适合正式项目）

CMake 能自动处理 C++ 库对 C 库的链接依赖，是最省心的方式。

CMakeLists.txt 示例：

cmake_minimum_required(VERSION 3.13)
project(my_mqtt_app LANGUAGES CXX)

# 强制使用 C++17 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# 查找 Paho C++ 包
find_package(PahoMqttCpp REQUIRED)

# 你的可执行目标
add_executable(my_app main.cpp)

# 链接 Paho C++ 库（CMake 会自动带入底层 C 库依赖）
target_link_libraries(my_app PRIVATE PahoMqttCpp::paho-mqttpp3)

配置与构建：

mkdir -p build && cd build
cmake ..
cmake --build .

关键点解释：

  • find_package(PahoMqttCpp REQUIRED)：让 CMake 查找已安装的 Paho C++ 库的配置文件（通常位于 /usr/lib/x86_64-linux-gnu/cmake/PahoMqttCpp/）。如果找不到，会直接报错，避免后续链接失败。
  • PahoMqttCpp::paho-mqttpp3：这是 CMake 导入的目标名，它不仅包含 C++ 库本身，还通过 INTERFACE_LINK_LIBRARIES 携带了它依赖的 C 库信息。你不需要手动再写 -lpaho-mqtt3as，CMake 会帮你处理。
  • CMAKE_CXX_EXTENSIONS OFF：禁用 GNU 扩展，保证代码的可移植性。如果你使用了 GNU 特有扩展，可以移除此行。

5.2 方式二：手动使用 g++ 命令行

如果你不使用 CMake，或者只是想快速验证一个示例程序，可以直接用 g++ 编译。这时需要自己处理链接顺序和库名选择。

编译命令模板：

g++ -std=c++17 -o my_app main.cpp \
    -lpaho-mqttpp3 \
    -lpaho-mqtt3as

每个参数的含义：

参数作用说明
-std=c++17指定 C++ 标准必须，因为 Paho C++ 1.5+ 使用了 C++17 特性
-lpaho-mqttpp3链接 Paho C++ 封装库提供 mqtt::async_client、mqtt::client 等 C++ 类
-lpaho-mqtt3as链接 Paho C 库（异步 + SSL）提供底层协议实现

关于 -lpaho-mqtt3as 的选择：C 库有四个变体，你需要根据代码中实际使用的 API 和是否启用 SSL 来选择：

你的代码使用…且需要 SSL/TLS？链接参数
异步 API（mqtt::async_client）是-lpaho-mqtt3as
异步 API（mqtt::async_client）否-lpaho-mqtt3a
同步 API（mqtt::client）是-lpaho-mqtt3cs
同步 API（mqtt::client）否-lpaho-mqtt3c

链接顺序铁律：-lpaho-mqttpp3 必须放在 -lpaho-mqtt3as（或对应变体）之前。这是因为 C++ 库的符号引用了 C 库的符号，GNU 链接器按从左到右的顺序解析依赖。如果顺序反了，会出现 undefined reference to ... 错误。

5.3 编译一个完整的 C++17 示例（验证用）

创建一个简单的 main.cpp 来验证整个链路是否通畅：

#include <mqtt/async_client.h>
#include <iostream>

int main() {
    // 仅创建客户端对象，不实际连接（避免依赖真实 broker）
    mqtt::async_client client("tcp://localhost:1883", "test_client");
    std::cout << "Paho C++ async_client created successfully." << std::endl;
    return 0;
}

用 CMake 方式构建（假设 CMakeLists.txt 如上文所示），或者手动编译：

g++ -std=c++17 -o test_paho main.cpp -lpaho-mqttpp3 -lpaho-mqtt3as

运行：

./test_paho

如果输出 Paho C++ async_client created successfully.，说明安装和链接全部正确。如果运行时提示找不到共享库（虽然 apt 安装的库通常不会），执行 sudo ldconfig 刷新缓存即可。

六、为什么这个方案比源码编译更优

对比你最初执行的 git clone + cmake 流程：

对比项源码编译apt 直接安装
操作复杂度克隆、切换 tag、cmake 配置、编译、ldconfig两条 apt install
版本管理手动跟踪 GitHub Releasesapt upgrade 自动更新
C++ 标准兼容性需手动选旧版并强制 -std=c++11直接使用 1.5.3/1.6.0，配合 C++17 应用
依赖处理需自行确保 C 库先装且版本正确apt 自动解析依赖（libpaho-mqtt1.3 >= 1.3.14）

唯一需要注意的是：你的应用代码本身必须能通过 C++17 编译器的检查。如果代码中使用了 C++11 时代已弃用但在 C++17 中被移除的特性（如 std::auto_ptr），需要顺手替换。

总结

你的路径现在非常清晰：

  1. 应用升级到 C++17
  2. 在 Ubuntu 26.04 上直接安装：sudo apt install libpaho-mqtt-dev libpaho-mqttpp-dev
  3. 编译时指定标准：CMake 中用 set(CMAKE_CXX_STANDARD 17)，或 g++ 中用 -std=c++17
  4. 链接时注意：CMake 用 PahoMqttCpp::paho-mqttpp3 即可；手动 g++ 时 C++ 库在前、C 库在后，并根据 API 类型和 SSL 需求选择正确的 C 库变体

不再需要源码编译，也不再需要纠结版本兼容。剩下的工作就是编写你的 MQTT 业务逻辑了。

作者

老丹

关注我
其他文章