更新记录

1.5.7（2026-09-07）

• 优化 uni-app x：入口将对象字面量归一化为 Option，业务页可直接传对象调用 API，无需再写 as XxxOption
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 不传参行为与上一版兼容

1.5.6（2026-09-06）

• 修复 Android ByteArray 空判断：size 先 Number.from
• 修复 Android 运行时 ClassCastException：成功回调与 onMessage 结果改为 UTSJSONObject 别名，避免强转为独立 Result 类型
• 修复 onMessage 载荷构造统一为 UTSJSONObject；Android QoS 用 Number.from
• 修复 invoke 回调判空调用；可选 number 去掉 undefined 联合；部分 Android 原生返回值改 Number.from、可变属性局部拷贝
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

1.5.4（2026-09-04）

• 修复 Android 云打包：可选 number 先 Number.from 再比较返回，避免 compareTo / expected Number actual Any
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 不传参行为与上一版兼容
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-emqxmqtt 使用说明

标准 MQTT 3.1.1 客户端，兼容 EMQX 等 Broker，适用于设备上下行、状态同步与消息推送场景。

当前版本：1.5.7

• Android / iOS：原生 TCP 或 SSL
• 微信小程序 / 鸿蒙 / H5：MQTT over WebSocket（ws / wss）
• 能力：连接、订阅、发布、遗嘱、指数退避重连与次数上限；QoS 0/1/2、retain、账号密码、cleanSession；payload 支持文本与二进制；发布队列背压
• 不做 EMQX 服务端、不做 MQTT 5 全家桶、不做其它小程序

建议调用顺序：init → connect → subscribe / publish → unsubscribe → disconnect / destroy。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg（中文）。

1. 环境要求

• HBuilderX 4.11 及以上（鸿蒙 UTS 建议 4.81+）
• uni-app Vue3（App-vue / App-nvue）或 uni-app x（App；微信 / H5 能力与 uni-app 一致）
• 支持：App-Android、App-iOS、App-鸿蒙、微信小程序、H5（Chrome / Safari）；uni-app x 含鸿蒙与 H5
• 不支持：其它小程序
• Android 最低 API：21；iOS 最低 12；鸿蒙最低 API：12；微信小程序基础库建议 2.10.0 及以上
• App 真机调试须制作自定义基座；正式发版须购买授权后走云端传统打包
• 授权绑定唯一 appid + 包名

2. 安装与引入

将插件目录放入工程的 uni_modules/breao-emqxmqtt，或从插件市场导入后同步。

import {
  init,
  connect,
  disconnect,
  destroy,
  subscribe,
  unsubscribe,
  publish,
  getConnectionState,
} from '@/uni_modules/breao-emqxmqtt'

3. API

3.1 init / destroy

init({
  host: 'broker.emqx.io',
  port: 1883,
  clientId: 'uni-app-demo',
  autoReconnect: true,
  maxReconnectAttempts: 5,
  maxPublishQueue: 32,
  will: {
    topic: 'device/status',
    payload: 'offline',
    qos: 0,
    retain: false,
  },
  onMessage(msg) {
    // msg: { topic, payload, payloadBytes, encoding, qos, retain }
    console.log(msg.topic, msg.encoding, msg.payload)
  },
  onConnectionLost(res) {
    console.log('lost', res)
  },
  success() {},
  fail(err) {
    console.error(err.errCode, err.errMsg)
  },
})

destroy({ success() {}, fail() {} })

destroy 会断开连接并清空 onMessage / onConnectionLost。App 忽略 wsPath / mapTcpPortToWs。微信 / 鸿蒙 / H5 请用 WS 口（常用 8083 / 8084）或保留默认端口映射。

3.2 connect / disconnect / 状态

connect({
  timeout: 15000,
  success() {},
  fail(err) { console.error(err.errCode, err.errMsg) },
})

getConnectionState({
  success(res) {
    // res.state: idle | connecting | connected | disconnected
  },
})

disconnect({ success() {}, fail() {} })

3.3 subscribe / unsubscribe / publish

subscribe({ topic: 'test/uni', qos: 1, success() {}, fail() {} })

