更新记录

1.0.0（2025-07-11）

初始版本，原生 MQTT 实现

平台兼容性

uni-app x

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
-	-	7.0	×	×	×

native-mqtt

基于UTS技术开发的跨平台MQTT客户端插件，支持uni-app全平台。采用Eclipse Paho MQTT Android Client实现，提供稳定可靠的MQTT通信能力。

功能特性

✅ 完整的MQTT协议支持：基于Eclipse Paho MQTT实现，支持MQTT 3.1.1协议
✅ 智能连接管理：支持TCP/SSL协议，自动协议选择，连接状态实时监控
✅ 高级连接功能：支持自动重连、连接超时控制、心跳机制
✅ 消息通信：支持发布/订阅消息，完整的消息回调处理
✅ QoS支持：支持QoS 0/1/2等级，保证消息传输质量
✅ 会话管理：支持清理会话和持久会话
✅ 资源管理：自动资源清理，防止内存泄漏
✅ 错误处理：完整的错误处理和状态回调机制
✅ 调试支持：详细的调试日志，便于问题排查

平台支持

平台	状态	说明
Android	✅ 完全支持	基于Eclipse Paho MQTT Android，最低SDK 21
iOS	⚠️ 配置就绪	架构已准备，功能待实现

快速开始

1. 安装插件

将插件复制到项目的 uni_modules 目录下。

2. 基本使用

import { MQTT } from "@/uni_modules/native-mqtt"

// 创建MQTT实例
const mqtt = new MQTT();

// 配置连接参数
mqtt.initParams({
  host: "your-mqtt-broker.com",
  port: 1883,
  clientId: "your-client-id",
  userName: "username",
  password: "password",
  isAutomaticReconnect: true,
  isCleanSession: false,
  keepAliveInterval: 60,
  connectionTimeout: 30
});

// 连接到MQTT服务器
mqtt.connect(
  // 连接状态变化回调
  (action, message) => {
    switch(action) {
      case 1: // CONNECT_SUCCESS
        console.log('连接成功:', message);
        break;
      case 2: // RECONNECT_SUCCESS
        console.log('重连成功:', message);
        break;
      case 3: // CONNECT_LOST
        console.log('连接丢失:', message);
        break;
      case 4: // CONNECT_FAIL
        console.log('连接失败:', message);
        break;
    }
  },
  // 消息接收回调
  (topic, message) => {
    console.log('收到消息:', topic, message);
  }
);

// 订阅主题
mqtt.subscribe("your/topic", 1);

// 发布消息
mqtt.publish("your/topic", "Hello MQTT!", 1);

// 断开连接
mqtt.disconnect();

API 文档

类型定义

MqttInitParams

连接参数配置对象

type MqttInitParams = {
  host: string;                    // MQTT服务器地址
  port: number;                    // 端口号
  clientId: string;                // 客户端ID
  userName: string;                // 用户名
  password: string;                // 密码
  isAutomaticReconnect: boolean;   // 是否自动重连
  isCleanSession: boolean;         // 是否清理会话
  keepAliveInterval: number;       // 心跳间隔（秒）
  connectionTimeout: number;       // 连接超时（秒）
}

ConnectChangeResult

连接状态变化回调函数

type ConnectChangeResult = (action: number, message: string) => void

状态码说明:

1 - CONNECT_SUCCESS: 连接成功
2 - RECONNECT_SUCCESS: 重连成功
3 - CONNECT_LOST: 连接丢失
4 - CONNECT_FAIL: 连接失败

MessageReceived

消息接收回调函数

type MessageReceived = (topic: string, message: string) => void

MQTT 类方法

initParams(params: MqttInitParams)

初始化连接参数

connect(connectCallback: ConnectChangeResult, messageCallback: MessageReceived)

连接到MQTT服务器

connectCallback: 连接状态变化回调，监听连接、重连、丢失、失败等状态
messageCallback: 消息接收回调，接收订阅主题的消息

disconnect()

断开MQTT连接，自动清理所有回调和资源，防止内存泄漏

subscribe(topic: string, qos: number)

订阅主题

topic: 主题名称
qos: QoS等级 (0, 1, 2)

unsubscribe(topic: string)

取消订阅主题

topic: 主题名称

publish(topic: string, message: string, qos: number)

发布消息

topic: 主题名称
message: 消息内容
qos: QoS等级 (0, 1, 2)

isConnected(): boolean

检查连接状态

高级功能

连接状态监控

插件提供完整的连接状态监控，通过状态码精确识别连接状态：

