MQTT 问题排查工具使用教程

[English]

本文将介绍如何借助本地 MQTT 测试工具、调试日志（Debug Log）和无线抓包等方法，对 MQTT 问题进行排查与定位。

概述

MQTT 是一种轻量级消息传输协议，基于发布/订阅（Publish/Subscribe）模式，适用于物联网和低带宽网络环境。进一步介绍以及相关示例可参考 MQTT 示例。

在实际开发中，开发者在使用 MQTT 时可能会遇到各种异常或故障，例如连接异常、消息丢失或订阅失败等。

当程序出现异常时，可先观察 WARN/ERROR 日志，快速定位异常发生的大致环节：

  • 如果日志中打印了如下 TLS 错误码，可通过查看 报错排查 文档查找对应原因和可能的解决办法。也可通过 ESP TLS 返回值 查找错误码对应的错误原因。

    E (15139) mqtt_example: Last error reported from esp-tls: 0x8006

  • 如果异常发生在 连接建立或订阅环节，可先使用 本地 MQTT 测试工具 排查服务器环境问题。

  • 如果 MQTT 服务器连接失败，可 获取具体的错误原因。

如果以上方法均无法定位问题，并且服务器和网络环境已确认正常，可根据实际情况选择开启更详细日志（MQTT Debug Log）或使用 无线抓包 进行进一步排查。

MQTT Debug Log

MQTT 设备端日志

在排查 MQTT 问题时，设备端日志可以查看程序内部状态，是分析连接与收发流程的主要信息来源。

在默认配置下，设备端日志只输出基础流程信息，例如连接成功/失败、消息发送或接收是否成功等，用于确认核心步骤是否执行，但不会展示更细分的内部状态。因此，在某些排查阶段，需要根据情况 调整日志等级 以获取更多细节。

日志库共有六个详细程度级别，具体请参考 日志级别。

MQTT 可简单分为以下几个层级：

  • 应用层：生成和处理 MQTT 消息，执行业务逻辑。

  • TLS 层：负责 TLS 握手、证书校验以及数据的加密与解密，为上层提供安全的通信通道。

  • lwIP 层：负责 TCP/IP 封装、网络传输和连接管理。

  • Wi-Fi 层：负责无线连接和物理数据收发，是最底层的网络接口。

应用层关注 MQTT 消息和业务，TLS 层关注数据安全，lwIP 层关注网络传输，Wi-Fi 层关注无线收发，日志从下到上逐层提供调试信息。

不同层级的日志信息侧重点不同，Debug Log 的开启方法也不同，具体说明如下。

修改最大日志等级

全局最大日志等级决定了日志输出的上限，默认为 INFO 级别，若需要查看 DEBUG 或 VERBOSE 级别的调试日志，必须首先将全局最大日志等级提升。否则即使单独模块设置为 DEBUG 或 VERBOSE 级别，也无法打印 DEBUG 或 VERBOSE 级别日志。

修改最大日志等级方法如下：

  • 进入 menuconfig 后依次选择 Component config > Log > Log Level > Maximum log verbosity，勾选 DEBUG 选项后保存配置。

应用层 Debug Log 开启步骤

在排查 MQTT 应用问题时，应用层日志是分析客户端状态和消息收发流程的重要信息来源。开启应用层 Debug Log 的步骤如下：

  1. 修改最大日志等级 至 DEBUG。

  2. 动态修改模块的日志等级：可以通过在代码中调用 esp_log_level_set() 动态修改指定模块的日志等级，该 API 使用说明请参考 日志级别控制。建议的修改步骤如下：

esp_log_level_set("mqtt_client", ESP_LOG_DEBUG);    // 修改 mqtt_client 模块日志等级至 DEBUG
esp_log_level_set("mqtt_client", ESP_LOG_VERBOSE);  // 修改 mqtt_client 模块日志等级至 VERBOSE

备注

  • 为防止日志量过大，建议将需要调试的关键模块设置为 DEBUG，既能输出关键日志，又可以控制整体日志量。

  • 尽量避免同时将所有模块的日志级别设置为 DEBUG 或 VERBOSE。

MQTT 设备端相关日志主要包含以下模块（参考自 mqtt_tcp 示例）：

  • mqtt_client：处理 MQTT 协议流程，包括 CONNECT、SUBSCRIBE、PUBLISH、ACK 等，用于排查连接异常或消息收发异常。

  • mqtt_example：业务逻辑层日志，观察 MQTT API 调用执行情况，用于排查业务逻辑调用异常。

  • transport_base：底层 TCP/TLS 传输封装基础模块，用于排查 TCP 连接失败或网络传输异常。

  • transport：传输层报文发送/接收及状态管理，用于排查报文发送失败、ACK 丢失或消息重试异常。

  • esp-tls：TLS 握手、证书加载与验证，用于排查 TLS 握手失败、证书验证失败或加密套件不匹配。

  • outbox：MQTT 客户端内部消息队列及 QoS1/QoS2 重试机制，用于排查消息未发送、队列阻塞或重试失败。

TLS 层 Debug Log 开启步骤

在 ESP-IDF 中，TLS 协议由 mbedTLS 库实现。开启 TLS 层 Debug Log 的步骤如下：

  1. 修改最大日志等级 至 DEBUG。

  2. 进入 menuconfig 后依次选择 Component config > mbedTLS，按空格开启 Enable mbedTLS debugging

  1. 开启日志后可通过 Set mbedTLS debugging level 修改日志级别:

  • 该日志默认级别为 VERBOSE，建议修改至 DEBUG 级别，以控制日志量。

