mqtt客户端需手动启动网络循环才能收发消息；qos消息依赖broker持久化和固定client_id；payload始终为bytes类型，需显式解码；认证失败多因凭证设置顺序或tls路径错误。
connect() 调用后没反应？检查 loop_start() 或手动 loop()
MQTT 客户端连接成功不等于消息能收发——connect() 只是发起 TCP 连接并完成协议握手，后续的保活、重连、收包、分发回调全靠网络循环驱动。paho-mqtt 默认不自动启循环，所以常见现象是：日志显示 Connected with result code 0，但 on_message 死活不触发，publish() 也卡住不发。
- 要么在
connect()后立刻调用client.loop_start()（开后台线程，适合长期运行） - 要么在主逻辑里写死循环：
while True: client.loop(); time.sleep(0.1)（适合脚本或调试） - 别用
loop_forever()做主循环——它会阻塞，后续代码不执行，且无法优雅退出 - 如果用
loop_start()，记得程序退出前调client.disconnect()和client.loop_stop()，否则可能残留线程
QoS 1/2 消息发出去就消失？确认 broker 支持且客户端没设 clean_session=False
MQTT 的 QoS 不是“发了就一定到”，它依赖 broker 配置和客户端 session 状态。典型表现：本地 publish(topic, payload, qos=1) 返回正常，但订阅端收不到，broker 日志也没记录。
- 先查 broker 是否启用持久化（如 Mosquitto 需配置
persistence true和autosave_interval） - 如果客户端初始化时传了
clean_session=False，但没指定client_id，paho 会自动生成随机 ID——每次启动都是新 session，broker 丢弃旧队列 - QoS 1 消息在客户端断线重连后，只有
clean_session=False+ 固定client_id才可能被 broker 重发 - Python 客户端默认
clean_session=True，别以为设了 QoS 就自动保消息
收到中文乱码或字节对象？payload 是 bytes，不是 str
MQTT 协议本身不关心 payload 编码，paho-mqtt 一律以 bytes 形式传递。常见错误：直接 print(msg.payload) 看到 b'\xe4\xbd\xa0\xe5\xa5\xbd'，或者 msg.payload.decode('utf-8') 报 UnicodeDecodeError。
-
msg.payload永远是bytes类型，哪怕你 publish 时传的是 str；paho 会自动 encode 成 utf-8，但不会自动 decode - 安全解码方式：
msg.payload.decode('utf-8', errors='ignore')（忽略非法字节）或msg.payload.decode('utf-8', errors='replace')（替换成 ） - 如果 payload 是 JSON，别先 decode 再 json.loads —— 直接
json.loads(msg.payload.decode('utf-8'))，少一层中间变量 - 某些设备（如 ESP32）可能发 GBK 编码，此时需按实际编码 decode，不能硬写 utf-8
频繁断连或 Connection Refused: not authorised？检查 username/password 和 TLS 配置顺序
MQTT 连接失败常被归为“网络问题”，但多数出在认证环节。错误信息如 Connection Refused: not authorised 或静默超时，往往不是防火墙挡的，而是凭证或协议层没对齐。
立即学习“Python免费学习笔记（深入）”；
-
username和password必须在connect()前调用username_pw_set()设置，不能只传进 connect 参数里（paho 旧版本会忽略） - 用 TLS 时，必须在
connect()前调tls_set()，且路径要写绝对路径（ca_certs="/etc/mosquitto/ca.crt"），相对路径容易静默失败 - Mosquitto 默认禁用匿名登录，如果没配
allow_anonymous false却又没设账号，就会拒绝所有连接 - 某些云 MQTT 服务（如阿里云 IoT）要求 client_id 包含设备三元组，格式不对也会返回授权失败
