更新记录

v0.0.1（2026-04-05） 下载此版本

uni-mqtt-lite

一个基于 UniApp WebSocket 的轻量级 MQTT 3.1.1 客户端插件。

适用于 UniApp / Vue3 项目，支持连接、订阅、发布、断开、自动重连、自动恢复订阅等基础能力。

特性

• 基于 uni.connectSocket 实现，适配 UniApp 多端环境
• 无第三方依赖，包体轻量
• 支持 MQTT 3.1.1
• 支持 QoS 0 / QoS 1
• 支持自动重连
• 支持重连后恢复订阅
• 支持字符串 / JSON / Uint8Array / ArrayBuffer 消息发布
• 提供事件监听机制，方便页面状态同步

平台兼容性

uni-app(5.05)

UniApp MQTT 客户端插件

基于 UniApp WebSocket 实现的 MQTT 3.1.1 协议客户端，轻量、无依赖、支持多实例。

平台支持

特性

• 🚀 轻量无依赖 - 体积约 15KB，无第三方依赖
• 🔌 多实例支持 - 可同时连接多个不同的 MQTT Broker
• 🔄 自动重连 - 支持断线自动重连，可配置重连间隔
• 📡 订阅恢复 - 重连后智能恢复订阅（根据 sessionPresent 判断）
• ⏱️ 超时保护 - 订阅、发布、取消订阅均有超时机制
• 🛡️ 异常容错 - 报文解析异常不会导致消息循环崩溃
• ⚙️ 灵活配置 - 支持自定义 WebSocket 子协议、超时时间等

安装

将 utils/mqtt 目录复制到你的 UniApp 项目中：

your-project/
└── utils/
    └── mqtt/
        ├── index.js    # 核心模块
        ├── config.js   # 配置文件
        ├── codec.js    # 编解码模块
        └── packets.js  # 报文构建模块

快速开始

基础用法

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import mqttService from '@/utils/mqtt'

const status = ref('disconnected')

function onMessage(data) {
  console.log('收到消息：', data.topic, data.payloadText)
}

onMounted(async () => {
  mqttService.on('message', onMessage)

  await mqttService.connect({
    url: 'wss://your-broker:8084/mqtt',
    username: 'your-username',
    password: 'your-password'
  })

  await mqttService.subscribe('test/#')
  await mqttService.publish('test/hello', 'Hello MQTT')
})

onUnmounted(() => {
  mqttService.off('message', onMessage)
  mqttService.disconnect()
})
</script>

多实例用法

import { createMqttClient } from '@/utils/mqtt'

const client1 = createMqttClient()
const client2 = createMqttClient()

await client1.connect({
  url: 'wss://broker1.example.com:8084/mqtt',
  username: 'user1',
  password: 'pass1'
})

await client2.connect({
  url: 'wss://broker2.example.com:8084/mqtt',
  username: 'user2',
  password: 'pass2'
})

client1.destroy()
client2.destroy()

API 文档

导出方式

import mqttService, { UniMqttClient, createMqttClient } from '@/utils/mqtt'

const client1 = mqttService

const client2 = createMqttClient()

const client3 = new UniMqttClient()

配置项

方法

connect(config)

连接到 MQTT 服务器。

await mqttService.connect({
  url: 'wss://broker:8084/mqtt',
  username: 'user',
  password: 'pass',
  wsProtocols: ['mqtt']
})

subscribe(topic, options)

订阅主题。

const result = await mqttService.subscribe('test/#', { qos: 0 })
console.log(result)

unsubscribe(topic)

取消订阅。

await mqttService.unsubscribe('test/#')

publish(topic, message, options)

发布消息。支持字符串、对象、Uint8Array、ArrayBuffer。

await mqttService.publish('test/msg', 'Hello', { qos: 0 })

await mqttService.publish('test/msg', { foo: 'bar' }, { qos: 1 })

await mqttService.publish('test/binary', new Uint8Array([1, 2, 3]))

disconnect()

断开连接。

await mqttService.disconnect()

destroy()

销毁实例，释放所有资源。

mqttService.destroy()

getStatus()

获取当前状态。

const status = mqttService.getStatus()

isConnected()

检查是否已连接。

if (mqttService.isConnected()) {
}

getClientId()

获取客户端 ID。

const clientId = mqttService.getClientId()

事件

mqttService.on('message', (data) => {
  console.log('主题：', data.topic)
  console.log('文本：', data.payloadText)
  console.log('JSON：', data.payloadJson)
  console.log('字节：', data.payloadBytes)
})

mqttService.off('message', handler)

状态说明

重连机制

自动重连

当 autoReconnect: true 时，连接意外断开后会自动重连：

1. 触发 reconnect 事件
2. 等待 reconnectPeriod 毫秒
3. 重新建立连接

订阅恢复

重连成功后是否恢复订阅的逻辑：

QoS 支持

超时机制

以下操作有超时保护：

• 连接：connectTimeout（默认 10s）
• 订阅：requestTimeout（默认 10s）
• 取消订阅：requestTimeout（默认 10s）
• QoS 1 发布：requestTimeout（默认 10s）

超时后会 reject Promise，错误信息包含超时时长。

注意事项

1. 协议版本：当前仅支持 MQTT 3.1.1
2. QoS 限制：发布消息仅支持 QoS 0 和 QoS 1
3. WebSocket：必须使用 WebSocket 协议，地址格式为 wss://host:port/mqtt
4. 安全提示：请勿在代码中硬编码账号密码，建议从服务端获取

常见问题

1. 连接失败

• 检查服务器地址是否正确（需以 ws:// 或 wss:// 开头）
• 检查用户名密码是否正确
• 检查网络是否通畅
• 检查 wsProtocols 配置是否与服务器要求一致

2. 订阅无消息

• 检查订阅主题是否正确
• 检查发布者是否向该主题发布了消息
• 检查消息是否被其他客户端消费（非共享订阅）

3. 频繁重连

• 检查 keepAlive 设置是否合理
• 检查网络稳定性
• 检查服务器是否主动断开连接

更新日志

v1.0.0

• 支持 MQTT 3.1.1 协议
• 支持多实例
• 支持自动重连
• 支持订阅恢复
• 支持超时机制
• 支持异常容错

许可证

MIT License