单片机与物联网 / 系统课时
用 WebSocket 接入浏览器
用 WebSocket 接入浏览器
浏览器不能像 Node.js 服务端一样直接连接 MQTT 的原生 TCP 端口。本篇在 Mosquitto 上开启 WebSocket 监听,再用 Vite 和 MQTT.js 做一个浏览器页面,完成设备消息的订阅、显示和发布,并验证部署时的连接边界。
学习目标
- 区分 MQTT/TCP 与 MQTT over WebSocket 的连接入口。
- 配置 Mosquitto WebSocket 监听,实现浏览器订阅与发布。
- 排查协议地址、HTTPS 混合内容和生产环境鉴权问题。
区分传输与 MQTT 消息
原生客户端可以通过 mqtt://127.0.0.1:1883 建立 TCP 连接;浏览器只能用 ws:// 或 wss:// 建立 WebSocket 连接。本例让同一个 Broker 同时监听 1883 和 9001,两个入口共享主题与订阅路由,但不能把 ws:// 直接指向只支持 MQTT/TCP 的端口。

WebSocket 的 HTTP Upgrade 只负责建立承载通道,连接成功后传输的仍是 MQTT CONNECT、SUBSCRIBE 和 PUBLISH 报文,并非把 MQTT 改成普通 HTTP 接口。不同 Broker 的 WebSocket 端口和 URL 路径可能不同,应以部署配置为准。
给 Mosquitto 配置双监听
准备支持 WebSockets 的 Mosquitto 以及 Node.js 20.19+ 或 22.12+。新建 mosquitto-ws.conf,下面只绑定本机回环地址,允许匿名连接仅供本地验证:
listener 1883 127.0.0.1
protocol mqtt
listener 9001 127.0.0.1
protocol websockets
allow_anonymous true预期生效行为:1883 接受原生 MQTT,9001 接受 MQTT over WebSocket;两者属于同一 Broker。allow_anonymous true 是本机演示配置,不得原样暴露到公网。
确保没有其他 Mosquitto 实例占用端口,然后运行:
mosquitto -c ./mosquitto-ws.conf -v预期结果:Broker 成功启动并建立两个监听。如果日志提示 WebSocket 不受支持,检查 Mosquitto 是否构建了 WebSockets 功能;如提示地址已被使用,先检查现有进程或更换监听端口。
创建网页并接入 MQTT.js
在另一个终端建立 Vite 原生 JavaScript 项目,安装 MQTT.js:
npm create vite@latest mqtt-browser -- --template vanilla
cd mqtt-browser
npm install
npm install mqtt@^5预期结果:项目内有 index.html、src/main.js 和已安装的 mqtt 依赖。把 index.html 替换为下列页面,按钮先禁用,防止未订阅就发送测试数据:
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MQTT 浏览器演示</title>
</head>
<body>
<h1>设备遥测</h1>
<p id="status">正在连接</p>
<button id="send" disabled>发送测试温度</button>
<pre id="messages">尚无消息</pre>
<script type="module" src="/src/main.js"></script>
</body>
</html>预期结果:页面具备连接状态、测试按钮和消息区域;脚本成功加载前按钮不可点击。将 src/main.js 替换为:
import mqtt from 'mqtt';
const topic = 'factory/line1/device/t01/telemetry';
const status = document.querySelector('#status');
const send = document.querySelector('#send');
const messages = document.querySelector('#messages');
const client = mqtt.connect('ws://127.0.0.1:9001', {
clientId: `web-dashboard-${Math.random().toString(16).slice(2)}`,
protocolVersion: 4,
clean: true,
reconnectPeriod: 2000,
resubscribe: false
});
client.on('connect', () => {
status.textContent = '已连接,订阅中';
// 网页使用临时会话,每次连接都重新订阅
client.subscribe(topic, { qos: 1 }, (err, granted) => {
if (err || !granted?.length || granted[0].qos === 128) {
status.textContent = `订阅失败:${err?.message ?? 'Broker 拒绝'}`;
return;
}
status.textContent = '已订阅';
send.disabled = false;
});
});
client.on('message', (receivedTopic, bytes) => {
if (receivedTopic !== topic) return;
// 设备负载按文本显示,避免作为 HTML 执行
messages.textContent = `${receivedTopic}: ${bytes.toString()}\n${messages.textContent}`;
});
client.on('offline', () => {
status.textContent = '离线,正在重连';
send.disabled = true;
});
client.on('error', (err) => {
status.textContent = `连接错误:${err.message}`;
send.disabled = true;
});
send.addEventListener('click', () => {
const payload = JSON.stringify({ temperature: 23.6, status: 'ok' });
client.publish(topic, payload, { qos: 1 }, (err) => {
if (err) status.textContent = `发布失败:${err.message}`;
});
});预期页面效果:订阅成功后状态显示“已订阅”,按钮可点击;点击后发布一条温度消息,并在消息区域显示自己从 Broker 收到的同主题负载。textContent 不会执行设备消息里的 HTML。
运行并跨传输验证
在网页项目目录启动开发服务器:
npm run dev预期结果:终端显示 Local: http://localhost:<PORT>/,其中 <PORT> 为实际开发端口,通常是 5173。打开该地址,确认状态变为“已订阅”,点击按钮应显示温度 23.6。
再从另一个终端经原生 TCP 发布同一主题,检验 WebSocket 订阅者能否收到:
mosquitto_pub -h 127.0.0.1 -p 1883 -q 1 -t factory/line1/device/t01/telemetry -m '{"temperature":25.4,"status":"ok"}'预期结果:命令正常退出且通常没有控制台输出;网页消息区新增包含 "temperature":25.4 的 JSON。这说明 TCP 发布与 WebSocket 订阅经过同一 Broker 的主题路由。
处理实际部署中的连接限制
使用 HTTPS 打开的网页应连接 wss://,否则普通 ws:// 通常会被浏览器作为混合内容阻止。生产环境一般由反向代理终止 TLS,并正确转发 WebSocket Upgrade;反向代理的路径、证书域名与 Broker 监听端口必须对应。示例中的 127.0.0.1 指浏览器所在的计算机,其他用户设备不能用它访问服务器上的 Broker。
遇到持续重连时,先在浏览器开发者工具的 Network 中检查 WebSocket 握手是否成功,再检查 Broker 是否支持 WebSockets、代理是否传递 Upgrade,以及 MQTT CONNECT 是否被认证或 ACL 拒绝。握手成功只说明传输通道建立,界面显示“已订阅”才代表业务主题订阅成功。