publish({
  topic: 'test/uni',
  payload: 'hello',
  qos: 0,
  retain: false,
  success() {},
  fail(err) { console.error(err.errCode, err.errMsg) },
})

// 二进制
publish({
  topic: 'test/bin',
  payload: new Uint8Array([0x01, 0x02, 0xff]).buffer,
  qos: 2,
  success() {},
})

unsubscribe({ topic: 'test/uni', success() {} })

微信 / 鸿蒙 / H5 订阅与 QoS>0 发布会等待 Broker 应答（SUBACK / PUBACK / PUBREC·PUBREL·PUBCOMP）。

3.4 二进制约定

• 发布 / 遗嘱：payload 可为 string（按 UTF-8 编码）或 ArrayBuffer（原样发送）
• 接收：始终带回 payloadBytes（ArrayBuffer）与 encoding
  • encoding === 'utf8'：payload 为可靠 UTF-8 文本
  • encoding === 'binary'：请使用 payloadBytes；payload 仅为尽力解码视图

4. 可配置项

不传参即用默认值。

5. 完整示例

5.1 App（TCP / SSL）

import {
  init, connect, subscribe, publish, unsubscribe, disconnect, destroy,
} from '@/uni_modules/breao-emqxmqtt'

init({
  host: 'broker.emqx.io',
  port: 1883,
  keepAlive: 60,
  autoReconnect: true,
  maxReconnectAttempts: 5,
  onMessage(msg) {
    if (msg.encoding === 'binary') {
      console.log(msg.topic, Array.from(new Uint8Array(msg.payloadBytes)))
    } else {
      console.log(msg.topic, msg.payload)
    }
  },
  success() {
    connect({
      success() {
        subscribe({
          topic: 'test/uni',
          qos: 1,
          success() {
            publish({
              topic: 'test/uni',
              payload: 'hello',
              qos: 1,
              retain: true,
              success() {
                unsubscribe({ topic: 'test/uni', success() { disconnect({ success() { destroy({}) } }) } })
              },
            })
          },
        })
      },
    })
  },
  fail(err) { console.error(err.errCode, err.errMsg) },
})

5.2 微信小程序 / 鸿蒙 / H5（WebSocket）

import { init, connect, subscribe, publish } from '@/uni_modules/breao-emqxmqtt'

init({
  host: 'broker.emqx.io',
  port: 8083,
  useTls: false,
  wsPath: '/mqtt',
  will: { topic: 'test/will', payload: 'offline', qos: 0, retain: false },
  onMessage(msg) { console.log(msg.topic, msg.encoding, msg.payload) },
  success() {
    connect({
      success() {
        subscribe({ topic: 'test/uni', qos: 1 })
        publish({ topic: 'test/uni', payload: 'hello', qos: 0 })
        publish({
          topic: 'test/bin',
          payload: new Uint8Array([0xaa, 0x55]).buffer,
          qos: 2,
        })
      },
    })
  },
})

微信正式环境须 useTls: true（wss），并在小程序后台配置 socket 合法域名；H5 正式环境建议 wss；Broker 须开启 MQTT over WebSocket。

6. 权限

请在应用 manifest / 隐私弹窗中按需声明，并说明用于连接 MQTT Broker 收发业务报文。

7. 错误码（904）

8. 平台注意

• uni-app x（.uvue）：1.5.7 起可直接传对象字面量调用 API，无需 as XxxOption；须使用 1.5.7+ 并重打自定义基座
• App 为 TCP/SSL；微信 / 鸿蒙 / H5 为 WS/WSS，端口与路径勿混用
• 若 WS 端仍传 1883/8883，默认映射为 8083/8084；可用 mapTcpPortToWs: false 关闭
• Android TLS 使用系统默认信任库；自签证书需业务侧另行处理
• QoS 支持 0 / 1 / 2；不支持 MQTT 5
• 重连为指数退避（基础间隔 × 2^n，上限 60s）；maxReconnectAttempts 为 0 时不限制次数
• maxPublishQueue 仅约束 QoS>0 在途发布；满则返回发布失败
• 二进制消息请以 payloadBytes 为准；勿对 encoding === 'binary' 的 payload 做业务解析