一、背景简介

• Qt6：跨平台 C++ 框架，广泛用于嵌入式、物联网软件开发。

• MQTT：轻量级发布/订阅消息协议，适合低带宽、实时通信场景。

本文基于 Windows 10/11 + Qt 6.6.2/MinGW 64-bit，演示如何：

• 编译 Qt 官方 MQTT 模块（QtMqtt）；

• 安装至 Qt 环境；

• 连接到公共 Broker（broker.emqx.io）；

• 实现订阅、发布、接收消息；

• 将 MQTT 模块集成到新建或现有的 Qt 项目。

二、环境准备

编译 QtMqtt 需要以下组件协同工作：

组件	推荐版本/选择	检查/获取方式
Qt 版本	与 QtMqtt 源码分支对应（本文使用 6.6.2）	通过 Qt 安装程序添加 MinGW 组件，查看“关于 Qt Creator”确认
编译器套件	MinGW 64-bit（兼容性优于 MSVC）	安装 Qt 时一并安装；避免使用 MSVC 以减少兼容性问题
CMake	≥ 3.21（Qt 6.x 要求）	cmake --version，可从 CMake 官网下载最新版
Git（可选）	任意版本	git --version，推荐用于获取指定分支源码
Perl（部分版本需要）	Strawberry Perl 或 ActivePerl	某些 Qt 版本编译 MQTT 需要 Perl 支持

🔧 环境检查要点：

• 确保 CMake、MinGW 的 bin 目录已在系统环境变量 PATH 中。

• 在 Qt Creator 中，进入 工具 → 选项 → Kits，选择你的套件（如 Desktop Qt 6.6.2 MinGW 64-bit），将 CMake 生成器设为 MinGW Makefiles。

💡 若之前未安装 MinGW 组件，需重新运行 Qt 安装程序添加，确保与后续编译所用套件一致。

三、下载 Qt MQTT 源码

从 GitHub 官方仓库克隆与你的 Qt 版本匹配的源码分支：

bash

git clone git://code.qt.io/qt/qtmqtt.git -b 6.6.2

⚠️ 版本匹配的重要性
必须下载与你的 Qt 版本完全对应的分支（例如 Qt 6.6.2 → 分支 6.6.2）。使用默认的 dev 或其他不匹配的分支将导致编译失败。

四、编译与安装

4.1 使用 Qt Creator 编译

1. 在 Qt Creator 中打开源码中的 CMakeLists.txt 文件。

2. 选择与 Qt 版本一致的 MinGW 64-bit 编译套件。

3. 点击“构建”进行编译。

编译成功后，会生成一个类似 build-qtmqtt-Desktop_Qt_6_6_2_MinGW_64_bit-Release 的文件夹，其中包含所有必需的库和配置文件。

📁 编译生成的主要内容：

• bin/：动态库（.dll 文件）

• lib/：静态库（.a 文件）以及 CMake 配置目录

• include/：头文件

• mkspecs/modules/：qmake 模块定义文件

• modules/：CMake 模块定义文件（如 Mqtt.json）

4.2 将编译产物安装到 Qt 目录

为了在所有项目中方便使用，将编译生成的文件拷贝到 Qt 安装目录对应的编译器文件夹下。假设 Qt 安装路径为 C:\Qt\6.6.2\mingw_64\，具体步骤如下：

1. 头文件：将 build-xxx/include/QtMqtt 整个目录复制到 C:\Qt\6.6.2\mingw_64\include\ 下。

2. 动态库：将 build-xxx/bin/ 下的所有文件（如 Qt6Mqtt.dll 等）复制到 C:\Qt\6.6.2\mingw_64\bin\ 目录下。

3. 静态库及 CMake 配置：将 build-xxx/lib/ 下的 所有文件 复制到 C:\Qt\6.6.2\mingw_64\lib\ 目录下。其中：

   • lib/cmake/Qt6Mqtt 目录会被拷贝进去，这样 CMake 就能通过 find_package(Qt6 REQUIRED COMPONENTS Mqtt) 找到 MQTT 模块。

   • lib/pkgconfig 等其他文件一同复制即可。

4. qmake 模块文件：将 build-xxx/mkspecs/modules/ 下的所有 .pri 文件复制到 C:\Qt\6.6.2\mingw_64\mkspecs\modules\ 目录下。

5. CMake 模块文件：将 build-xxx/modules/ 下的 Mqtt.json 复制到 C:\Qt\6.6.2\mingw_64\modules\ 目录下。

⚠️ 关键点：

• 所有拷贝操作都必须在 同一个编译器套件目录（mingw_64）下完成，调用时也必须使用 同一个编译器，否则会导致模块找不到或链接错误。

• 如果之前编译时使用的是 Debug 模式，则对应拷贝 Debug 构建目录；若为 Release 模式则拷贝 Release 目录，两者不可混用。

五、集成到现有 Qt 项目

