Ineed主题、QoS 与消息排查
从连接、订阅和发布三个环节定位问题，理解通配主题、保留消息与 QoS 的作用范围。
继续深入：阅读 MQTT Tool 完整手册 ↗
本页目录
先分清三个状态
「已连接」说明客户端与 broker 建立了连接；「订阅成功」说明订阅请求被接受；看到接收记录才说明对应消息到达了当前客户端。排查时按这个顺序缩小范围。
主题如何匹配
主题区分大小写，由 / 分隔层级。
| 订阅过滤器 | 可以匹配 | 不能匹配 |
|---|---|---|
sensor/room/temperature |
同名完整主题 | sensor/room/humidity |
sensor/+/temperature |
sensor/a/temperature |
sensor/a/floor/temperature |
sensor/# |
sensor/a/temperature |
device/a/temperature |
+ 匹配一个层级，# 匹配后续多个层级且应位于末尾。通配符用于订阅过滤器，不用于发布主题。初次排查优先使用同一个完整主题，减少变量。
QoS 不是业务处理成功的回执
QoS 0、1、2 定义 MQTT 协议层的交付语义。最终接收侧 QoS 还受发布与订阅双方设置影响。不要把一次发送成功直接理解为设备已完成业务动作。
涉及控制指令时，业务上应定义对应的结果主题、请求标识和超时处理。使用 QoS 1 时，也应考虑重复交付下的业务幂等。
为什么一订阅就收到旧消息
发布时设置 Retain，broker 可以保留该主题最后一条保留消息，在新的匹配订阅建立时发送它。这不是消息历史查询。
初次验证可将 Retain 设为「否」。如果测试 broker 已有保留消息，检查其主题和时间，再确认是不是本轮发送的内容。清理保留消息前，应确认这个主题完全属于自己的测试环境。
常见现象与检查顺序
| 现象 | 优先检查 |
|---|---|
| 连接失败 | broker 是否运行、地址端口、协议、认证、网络可达性 |
| 连接反复断开 | 重复 Client ID、broker 限制、连接日志 |
| 有发送记录，没有接收记录 | 订阅是否成功、主题匹配、发布与订阅权限 |
| JSON 看起来乱码 | 原文与 HEX 发送方式、设备采用的实际编码 |
| 历史数据与当前页面不同 | 当前连接、筛选条件、接收/发送筛选和查询时间 |
提供一份可复现的问题描述
记录客户端版本、broker 类型与版本、连接协议、订阅过滤器、实际发布主题，以及一段脱敏载荷。附上期望结果、实际结果和对应时间段的日志。
不要提供真实密码或完整生产消息。可以回到第一条消息的固定示例，判断问题是否与业务载荷有关。