本文档基于实际调试经验，总结了在 EdgeLink Studio 中配置 SimpleMQTT 服务连接至 EMQX 的核心要点，可供后续参考和维护。
一、基础连接参数配置
| 配置项 | 推荐值 / 注意事项 |
|---|
| 启用此连接 | 必须勾选 |
| 主机 (Host) | 填写 EMQX 服务器的公网 IP 或域名 |
| 端口号 | MQTT 默认明文端口 1883；若启用 SSL 则为 8883 |
| MQTT 版本号 | 选择 3.1.1（与 EMQX 5.x 完全兼容） |
| 客户端标识符 | 必须唯一，建议使用有意义的 ID 如 ECU1051_001 |
| 用户名 / 密码 | 填写在 EMQX Dashboard 中已创建的认证凭据 |
| 保持连接/重连间隔 | 可使用默认值 (60/60) |
| 启用 SSL | 如未配置证书，保持不勾选 |
二、主题（Topic）命名规范
| 主题类型 | 配置项 | 推荐格式 | 说明 |
|---|
| Data Topic | 数据上报主题 | data/<设备标识> （如 data/test） | 设备发布实时数据的主题 |
| Command Topic | 命令接收主题 | cmd/<设备标识> （如 cmd/test） | 服务器向该主题下发 JSON 指令 |
| Resume Topic | 断点续传主题 | 若不使用则留空 | 用于离线重传历史数据 |
重要：主题中建议不要使用特殊字符或变量，保持清晰、可读性强。
三、Tag 点列表配置（极易出错）
| 规则 | 说明 |
|---|
| Tag 名称 | 只允许 字母、数字、下划线，不能包含中文、冒号、空格等 |
| 别名 | 可以包含中文，仅用于界面显示 |
| 点类型 | 必须正确选择（analog / digital 等） |
| 错误排查 | 若保存提示“页面中有输入错误”，先检查 Tag 名称是否合规 |
典型错误：1test:新点（数字开头 + 中文 + 冒号）→ 应改为 test_point_1
四、发布参数优化建议
| 参数 | 推荐值 | 理由 |
|---|
| QoS | 1 | 保证消息至少送达一次，开销适中 |
| Payload Type | Simple | 默认 JSON 格式，含 d 数组和 ts 时间戳 |
| Timestamp | UTC Time (ISO-8601) | 避免时区混淆 |
| 定期上传 | 启用，周期 ≥ 1s | 保证数据持续上报 |
| 变化上传 | 按需启用 | 可减少带宽，但需正确设置阈值 |
五、常见错误及解决方法
| 错误现象 | 可能原因 | 解决方案 |
|---|
| 保存时提示“页面中有输入错误” | Tag 点名称含非法字符 | 修改 Tag 名为纯英文/数字/下划线 |
| 连接失败 | 用户名/密码错误 | 检查 EMQX Dashboard 中的认证配置 |
| 连接成功但收不到数据 | Data Topic 订阅错误 | 确认客户端订阅的主题与发布的 Topic 完全一致 |
| 设备频繁掉线 | Client ID 冲突 | 确保 Client ID 唯一 |
六、快速验证链路
- 服务器端命令行订阅：bashmosquitto_sub -h <服务器IP> -p 1883 -u <用户名> -P <密码> -t “data/test” -v
- EMQX Dashboard：使用 WebSocket 客户端（端口
8083）订阅主题观察消息。
- 第三方工具：使用 MQTTX 等工具连接并订阅，验证数据流。
