Paho.MQTT.JS 从零接入：浏览器 5 分钟连上 MQTT Broker
项目地址: https://gitcode.com/gh_mirrors/pa/paho.mqtt.javascript 想象一下你正在写的那个监控大屏：设备数据正源源不断地流进 MQTT Broker，而浏览器端需要实时收下它们，还要能把控制指令发回去。Paho.MQTT.JS 就是一个浏览器端 MQTT 客户端，基于 WebSocket 通信，几十行代码就能让网页和 Broker 直接对话。
它是什么，凭什么选它
简单来说，它是 Eclipse Paho 项目出品的纯 JavaScript 单文件库，专门解决 MQTT 浏览器端连接这个难题：页面通过 WebSocket 握手，剩下的 QoS、会话、遗嘱这些 MQTT 语义全部由库帮你处理。你可以把它理解成浏览器里的"MQTT 网卡驱动"。
和偏重 Node.js 环境、需要先打包再用的同类库不同，Paho.MQTT.JS 的设计目标就是"拷一个文件进来就能跑"，一个 <script> 标签搞定引入，特别适合没有构建链路的传统前端项目，也方便嵌进各种工具页和演示页。
5 分钟跑通第一个 Demo
先把仓库里的 src/paho-mqtt.js 拷到你的项目目录，在 HTML 里用 <script src="paho-mqtt.js"></script> 引入。然后假设你的 Broker 已开启 WebSocket 监听（mosquitto 加一行 listener 配置即可），地址为 ws://localhost:8083/mqtt：
var client = new Paho.Client("localhost", 8083, "/mqtt", "web-client-1");
client.onMessageArrived = function(m) {
console.log(m.destinationName, m.payloadString);
};
client.connect({
onSuccess: function() {
client.subscribe("World");
var msg = new Paho.Message("Hello");
msg.destinationName = "World";
client.send(msg);
}
});
跑起来后打开浏览器控制台，你应该能看到一行 World Hello——刚发出的消息经 Broker 转发、又回到订阅它的同一个客户端。再开一个浏览器页面用同样的代码，两个页面从此互通。
三个真实场景的落地姿势
设备数据上报：用通配符一次订完
监控场景下，主题按 sensor/{设备号}/data 规划，订阅时直接写 client.subscribe("sensor/#")，一次订下所有设备。回调里的 message.qos、message.retained 字段都有，做状态面板时能直接用。这里有个容易忽略的点：连接后立刻收到的一条"陌生"消息，很可能是 Broker 里的保留消息（retained），处理前先判断 message.retained，别把它当成新数据入库。
断线自动恢复：让页面比网络更皮实
标准的 MQTT 断线重连方案就藏在 connect 选项里：reconnect: true 开启后，库会按指数退避自动重建连接，你只需监听 onConnected 回调感知恢复时机；keepAliveInterval: 30 让死连接更快被发现；disconnectedBufferSize（默认 5000 条）会把断线期间 send 的消息先在本地缓存。最容易踩的坑是订阅丢失：库只在 cleanSession: false 时自动重订旧主题，默认值 true 会清空会话，这时得自己在 onConnected 里补一遍订阅，或者给 clientId 固定下来并改 cleanSession: false。
远程控制指令下发：知道消息到底没到
控制类业务要的是确定性，client.send(message) 配合选项里的 onSuccess / onFailure 回调，就能确认 QoS 1 消息的投递结果，建议把指令主题规划成 device/{id}/cmd 便于隔离。这里最容易忽略的点：前端代码里的 userName / password 是明文可见的，生产环境要么 useSSL: true 走 wss，要么干脆把鉴权挪到后端网关，让页面拿短期凭证换长连接。
上手前必知的 3 个坑
1. 连接一直失败，onFail 被触发。 浏览器不会说纯 TCP，1883 端口从页面里根本够不着，Broker 必须额外暴露 WebSocket 监听（常见是 8083），构造器里第三个参数 path 默认是 /mqtt，别忘了和 Broker 端对齐。
2. Paho.MQTT.Client 是 undefined。 1.1.0 起命名空间从 Paho.MQTT 简化成了 Paho，很多老教程还在写旧名字，全局把 Paho.MQTT. 替换成 Paho. 即可。
3. 断线半天没察觉，还丢了消息。 keepAliveInterval 默认 60 秒，最长要两个周期才探测出断线，把它压到 30 秒以下，并在 onConnectionLost 里同步页面状态，别等用户点按钮才发现问题。
下一步去哪，资源清单
- 克隆仓库（取源码用）
src/paho-mqtt.js（核心库本体，单文件）utility/index.html（带表单的交互式示例页）src/test/（Jasmine 测试用例，照着写自己的）pom.xml（Maven 构建与压缩配置）
把文件拷过来，打开控制台，订阅你的第一个主题，等第一条消息自己走进来。剩下的事，交给你的终端吧。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
