ESP32对接本地MQTT服务的常见问题排查

昨天在嵌入式开源群里蹲了半小时，连着三个刚摸ESP32的朋友卡在上云前的本地MQTT联调步骤，翻了下聊天记录，问来问去就那俩高频问题，干脆整理成可直接照着排查的步骤放这。

大家问得最多的两个问题是：

• 烧录完官方示例代码，ESP32死活连不上本地开的MQTT服务，串口全是connect failed打印
• 串口显示MQTT连接成功，但订阅端等半天收不到任何上报消息

连不上本地MQTT服务的排查步骤

遇到连接失败别上来就换例程、换库版本，按顺序查：

1. 先排除MQTT服务本身的问题，别上来就怪ESP32。同一局域网内找台设备，或者就在跑MQTT broker的电脑上开终端，敲下面的命令测试本地服务是否正常：

   mosquitto_sub -h 你电脑的局域网IP -t test -v

   本地再开个终端发一条测试消息，如果这步都收不到，先去检查系统防火墙有没有放开1883端口，跟ESP32半毛钱关系都没有。
2. 检查代码里填的broker地址，别写127.0.0.1或者localhost，这俩地址指向的是ESP32设备自身，不是你局域网里的电脑，要填跑服务那台机器的局域网IP（就是ipconfig/ifconfig里查到的192.168.x.x段地址）。
3. 如果你用的是3.x版本的ESP32 Arduino核心，WiFi连接成功后别立刻发起MQTT连接，等网络状态稳定个1秒左右再连，不然网卡还没完成初始化，握手包根本发不出去。

要是你自己给Mosquitto开了认证、关了匿名访问，记得代码里要填对应的用户名密码参数，别抄无认证的示例硬连，串口其实会打印未授权的报错，只是很多人扫一眼报错就跳过了。

连接成功但收不到消息的排查步骤

看着串口打印connected但收不到消息，基本都是下面几个小问题：

1. 先核对发布端和订阅端的主题字符串，必须完全一致——大小写、前后有没有多打斜杠，差一个字符都是完全不同的主题，比如发布端写/sensor/temp，订阅端写sensor/temp，永远收不到消息。
2. 如果你用的是最常见的PubSubClient库，它默认的MQTT报文缓冲区只有256字节，要是你拼的JSON上报数据太长，报文会被直接截断，发出去的是无效内容。要改缓冲区大小的话，记得在引入PubSubClient头文件之前加宏定义，顺序错了不生效：

   #define MQTT_MAX_PACKET_SIZE 512
   #include <PubSubClient.h>

3. 别在loop()函数里塞几秒以上的长delay，PubSubClient需要频繁调用client.loop()来维持心跳、处理收发报文，长时间阻塞的话，broker会自动断开连接，串口可能还留着之前打印的连接成功提示，其实链路早就断了。

对了，别没事就升级降级库版本，大部分的联调问题都是抄代码时漏看了参数细节，真跟库的版本关系不大。