lwIP 层 Debug Log 开启步骤

开启 lwIP 层 Debug Log 的步骤如下：

  1. 修改最大日志等级 至 DEBUG。

  2. 进入 menuconfig 后依次选择 Component config > LWIP，按空格开启 Enable LWIP Debug

  1. 按回车进入 Enable LWIP Debug 页面，按需开启对应的子模块日志，子模块包括 netif、pbuf、etharp、api lib、socket、IP、ICMP、DHCP、IP6、ICMP6、TCP、UDP、SNTP、DNS、bridge generic、bridge FDB、bridge forwarding。

有关启用 lwIP 层调试日志的进一步说明可参考此 ESP-FAQ。

Wi-Fi 层 Debug Log 开启步骤

在 ESP-IDF 中，Wi-Fi 连接相关日志主要分布在 wifi 和 wpa 模块中，分别对应 链路管理 和 无线安全认证。开启 Wi-Fi 层 Debug Log 的步骤如下：

  1. 修改最大日志等级 至 DEBUG。

  2. 查看 wifi 模块调试日志：wifi 模块日志默认开启，可以通过在代码中调用 esp_log_level_set() 修改其日志等级至 DEBUG，该 API 使用说明请参考 日志级别控制。建议的修改步骤如下：

esp_log_level_set("wifi", ESP_LOG_DEBUG);

  1. 查看 wpa 模块调试日志：wpa 模块日志默认关闭，开启步骤如下。

  • 进入 menuconfig 后依次选择 Component config > Wi-Fi，按空格开启 Print debug messages from WPA Supplicant。

  • 在代码中调用 esp_log_level_set() 修改其日志等级至 DEBUG，该 API 使用说明请参考 日志级别控制。建议的修改步骤如下：

esp_log_level_set("wpa", ESP_LOG_DEBUG);

本地 MQTT 测试工具

测试工具使用场景

MQTT 测试工具主要作为 客户端，独立于设备端运行，可用于快速确认 MQTT 服务器及网络环境是否正常，从而辅助问题排查，减少因环境异常导致的误判或重复调试：

  • 如果测试工具无法连接目标 URI，问题通常出在环境或服务器端。

  • 如果测试工具连接正常，问题通常出在设备端代码。

对于确认为设备端的问题，需要进一步结合 MQTT Debug Log 或 无线抓包 分析，排查设备端的配置与业务逻辑问题。

此外，部分 MQTT 测试工具可作为 服务器 使用，用于在没有可用 Broker 的情况下（如离线环境、实验环境或自动化测试脚本中）快速搭建临时 MQTT 服务。对于线上或已有开发环境的 Broker，通常无需使用服务器模式。

常用测试工具

在 MQTT 开发和调试中，本地测试工具主要用于验证客户端与 Broker 的连接、调试消息收发、检查主题和 QoS 配置，以及模拟客户端行为。这类工具可以快速帮助开发者确认消息交互是否正常，同时支持多客户端场景和批量消息测试。

常见的本地测试工具可分为两类：图形化界面（GUI）工具和命令行界面（CLI）工具。

  • GUI 工具 提供可视化操作，可以直观查看主题结构、消息流向，以及 Retain 或 Will 消息状态，适合快速验证连接和观察消息行为。

  • CLI 工具 通过命令或脚本操作，更适合批量消息发布、自动化测试，或在无图形界面的环境中使用。

在实际开发中，GUI 工具通常用于快速调试和观察消息，而 CLI 工具更适合脚本化操作、持续集成或大规模消息验证。

常用的本地 MQTT 测试工具包括：

  • MQTTX：同时提供 GUI 和 CLI 版本。GUI 可直观显示主题树和消息流向，并支持 JSON 格式化，便于快速调试和观察消息；CLI 适合脚本化批量消息发布和自动化测试，是开发阶段的综合调试工具。

  • MQTT Explorer：以可视化主题树和历史消息管理为特点，尤其适合处理复杂主题结构和 Retain 消息，帮助开发者快速定位问题。

  • Mosquitto：轻量、简单的 MQTT Broker 和命令行客户端工具。通过 mosquitto_pub 和 mosquitto_sub 命令可以发布和订阅消息，适合自动化测试、批量消息验证或在无 GUI 环境中使用。

备注

MQTTX 和 MQTT Explorer 仅支持客户端模式；Mosquitto 则可用作客户端或服务器（Broker）。

测试工具使用说明

无线抓包

无线抓包能够直接展示真实网络报文，主要用于排查 网络层或传输层 异常，例如发送数据超时，读数据超时等，用于确认设备与 Broker 之间的底层链路是否稳定可靠。

进入抓包阶段前，需先完成以下前置验证，避免无效抓包：

  • 使用 MQTT 测试工具 确认 Broker 服务正常、网络链路可达、端口 / 防火墙配置有效、TLS 认证参数兼容

  • 使用 Debug Log 确认连接参数（Client ID、Topic、QoS 等）配置正确、证书加载正常、SDK 连接流程无明确错误码或异常日志

当测试工具运行正常、Debug Log 未发现明确问题，但仍存在连接不稳定、消息丢包、频繁断连等现象时，需通过抓包进一步定位。

无线抓包步骤可参考 无线抓包教程