MQTT over WebSocket 客户端
通过 WebSocket 连接 MQTT broker,订阅和发布文本或二进制消息,支持 MQTT 3.1.1 与 5.0。
连接、订阅和发布会直接与指定 broker 通信。
使用 MQTT WebSocket 监听端点
请输入带 WebSocket 路径的 ws:// 或 wss:// broker 地址。1883 等原生 MQTT TCP 端口不能直接作为浏览器 WebSocket 端点。本工具使用 MQTT.js 5.16.1 和 MQTT 协议,不是原始 WebSocket 回显格式。示例只填入演示地址与主题,不会自动连接或订阅。
选择 MQTT 3.1.1 或 5.0,设置 broker 凭据及客户端 ID。清理会话时,留空 ID 会用浏览器密码学随机源生成新的 23 位字母数字 ID。持久会话需显式 ID;另一个使用相同 ID 的客户端可能挤掉当前连接。安全页面通常需要 WSS,仍受服务器 Origin 检查、TLS 和浏览器策略约束。没有服务端代理或原生 TCP 传输。
订阅、发布与确认
订阅过滤器的 + 占一个完整主题层级,# 需占最后完整层级;允许空层级。共享过滤器使用 $share/group/filter,需 broker 支持。首层通配符不会自动选择 $SYS 主题。发布主题不能包含通配符。
选择请求的订阅 QoS,再查看实际 SUBACK 授权。发布 QoS 0 在套接字写入后完成,QoS 1 等待 PUBACK,QoS 2 等待 PUBCOMP。这些是协议完成状态,不代表订阅应用已处理消息。入站记录保留主题、消息 QoS、retain/dup 标记、准确十六进制字节,以及有效时的 UTF-8 文本。
文本按 UTF-8 编码,十六进制接受完整字节对与空白分隔,支持空正文。保留发布会替换 broker 存储值,空的保留消息可删除该保留值。取消订阅在 broker 确认后移除过滤器,不会清除 broker 的保留数据。
会话与连接清理
清理选项在 3.1.1 中表示 Clean Session,在 5.0 中表示 Clean Start。MQTT 5 会话过期可设 0–86,400 秒,3.1.1 不支持该字段。Session Present 来自 CONNACK。本工具只使用内存存储,清除、重新打开页面或创建新客户端后不会恢复未完成的 QoS 事务;broker 持久会话本身不能保证无损恢复。
不自动重连、恢复订阅或排队离线 QoS 0 消息,新连接需手动发起。连接超时覆盖 CONNACK 握手,操作超时覆盖发布/订阅/取消订阅回调,均为 1–30 秒。操作超时会停止连接,避免操作一直处于未决状态;超时前 broker 可能已执行操作。
断开会请求 MQTT DISCONNECT,最多等待两秒后强制清理。修改连接设置或清除会停止旧客户端并忽略迟到回调;修改主题或正文保留连接。离开页面会清理资源,不将凭据、会话或日志写入浏览器存储。不提供遗嘱消息设置及全部 MQTT 5 高级属性。
上限与导出
最多跟踪 32 个订阅过滤器、等待 20 个操作,消息正文限 256 KiB。客户端 ID 限 128 UTF-8 字节;MQTT 文本字段拒绝控制字符、NUL、代理项和非字符码点。用户名与密码需符合协议字节上限。Keepalive 可设 0–300 秒,0 表示不启用协议保活。
日志最多保留 1,000 条或 2 MiB 的紧凑事件 JSON,达到上限会断开。MQTT 库及浏览器可能先收到数据,再执行应用层正文检查;MQTT 5 还声明 1 MiB 最大数据包。本工具用于手动调试,不用于压力测试。
预览只显示前 200,000 字符,复制与下载保留完整的有界日志。连接记录不包含用户名或密码,但 broker 错误、主题和正文仍可能含私密信息。JavaScript 不能绕过 broker 的认证或授权。
常见问题
可以连接 mqtt:// 或普通 WebSocket 回显服务器吗?
不可以。请使用 broker 的 MQTT over WebSocket 监听端点,并设置正确路径、版本与凭据。
QoS 2 是否代表业务操作只执行一次?
不是。它的保证属于参与方之间的 MQTT 协议投递;应用处理、持久恢复和下游系统有各自的行为。
为什么取消订阅后仍可能到一条消息?
已经接收或正在传输的消息可能与确认交错。取消订阅改变 broker 的订阅,不会撤销已经送达的工作。
其他语言
参考资料
我们如何确保结果正确
我们使用以下自动化测试验证此工具。下方保留测试用例的原始名称,便于查看实际断言和复现。
- 验证方法
- 检查 topic、QoS、协议版本和二进制载荷;集成用例连接本地 broker 检查认证、保留消息和会话。
- 对比依据
- Mosquitto 的 WebSocket broker 与固定消息/事件断言。
- 验证范围
- 真实 broker 用例需要 Mosquitto 环境;缺失环境时不能把模拟测试通过当作完整互操作通过。
测试源码与用例(点击文件名查看)
-
mqtt-graphql-tools.test.js
- MQTT strict URL, credentials, protocol, session and time option validation
- MQTT topic filters handle empty levels, shared groups, wildcards and forbidden text
这些测试覆盖列出的样本和边界,不代表所有输入都已证明正确。往返测试和使用同一依赖库的检查,不属于独立交叉验证。