MQTT 常见功能问题
这页复用 MQTT 接入常见问题，方便在“快速开始 -> 常见问题”里直接查看。
MQTT 常见问题
1. MQTT 到底该走平台直连，还是自建接入？
先看两件事：
- 设备 Topic 能不能按平台规范改。
- 设备是不是必须连第三方 Broker。
如果 Topic 能改，而且设备愿意直接连平台，就先看 标准topic设备接入。
如果 Topic 改不了，或者设备已经部署在第三方 Broker 上，就直接看 任意Topic接入。
2. 为什么产品详情里会同时看到“平台直连”和“自建接入”？
因为产品详情里的“连接信息”页，本身就支持两种模式：
平台直连自建接入
如果产品已经绑定了可用的 MQTT 网络组件，页面会优先显示 自建接入；否则就回退到 平台直连。
所以这两个不是两种“产品类型”，而是同一个 MQTT 产品的两种接入方式。
3. 任意主题模式下，productKey 和 deviceId 到底怎么认？
这两步不是一回事。
productKey
平台会优先按主题映射去认产品：
- 先看这条
topicPattern有没有显式配置productKey - 如果没配，再尝试从 Topic 模式里自动提取
- 再不行，才回退到标准 Topic 解析
所以第一次联调，我建议直接把 productKey 写在主题映射里。
deviceId
第三方 MQTT / 任意主题模式下，代码里会继续执行 preDecode 去识别 deviceId。
这一步可以从：
- Topic 提取
- payload 提取
- Topic 和 payload 结合提取
不要把“产品认出来了”当成“设备认出来了”
这两步在 MQTT 任意主题模式下是分开的。
4. topicCategory 应该选 THING_MODEL 还是 PASSTHROUGH？
看消息体，不看 Broker。
| 选项 | 什么时候选 |
|---|---|
THING_MODEL | payload 已经是标准物模型 JSON |
PASSTHROUGH | payload 还是私有协议，需要编解码 |
还有一个常见误区：
THING_MODEL只是说明消息体可以直接按 JSON 处理。- 它不代表设备号可以自动识别。
所以在第三方 MQTT 模式下，就算你选了 THING_MODEL，preDecode 也可能仍然要写。
5. 为什么平台有 MQTT 消息，但设备列表里没有设备？
优先排查这几件事：
preDecode没拿到稳定的deviceId- 产品没有开
allowInsert - 主题映射虽然匹配了，但
productKey归错了 - Topic 能进来，但产品详情里没有绑定正确的 MQTT 网络组件
联调阶段最稳的做法是：
- 先把
allowInsert打开 - 先把
productKey在主题映射里写死 - 先让
preDecode稳定返回一个设备号
6. 为什么有设备了，但一直看不到属性或事件？
这时问题一般已经不在连接层了，而在消息处理层。
优先排查：
topicCategory选错了- 物模型模式下，payload 不是标准 JSON
- 透传模式下，
decode返回格式不对 - 属性名、事件名和物模型定义对不上
7. 为什么平台下发了，但设备收不到？
MQTT 下发常见有 4 个原因：
- 设备订阅的 Topic 不是平台实际下发的 Topic
- 产品里配置了
downTopic，但你忘了这一层会覆盖默认主题 - 自建接入场景下，Broker 权限不够，没有发布权限
- 产品编码器不对，设备收到的数据格式不对
最稳的检查顺序是：
- 先看产品端云配置有没有
downTopic - 再看设备实际订阅的是哪条 Topic
- 再看网络组件有没有权限往这条 Topic 发
- 最后再看
encoderType
8. replyPayload 为什么没回，或者回了很多次？
没回
优先看：
decode结果里到底有没有replyPayload- 编码器是否能把
replyPayload编出来 - 最终下发 Topic 是否正确
回了很多次
代码里现在是按 upRequestList 一条一条处理回复的。
也就是说：
- 你返回 1 条带
replyPayload，就回 1 次 - 你返回 10 条都带
replyPayload，就回 10 次
如果你只想回一次，最简单的做法就是只在一条结果上设置 replyPayload。
9. 常见问题速查
| 现象 | 优先排查 |
|---|---|
| 平台直连连不上 | 产品连接信息里的地址、用户名、密码是否正确 |
| 自建接入无消息 | 网络组件是否启动、Topic 是否匹配、Broker ACL 是否正确 |
| 有消息没设备 | preDecode、allowInsert、主题映射里的 productKey |
| 有设备没属性 | topicCategory、物模型字段、decode 返回格式 |
| 下发没效果 | downTopic、订阅 Topic、发布权限、encoderType |
| 自动回复异常 | replyPayload、返回条数、最终下发 Topic |