mqtt.connect(
  (action, message) => {
    switch(action) {
      case 1: // 连接成功
        // 连接建立，可以开始订阅和发布
        console.log('MQTT连接已建立');
        break;
      case 2: // 重连成功  
        // 网络恢复后自动重连成功
        console.log('MQTT重连成功');
        break;
      case 3: // 连接丢失
        // 网络中断或服务器断开
        console.log('MQTT连接丢失，等待重连...');
        break;
      case 4: // 连接失败
        // 认证失败、网络错误等
        console.log('MQTT连接失败:', message);
        break;
    }
  },
  (topic, message) => {
    console.log(`收到消息 [${topic}]: ${message}`);
  }
);

自动重连机制

插件支持智能自动重连，在网络恢复时自动重新建立连接：

mqtt.initParams({
  // ... 其他配置
  isAutomaticReconnect: true,  // 启用自动重连
  keepAliveInterval: 60,       // 心跳间隔60秒
  connectionTimeout: 30        // 连接超时30秒
});

资源管理

插件提供自动资源管理，在断开连接时自动清理：

// 在页面卸载或应用退出时调用
mqtt.disconnect(); // 自动清理回调和资源

配置说明

Android 配置

权限配置

插件已自动配置以下权限：

android.permission.INTERNET - 网络访问权限
android.permission.WAKE_LOCK - 保持设备唤醒，维持长连接
android.permission.ACCESS_NETWORK_STATE - 网络状态监控

依赖库

Eclipse Paho MQTT Android Service: 4.2
Eclipse Paho MQTT Client: 1.2.5
最低Android SDK: 21 (Android 5.0)

iOS 配置

最低部署目标：iOS 12.0

注意：iOS平台功能正在开发中

完整示例

Vue页面集成示例

<template>
  <view class="container">
    <view class="status">
      <text>连接状态: {{ isConnected ? '已连接' : '未连接' }}</text>
    </view>

    <button @click="connectMqtt" :disabled="isConnecting">
      {{ isConnecting ? '连接中...' : '连接MQTT' }}
    </button>

    <button @click="publishMessage" :disabled="!isConnected">
      发送测试消息
    </button>

    <view class="messages">
      <text v-for="(msg, index) in messages" :key="index">
        {{ msg }}
      </text>
    </view>
  </view>
</template>

<script>
import { MQTT } from "@/uni_modules/native-mqtt"

export default {
  data() {
    return {
      mqtt: null,
      isConnected: false,
      isConnecting: false,
      messages: []
    }
  },

  onLoad() {
    this.initMqtt()
  },

  onUnload() {
    // 页面卸载时清理资源
    if (this.mqtt) {
      this.mqtt.disconnect()
    }
  },

  methods: {
    initMqtt() {
      this.mqtt = new MQTT()

      // 配置连接参数
      this.mqtt.initParams({
        host: "your-broker.com",
        port: 1883,
        clientId: "client_" + Date.now(),
        userName: "your_username",
        password: "your_password",
        isAutomaticReconnect: true,
        isCleanSession: false,
        keepAliveInterval: 60,
        connectionTimeout: 30
      })
    },

    connectMqtt() {
      this.isConnecting = true

      this.mqtt.connect(
        (action, message) => {
          this.isConnecting = false

          switch(action) {
            case 1: // 连接成功
              this.isConnected = true
              this.addMessage('✅ 连接成功')
              // 连接成功后订阅主题
              this.mqtt.subscribe('test/topic', 1)
              break
            case 2: // 重连成功
              this.isConnected = true
              this.addMessage('🔄 重连成功')
              break
            case 3: // 连接丢失
              this.isConnected = false
              this.addMessage('⚠️ 连接丢失')
              break
            case 4: // 连接失败
              this.isConnected = false
              this.addMessage('❌ 连接失败: ' + message)
              break
          }
        },
        (topic, message) => {
          this.addMessage(`📨 [${topic}]: ${message}`)
        }
      )
    },

    publishMessage() {
      if (this.isConnected) {
        const message = `Hello MQTT! ${new Date().toLocaleTimeString()}`
        this.mqtt.publish('test/topic', message, 1)
        this.addMessage(`📤 发送: ${message}`)
      }
    },

    addMessage(msg) {
      this.messages.push(`[${new Date().toLocaleTimeString()}] ${msg}`)
      // 限制消息数量
      if (this.messages.length > 50) {
        this.messages.shift()
      }
    }
  }
}
</script>

测试工具

项目中包含完整的MQTT测试页面，位于 pages/mqtt/mqtt.nvue，提供了：

📋 连接配置界面: 支持服务器地址、端口、认证等完整配置
🔌 连接管理: 连接、断开、重连状态实时显示
📝 订阅管理: 动态订阅和取消订阅主题
📤 消息发布: 支持不同QoS等级的消息发布
📊 实时日志: 连接状态和消息收发的详细日志
🎛️ 调试工具: 便于开发调试和问题排查

