更新记录

0.2.9（2025-10-16）

• feat: 提供common目录

0.2.8（2025-10-16）

• fix: 修复鸿蒙报错问题

0.2.7（2025-10-15）

• fix: 修复鸿蒙报错问题

平台兼容性

uni-app(4.45)

uni-app x(4.61)

lime-mqtt MQTT通信组件

一个功能强大的MQTT通信组件，提供跨平台的MQTT协议通信能力，支持连接、订阅、发布、断开等基础操作，适用于物联网、实时通信等场景。支持安卓、IOS、鸿蒙Next、Web、微信小程序等平台。

文档链接

📚 组件详细文档请访问以下站点：

• MQTT通信组件文档 - 站点1
• MQTT通信组件文档 - 站点2
• MQTT通信组件文档 - 站点3

安装方法

1. 在uni-app插件市场中搜索并导入lime-mqtt
2. 导入后可能需要重新编译项目
3. APP开发需要使用自定义基座

代码演示

初始化客户端

首先需要导入并初始化MQTT客户端。

import { useMQTT } from '@/uni_modules/lime-mqtt'
const mqttClient = useMQTT()

连接MQTT服务器

连接到MQTT服务器，可配置多种参数。

import type { MQTTConnectOptions } from '@/uni_modules/lime-mqtt'

mqttClient.connect({
  host: "broker.example.com",  // MQTT服务器地址
  port: 8083,                  // 服务器端口
  clientId: "myClient_123",    // 可选，默认自动生成
  username: "user",            // 可选，用户名
  password: "pass",            // 可选，密码
  useSSL: true,                // 是否使用SSL，默认true
  keepalive: 60,               // 心跳间隔，默认60秒
  timeout: 30,                 // 超时时间，默认30秒
  reconnect: false,            // 是否自动重连，默认false
  success: (res) => {
    console.log("连接成功:", res.data.errMsg)
  },
  fail: (err) => {
    console.error("连接失败:", err.errorCode, err.errorMessage)
  }
} as MQTTConnectOptions)

断开连接

主动断开与MQTT服务器的连接。

import type { MQTTDisconnectOptions } from '@/uni_modules/lime-mqtt'

mqttClient.disconnect({
  success: (res) => {
    console.log("已断开连接:", res.data.errMsg)
  },
  fail: (err) => {
    console.error("断开连接失败:", err.errorCode)
  }
} as MQTTDisconnectOptions)

订阅主题

订阅指定的MQTT主题，可设置服务质量(QoS)。

import type { MQTTSubscribeOptions } from '@/uni_modules/lime-mqtt'

mqttClient.subscribe({
  topic: "home/sensor/temperature",  // 要订阅的主题
  qos: 1,                            // 服务质量，0-2
  success: (res) => {
    console.log(`订阅成功: ${res.data.topic}, QoS: ${res.data.qos}`)
  },
  fail: (err) => {
    console.error("订阅失败:", err.errorCode)
  }
} as MQTTSubscribeOptions)

取消订阅

取消订阅指定的MQTT主题。

import type { MQTTUnSubscribeOptions } from '@/uni_modules/lime-mqtt'

mqttClient.unsubscribe({
  topic: "home/sensor/temperature",  // 要取消订阅的主题
  success: (res) => {
    console.log(`已取消订阅: ${res.data.topic}`)
  },
  fail: (err) => {
    console.error("取消订阅失败:", err.errorCode)
  }
} as MQTTUnSubscribeOptions)

发布消息

向指定主题发布消息。

import type { MQTTPublishOptions } from '@/uni_modules/lime-mqtt'

mqttClient.publish({
  topic: "home/light/control",  // 发布的主题
  payload: "turn_on",           // 消息内容
  qos: 1                        // 服务质量，0-2
  success: (res) => {
    console.log(`消息发送成功: ${res.data.topic}`)
  },
  fail: (err) => {
    console.error("消息发送失败:", err.errorCode)
  }
} as MQTTPublishOptions)

监听消息

监听订阅主题的消息。

import type { MQTTMessage } from '@/uni_modules/lime-mqtt'

// 定义消息处理函数
const messageHandler = (msg: MQTTMessage) => {
  console.log(`收到消息 [${msg.topic}]: ${msg.payloadString}`)
  console.log("QoS:", msg.qos)
  console.log("是否保留消息:", msg.retained)

  // 如果需要处理二进制数据
   console.log("二进制数据:", msg.payload)
}

// 添加消息监听
mqttClient.onMessage(messageHandler)

// 移除特定的消息监听
mqttClient.offMessage(messageHandler)

// 移除所有消息监听
mqttClient.offMessage()

监听连接状态

监听MQTT连接状态变化。

import type { StateChangeCallback } from '@/uni_modules/lime-mqtt'

// 定义状态变化处理函数
const stateHandler: StateChangeCallback = (stateInfo) => {
  console.log(`连接状态变化: ${stateInfo.state ? '已连接' : '已断开'}`)
  console.log(`状态变化时间: ${new Date(stateInfo.timestamp).toLocaleString()}`)
}

// 添加状态监听
mqttClient.onStateChange(stateHandler)

// 移除特定的状态监听
mqttClient.offStateChange(stateHandler)

// 移除所有状态监听
mqttClient.offStateChange()

API文档

IMQTTClient 接口

属性

参数类型

MQTTConnectOptions

MQTTDisconnectOptions

MQTTSubscribeOptions

MQTTUnSubscribeOptions

MQTTPublishOptions

MQTTMessage

错误代码参考

常见问题

• iOS平台注意事项: iOS平台上的offMessage和offStateChange暂时无法清空指定函数，只能全部清空（HBuilderX 4.74版本）。
• 小程序连接问题: 微信小程序连接MQTT服务器时，需要在小程序管理后台配置域名白名单。
• 通配符订阅: 使用通配符订阅时，取消订阅也需要使用相同的通配符格式。
• 自动重连: 设置reconnect为true时，客户端会在连接断开后自动尝试重新连接。
• QoS级别:
  • QoS 0: 最多发送一次，可能丢失
  • QoS 1: 至少发送一次，可能重复
  • QoS 2: 只发送一次，不会丢失也不会重复

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助