做 Qt 上位机、工业软件或设备联网调试，除了串口、TCP、Modbus，MQTT 也是很常见的一类协议。

很多设备并不会直接和业务系统长连接通信，而是通过网关、边缘盒子或云平台，把数据发布到某个 Topic。传感器数据上报、设备状态同步、远程控制指令、告警消息推送，都可能会用到 MQTT。

所以我做了一个用 Qt 写的 MQTT 调试助手，把日常调试里最常用的功能放到一起：连接 Broker、订阅主题、发布消息、接收数据，以及同时打开多个客户端窗口做联调。

---

主界面：连接、订阅、发布集中在一起

这里预留一张软件主界面截图。

主界面左侧是登录设置区，可以填写 Broker 的 IP 或域名、端口、客户端 ID、用户名、密码、KeepAlive 和 Clean Session。

连接成功后，就可以在中间的主题操作区进行订阅和发布。右侧是接收信息区域，用来查看连接日志、订阅消息和错误提示。

MQTT 调试时，连接参数很关键。客户端 ID 是否重复、用户名密码是否正确、Broker 是否允许匿名登录、KeepAlive 是否合适，都会影响连接结果。把这些参数集中放在界面上，现场排查会更直接。

---

主题订阅：先看设备有没有正常上报

MQTT 的核心是 Topic。

比如一个设备可能把状态发布到：

factory/line1/device001/status

把温度发布到：

factory/line1/device001/temperature

把告警发布到：

factory/line1/device001/alarm

在调试设备时，最常见的第一步就是订阅对应 Topic，看设备有没有正常上线、有没有持续上报数据、消息格式是否符合协议文档。

软件里输入订阅主题后，点击订阅即可开始接收消息。取消订阅也可以直接在界面上完成，适合反复切换不同设备、不同数据点进行测试。

---

发布消息：模拟平台下发控制命令

MQTT 不只是接收设备数据，也经常用于下发控制命令。

例如平台可能向设备发布：

factory/line1/device001/cmd

消息内容可能是 JSON：

{
  "action": "start",
  "speed": 1200
}

也可能是简单文本：

reset

在软件里填写发布主题和消息内容后，点击发布即可发送到 Broker。这样可以在没有完整平台的情况下，先模拟业务系统给设备下发命令。

当前工具也支持 Retain 标志。调试配置类消息时，Retain 很有用，因为 Broker 可以保留最后一条消息，后续客户端订阅后能立即收到当前配置状态。

---

多客户端窗口：本机也能做简单联调

这里预留一张多客户端联调截图。

MQTT 调试经常需要两个角色：一个模拟设备，一个模拟平台。

所以软件增加了“新建客户端”按钮，可以再打开一个 MQTT 客户端窗口。一个窗口负责订阅，另一个窗口负责发布，就可以在本机完成简单联调。

这个功能适合验证 Topic 是否写对、消息是否能正常到达、Retain 是否生效，以及 Broker 的连接策略是否符合预期。

---

为什么适合 Qt 初学者练手？

这个项目不算大，但很贴近工业联网调试场景。

它覆盖了这些知识点：

Qt MQTT 做 MQTT 客户端通信；
QMqttClient 处理连接、订阅、发布和消息接收；
Qt Widgets 做参数界面和日志显示；
信号槽处理异步连接状态和消息回调；
CMake 构建 Qt 6 项目；
最后还可以练习程序打包发布。

它比单纯写按钮、弹窗、计算器更接近实际工作。做完之后，不只是多了一个 Demo，而是得到一个可以直接拿来测试 MQTT Broker、设备 Topic 和消息内容的小工具。

当前版本主要覆盖 MQTT 3.1.1、QoS 0 的常用调试场景。后续还可以继续扩展，比如 QoS 1/2、TLS 加密连接、遗嘱消息、自动重连、消息模板、JSON 格式化、历史记录保存等。

---

如果你正在学 Qt，并且想往工业软件、物联网设备调试或上位机方向走，MQTT 调试助手是一个很值得做的练手项目。

它不复杂，但足够实用。能连 Broker，能订阅，能发布，能看日志，也能模拟多个客户端联调。对于理解 MQTT 通信流程和 Qt 网络类开发，都很有帮助。