更新记录

1.0.1（2026-04-17）

首次发布

平台兼容性

uni-app(4.85)

其他

xn-mqtt

xn-mqtt 是一个基于 UTS 的 MQTT 插件，适用于需要在 UniApp 中接入 MQTT Broker 的 Android 项目。

功能特性

• MQTT 连接
• 订阅 / 取消订阅
• 发布消息 / 指定 QoS 发布
• 断开连接 / 手动重连
• 连接状态查询
• 统一回调通知

支持平台

• App-Android
• 最低版本：minSdkVersion 21

安装方式

将插件放入项目：

uni_modules/xn-mqtt

快速开始

import {
  enabledDebug,
  addCallback,
  connectUseJson,
  subscribe,
  publish,
  disconnect
} from "@/uni_modules/xn-mqtt";

enabledDebug(true);

addCallback((res) => {
  console.log("MQTT 回调：", res);
});

connectUseJson({
  server: "tcp://127.0.0.1:1883",
  clientId: "client-001",
  userName: "username",
  password: "password",
  autoReconnect: true,
  isCleanSession: true,
  connectionTimeout: 30,
  keepAliveInterval: 60,
  qos: 1
});

subscribe("demo/topic");
publish("hello mqtt", "demo/topic");
disconnect();

回调说明

addCallback 返回结构：

{
  code: Number,
  msg: String,
  reconnect: Boolean,
  data?: Object
}

常见状态码：

• 0：连接成功
• 1：消息发送成功
• 2：收到消息
• 3：订阅成功
• 4：取消订阅成功
• -1：连接异常或超时
• -2：手动断开
• -3：掉线，准备自动重连
• -4：掉线，需要手动重连
• -5：订阅失败，客户端未连接或未初始化
• -6：发布失败，客户端未连接
• -7：发布失败，主题或消息非法，或传输异常
• -8：订阅失败，主题为空或订阅异常
• -9：连接参数错误
• -10：取消订阅失败

权限声明

• android.permission.INTERNET
• android.permission.ACCESS_NETWORK_STATE
• android.permission.WAKE_LOCK
• android.permission.ACCESS_WIFI_STATE

注意事项

• server 必须以 tcp://、ssl://、ws:// 或 wss:// 开头
• clientId 不能为空
• 建议先调用 addCallback 再连接
• 当前仅支持 Android

文档

• 详细使用说明：usage.md
• 示例页面：pages/sample/uts_mqtt_demo

版本记录

见 changelog.md