开发注意事项

Android 平台

最低支持 Android 5.0 (API Level 21)
需要网络权限
支持后台保持连接

跨平台考虑

使用统一的TypeScript接口
平台特定实现通过UTS桥接
回调函数使用 @UTSJS.keepAlive 保持活跃

技术架构

┌─────────────────┐
│   Vue/UniApp    │  应用层
├─────────────────┤
│   UTS Interface │  接口层
├─────────────────┤
│   UTS Bridge    │  桥接层
├─────────────────┤
│  Native MQTT    │  原生层
└─────────────────┘

开发文档

常见问题

Q: 连接一直失败怎么办？

A: 请检查以下项目：

网络连接: 确保设备网络正常
服务器地址: 检查MQTT服务器地址和端口是否正确
认证信息: 验证用户名和密码是否有效
防火墙: 确保网络防火墙允许MQTT端口通信
协议支持: 确认服务器支持的协议版本

Q: 为什么会自动断线？

A: 可能的原因：

网络不稳定: 移动网络波动导致连接中断
心跳超时: keepAliveInterval设置过短或过长
服务器限制: 服务器主动断开空闲连接
应用后台: 系统杀死后台应用导致连接断开

解决方案：调整心跳间隔，启用自动重连。

Q: 如何处理大量消息？

A: 建议：

合理设置QoS: 根据消息重要性选择合适的QoS等级
消息过滤: 使用主题过滤，只订阅必要的主题
批处理: 对收到的消息进行批处理，避免UI频繁更新
内存管理: 及时清理不需要的消息，防止内存溢出

Q: 支持SSL/TLS加密吗？

A: 当前版本支持SSL协议，会根据配置自动选择TCP或SSL连接方式。

调试指南

启用详细日志

在HBuilderX控制台中查看MQTT相关日志，标签为 MqttManager：

// 日志示例
[MqttManager] 开始连接MQTT broker: tcp://broker.com:1883
[MqttManager] 客户端ID: client_123456
[MqttManager] 连接成功，开始订阅主题
[MqttManager] 订阅主题成功: test/topic (QoS: 1)

性能监控

监控关键指标：

连接建立时间
消息发送延迟
重连频率
内存使用情况

更新日志

v1.2.0 (当前版本)

✅ 优化连接状态回调机制，提供更详细的状态码
✅ 增强自动重连功能，提高连接稳定性
✅ 完善资源管理，防止内存泄漏
✅ 增强错误处理和调试日志
✅ 支持SSL/TLS加密连接

v1.1.0

✅ 重构MQTT连接管理逻辑
✅ 优化消息处理性能
✅ 增加连接超时控制

v1.0.0

✅ 基础MQTT功能实现
✅ 支持基本的发布/订阅
✅ Android平台完整支持

版本信息

当前版本: 1.2.0
最低HBuilderX版本: 3.6.8
插件类型: UTS
支持平台: Android (完整) / iOS (开发中)
MQTT协议版本: 3.1.1
依赖版本: Eclipse Paho MQTT 4.2+

技术支持

如遇到问题，请按以下步骤排查：

检查基础配置: 网络、服务器地址、认证信息
查看控制台日志: HBuilderX控制台中的详细日志
测试网络连通性: 确保目标服务器可达
参考示例代码: 对比官方示例确认集成方式
更新到最新版本: 使用最新版本获得最佳体验

更多技术支持请参考项目文档或联系开发团队。

native-mqtt native-mqtt

更新记录

1.0.0（2025-07-11）

平台兼容性

uni-app x

native-mqtt

功能特性

平台支持

快速开始

1. 安装插件

2. 基本使用

API 文档

类型定义

MqttInitParams

ConnectChangeResult

MessageReceived

MQTT 类方法

initParams(params: MqttInitParams)

connect(connectCallback: ConnectChangeResult, messageCallback: MessageReceived)

disconnect()

subscribe(topic: string, qos: number)

unsubscribe(topic: string)

publish(topic: string, message: string, qos: number)

isConnected(): boolean

高级功能

连接状态监控

自动重连机制

资源管理

配置说明

Android 配置

权限配置

依赖库

iOS 配置

完整示例

Vue页面集成示例

测试工具

开发注意事项

Android 平台

跨平台考虑

技术架构

开发文档

常见问题

Q: 连接一直失败怎么办？

Q: 为什么会自动断线？

Q: 如何处理大量消息？

Q: 支持SSL/TLS加密吗？

调试指南

启用详细日志

性能监控

更新日志

v1.2.0 (当前版本)

v1.1.0

v1.0.0

版本信息

技术支持

隐私、权限声明

1. 本插件需要申请的系统权限列表：

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

native-device

HL-WebView

native-mqtt

native-webview

Modal title