简而言之，MQTT 是一种面向低带宽、低功耗场景的消息协议。它采用发布/订阅模式：客户端只要订阅了某个主题，当任意设备向该主题发布消息时所有订阅者dou会收到。

它自带心跳检测和自动重连机制，这让我们在移动端使用时几乎不必再写额外的保活代码。

打开终端，在 uni‑app 项目的根目录执行：

# 推荐使用 mqtt@4.x 系列
npm i mqtt@4.1.0
npm i uuid

为什么坚持 4.1.0？因为我亲测，这个版本在 H5 与 APP‑PLUS 环境下几乎没有报错；而新版 5.x 在小程序里会出现 API 改动导致的异常。Ru果你想挑战Zui新功Neng，请自行评估。

创建文件 /utils/mqttClient.js，把所有连接配置、事件监听以及发布/订阅逻辑集中起来。这样即使以后需要切换 broker，只要改动这一个文件即可。

// utils/mqttClient.js
import { v4 as uuidv4 } from 'uuid';
const mqtt = require; // 小程序必须走 min 包
let client = null;
/**
 * 初始化连接
 * @param {Object} opts
 *   host      - 不带协议头的服务器地址，例如 broker.emqx.io
 *   port      - WebSocket 端口
 *   clientId  - 唯一标识，可使用 uuid
 *   username / password - 如有鉴权请填写
 *   secure    - 是否走 wss / wxs
 */
export function initMqtt {
    const {
        host,
        port,
        clientId = uuidv4,
        username = '',
        password = '',
        secure = false,
    } = opts;
    // 根据运行平台挑选协议前缀
    let proto = 'ws';
    // #ifdef MP-WEIXIN
    proto = secure ? 'wxs' : 'wxs';
    // #endif
    // #ifdef APP-PLUS || H5
    proto = secure ? 'wss' : 'ws';
    // #endif
    const url = `${proto}://${host}:${port}/mqtt`;
    const connectOpts = {
        clientId,
        username,
        password,
        keepalive: 10,
        reconnectPeriod: 2000,
        clean: true,
        connectTimeout: 6000,
    };
    client = mqtt.connect;
    client.on => console.log);
    client.on => console.warn);
    client.on);
    client.on => console.log);
    return client;
}
/**
 * 订阅指定主题并绑定回调
 */
export function subscribe {
    if  return console.warn;
    client.subscribe(topic, err => {
        if  return console.error;
        console.log;
    });
    // 全局监听消息，再交给业务层过滤
    client.on => {
        if  {
            try {
                const data = JSON.parse);
                cb;
            } catch  {
                cb);
            }
        }
    });
}
/**
 * 向某主题发送信息
 */
export function publish {
    if  return console.warn;
    const payload = typeof msg === 'object' ? JSON.stringify : String;
    client.publish(topic, payload, { qos: 0 }, err => {
        err ? console.error
            : console.log;
    });
}
/**
 * 手动断开链接
 */
export function disconnect {
    if  {
        client.end;
        client = null;
        console.log;
}
}

这段代码Yi经兼容了三大运行环境：

#ifdef MP-WEIXIN微信小程序走 wxs://

#ifdef APP-PLUS原生 App 使用 ws:///wss://

#ifdef H5网页同样采用 WebSocket 协议。

下面展示如何在一个普通页面里完成「连接 → 订阅 → 发布 → 断开」的完整闭环：

// pages/index/index.vue

关键点说明：

clientId 使用 UUID 前缀保证唯一性。

subscribe 回调里直接往数组头部 push，让Zui新消息显示在Zui上方。

页面销毁前务必调用 disconnect，否则后台仍会保持长链接，占用系统资源。

Ru果你kan到类似 “Cannot find module …” 的报错，大概率是因为 npm 安装的是完整版而不是 min 包。解决办法hen直接：删掉 node_modules 后重新执行上面的安装命令，并确保引用路径写成 'mqtt/dist/mqtt.min.js'.

AWS 或者自建 broker 有时候只开放 wss端口。Ru果你的浏览器控制台提示 handshake error，请把 {secure:true} 并把端口改为对应的 wss。别忘了服务器也要打开对应证书。

MQTT 默认会发送心跳包，Ru果服务端把 keepalive 时间设得太短，而客户端却用了默认值，就会被服务器认定为不活跃而踢掉。Ke以适当调高 {keepalive:30}.

- 检查 topic 拼写是否完全匹配。 - 若使用通配符，请确认 broker 支持，如 + 表示单层通配，# 表示多层通配。 - 有时候消息是二进制，需要自行 decode 为字符串或 JSON。

Apollo 或者 Chrome DevTools 的 Network 面板Ke以实时kan到 WebSocket 帧。打开「Preserve log」后即使页面刷新也Neng追踪到握手过程，这对定位「为什么没收到」非常有帮助。