完成上述安装后，即可在任何使用相同编译器套件的 Qt 项目中轻松引入 MQTT 模块。根据项目构建系统的不同，有以下两种集成方式：

5.1 CMake 项目集成（推荐）

对于使用 CMake 构建的 Qt 项目，在 CMakeLists.txt 中添加以下内容：

cmake

# 查找 Qt6 及 Mqtt 组件
find_package(Qt6 REQUIRED COMPONENTS Core Network Mqtt)

# 添加可执行文件
add_executable(MyMqttApp main.cpp)

# 链接 Qt6::Mqtt 及其他所需组件
target_link_libraries(MyMqttApp PRIVATE 
    Qt6::Core
    Qt6::Network 
    Qt6::Mqtt
)

其中 find_package(Qt6 REQUIRED COMPONENTS Mqtt) 会自动利用之前安装到 lib/cmake/Qt6Mqtt 的配置文件，完成头文件路径和库的查找。

5.2 qmake 项目集成

对于使用 .pro 文件的 qmake 项目，只需在配置中添加 mqtt 模块即可：

qmake

QT += core network mqtt

# 其余项目配置...
SOURCES += main.cpp

由于已将 mkspecs/modules/ 下的 qt_lib_mqtt.pri 复制到 Qt 安装目录，qmake 会自动识别 mqtt 模块的存在。

5.3 跨编译器注意事项

• 无论使用 CMake 还是 qmake，整个项目的编译器套件必须与编译 MQTT 模块时使用的套件完全一致（例如都是 mingw_64）。如果混用不同编译器（如 MinGW 与 MSVC），会导致链接时符号无法解析或运行时崩溃。

六、在项目中使用 MQTT

6.1 准备 MQTT Broker

使用免费的公共 MQTT Broker（由 EMQX 提供）进行测试：

参数	值
代理地址	broker.emqx.io
TCP 端口	1883
TLS 端口	8883
WebSocket	8083 / 8084(SSL)

6.2 核心代码示例

在集成好模块的 Qt 项目中，包含必要的头文件：

cpp

#include <QtMqtt/QtMqtt>

① 创建 MQTT 客户端

cpp

QMqttClient *m_client = new QMqttClient(this);
m_client->setHostname("broker.emqx.io");
m_client->setPort(1883);

② 接收消息

cpp

connect(m_client, &QMqttClient::messageReceived, this,
    [this](const QByteArray &message, const QMqttTopicName &topic) {
        // 处理收到的消息
        qDebug() << "Received message:" << message << "on topic:" << topic.name();
    });

③ 连接/断开 Broker

cpp

// 连接
m_client->connectToHost();
// 断开
m_client->disconnectFromHost();

④ 订阅/取消订阅

cpp

auto subscription = m_client->subscribe("test/topic");
if (!subscription) {
    qDebug() << "Subscribe failed";
}
// 取消订阅
m_client->unsubscribe("test/topic");

⑤ 发布消息

cpp

if (m_client->publish("test/topic", "Hello MQTT") == -1) {
    qDebug() << "Publish failed";
}

七、运行官方示例验证

源码目录中的 examples/mqtt/simpleclient 是一个完整的图形化 Demo。用 Qt Creator 打开其 CMakeLists.txt 或 .pro 文件，确保所选编译器套件与之前一致，直接编译运行后，填入 broker.emqx.io:1883，依次点击 Connect → Subscribe → Publish，即可看到消息收发。这也是验证模块安装是否成功的好方法。

八、常见编译错误及解决

错误现象	原因	解决方法
Could not find a package configuration file provided by "Qt6"	CMake 找不到 Qt6 安装路径	在 Qt Creator 中手动添加 CMAKE_PREFIX_PATH，指向你的 Qt 安装目录（如 C:\Qt\6.6.2\mingw_64\lib\cmake）
error: Unknown module(s) in QT: mqtt	qmake 未识别 mqtt 模块	检查是否正确将 mkspecs/modules/qt_lib_mqtt.pri 复制到了 Qt 安装目录的 mkspecs/modules/ 下
链接错误：undefined reference to ... QMqttClient	项目使用的编译器与编译 MQTT 模块的编译器不一致	确保项目 Kit 中的编译器套件与当初编译 MQTT 模块时所用的完全一致（MinGW/ MSVC 不能混用）
运行时提示找不到 Qt6Mqtt.dll	动态库路径不在系统的搜索路径中	将 bin 目录下的 .dll 文件复制到 Qt 安装目录的 bin 目录下，或将其所在目录添加到系统环境变量 PATH 中

九、总结

通过本文，你已在 Windows 平台上完成了以下工作：

• 为 Qt6 编译并集成 MQTT 模块；

• 将模块安装到 Qt 环境，并能在新项目或现有项目中通过 CMake 或 qmake 快速引入；

• 使用 EMQ 公共 Broker 进行功能验证。

所有完整代码可在 qtmqtt/examples 中找到。

在 Qt6 中使用 MQTT：入门指南 | EMQ