更新记录

1.0.0（2026-09-30） 下载此版本

首次完整实现：原生 MQTT 3.1.1 透传客户端（connect / subscribe / publish / unsubscribe / disconnect）。

• Android：Eclipse Paho mqttv3 1.2.5
• iOS：CocoaMQTT 2.1.x
• HarmonyOS：ohpm @ohos/mqtt@2.0.18

平台兼容性

uni-app x(5.21)

其他

原生 MQTT 3.1.1 客户端（Android / iOS / 鸿蒙）

面向 uni-app x（含蒸汽模式） 的三端 UTS 原生 MQTT 透传客户端。统一 connect / subscribe / publish / unsubscribe API 与错误码，适合 IoT 设备长连接、网关等场景。

功能特性

平台兼容性

• HBuilderX：^4.27（@UTSJS.keepAlive 需要）
• uni-app x：App-Android / App-iOS / App-HarmonyOS（含蒸汽模式）

快速开始

import {
  connect, subscribe, publish, unsubscribe, disconnect, isConnected
} from '@/uni_modules/bin-mqtt'

// 1. 建立连接（重复调用：已连接直接 onConnected；连接中忽略）
connect({
  url: 'tcp://mqtt.example.com:1883', // 或 wx://host:8083/mqtt、ssl://…、wss://…
  clientId: 'user_xxx',
  username: 'xxx',
  password: 'xxx',
  keepalive: 60,
  cleanSession: true,
  connectTimeout: 30,
  reconnectInterval: 5000, // 0 关闭插件内自动重连
  onConnected: () => {
    // 首次与重连成功都会触发
    subscribe({ topic: '/things/xxx/commands', qos: 1 })
  },
  onMessage: (topic, payload) => {
    // payload 为 UTF-8 文本；对象请自行 JSON.parse
    console.log(topic, payload)
  },
  onClosed: () => {
    // 仅被动断开（网络错误 / 服务端关闭）；主动 disconnect 不触发
  },
  onError: (errCode, errMsg) => {
    uni.showToast({ title: errMsg, icon: 'none' })
  },
  onReconnect: (attempt) => {
    // 重连尝试开始（attempt 从 1 起），不是重连成功
    console.log('reconnect attempt', attempt)
  }
})

// 2. 发布（对象请先 JSON.stringify）
publish({
  topic: '/things/xxx/properties',
  payload: JSON.stringify({ power: 1 }),
  qos: 0,
  retained: false,
  onSuccess: () => {},
  onFail: (errCode, errMsg) => {}
})

// 3. 取消订阅 / 断开
unsubscribe({ topic: '/things/xxx/commands' })
disconnect()

URL 约定

broker 开放 1883 时优先用 tcp://host:1883（比 WebSocket 更稳）；仅开放 8083/443 时用 ws:// / wss://。

API

connect(options): void

建立连接并替换、释放此前的连接。void 返回 + @UTSJS.keepAlive，保证 onMessage 等持续回调不被回收。

subscribe(options): void

publish(options): void

unsubscribe(options): void

disconnect(): void

主动断开并释放客户端。幂等。不回调 onClosed。

isConnected(): boolean

当前是否已连接。

错误码

集成说明

Android

• 依赖经 Gradle maven 拉取 org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.5，不要再往 libs/ 放同一 jar。
• 编译需能访问 Maven Central；标准基座可能不带 maven 产物，真机调试请用 自定义基座 / 云打包。
• 权限：INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE。

iOS

• 使用预编 Frameworks/*.xcframework（CocoaMQTT / MqttCocoaAsyncSocket / Starscream）。
• 不要改用 dependencies-pods（会丢 DCloudUTSFoundation）或 dependencies-spms（显式模块编不过 ObjC 包）。
• CocoaMQTT 2.1.6 固定 MQTT 3.1.1；allowUntrustCACertificate 保持关闭（默认不信任任意 CA）。
• 非 TLS 地址（tcp:// / ws://）需业务侧配置 NSAppTransportSecurity。
• 含 PrivacyInfo.xcprivacy（UserDefaults，无 Tracking）。

HarmonyOS

• 依赖 ohpm @ohos/mqtt@2.0.18，云打包 / 真机需能拉取该包。
• 优先验证 tcp://（库为原生 so）。

行为约定

• connect 重复调用：已连接直接 onConnected；连接中忽略。
• 主动 disconnect() 不回调 onClosed；被动断开会回调并按 reconnectInterval 自动重连。
• 持续回调在胶水层使用 @UTSJS.keepAlive（需 HBuilderX ≥ 4.27）；请勿高频调用 connect。
• onReconnect 表示「重连尝试开始」，不是重连成功；重连成功走 onConnected。
• payload 统一 UTF-8 字符串；非 UTF-8 时各端按实现回退。

最佳实践

1. clientId 全局唯一（可拼用户 ID / 设备 ID / 随机后缀），避免互踢。
2. 业务层做会话隔离：页面/模块各自订阅自己的 topic，关闭时 unsubscribe + 必要时 disconnect。
3. 重连策略：简单场景用 reconnectInterval；需要指数退避、超限断开时传 reconnectInterval: 0，在业务层调度。
4. 消息体建议 JSON 文本，插件不做解析，便于跨端一致。

开发文档

• UTS 语法
• UTS API 插件
• UTS iOS CocoaPods