更新记录

1.0.1（2025-08-23）

功能完善实现优化

平台兼容性

uni-app(4.55)

uni-app x(4.65)

其他

HMW-MQTT 企业级物联网通信插件

🚀 产品概述

HMW-MQTT 是一款专为 UniApp 生态系统设计的高性能 MQTT 通信插件，基于业界标准的 Eclipse Paho MQTT 客户端库构建。该插件采用原生 UTS 技术栈开发，为 Android 平台提供了企业级的物联网设备通信解决方案。

🎯 核心优势

• 🏗️ 企业级架构：基于 Eclipse Paho MQTT v3.1.1 协议标准，确保与主流 MQTT Broker 的完美兼容
• ⚡ 高性能原生实现：采用 UTS 原生技术，直接调用 Android 系统 API，性能卓越
• 🔄 智能连接管理：内置自动重连机制、心跳保持、连接状态监控等企业级特性
• 🛡️ 可靠消息传递：支持 QoS 0/1/2 三级服务质量保证，满足不同场景的可靠性需求
• 📡 多主题并发：支持同时订阅多个主题，高效处理复杂的消息路由场景
• 🔐 安全认证：支持用户名/密码认证，遗嘱消息机制，确保通信安全

🏢 应用场景

• 智能家居系统：设备状态监控、远程控制、场景联动
• 工业物联网：设备数据采集、生产线监控、预警系统
• 智慧城市：环境监测、交通管理、公共设施管理
• 移动应用：实时消息推送、状态同步、远程通知

📋 技术规格

🔧 系统要求

• HBuilderX: ≥ 3.6.8
• uni-app: ≥ 3.1.0
• Android: API Level 21+ (Android 5.0+)
• 权限需求: 网络访问、网络状态、WiFi状态、唤醒锁

🚀 快速开始

1. 安装插件

# 通过 HBuilderX 插件市场安装

2. 导入插件

import { MqttControl, MqttOpt } from '@/uni_modules/hmw-mqtt'

// 创建 MQTT 客户端实例
const mqttClient = new MqttControl()

3. 配置连接参数

const mqttConfig = {
  // 必填：MQTT 服务器地址
  host: "tcp://your-mqtt-broker.com:1883",

  // 必填：客户端唯一标识
  clientId: "UniApp_" + Date.now(),

  // 可选：认证信息
  username: "your_username",
  password: "your_password",

  // 可选：连接配置
  keepAliveInterval: 60,        // 心跳间隔(秒)
  connectionTimeout: 30000,     // 连接超时(毫秒)
  cleanSession: true,           // 清除会话
  automaticReconnect: true,     // 自动重连

  // 可选：订阅配置
  topic: ["sensor/temperature", "device/status"],
  qos: [1, 0],

  // 可选：遗嘱消息
  willTopic: "device/offline",
  willMsg: "Device disconnected",
  willQos: 1,
  willRetain: false
}

4. 设置回调函数

const callbacks = {
  // 连接状态回调
  connectSuccess: (success) => {
    console.log('连接状态:', success ? '成功' : '失败')
  },

  // 连接丢失回调
  connectLost: () => {
    console.log('连接已断开')
  },

  // 消息接收回调
  messageArrived: (topic, message) => {
    console.log(`收到消息 [${topic}]: ${message}`)
  },

  // 消息发送完成回调
  deliveryComplete: () => {
    console.log('消息发送完成')
  }
}

5. 建立连接

// 合并配置和回调
const options = { ...mqttConfig, ...callbacks }

// 连接到 MQTT 服务器
mqttClient.connect(options)

📚 API 参考

MqttControl 类

connect(options: MqttOpt): void

建立 MQTT 连接

参数说明：

• options: 连接配置对象，包含服务器地址、认证信息、回调函数等

subscribe(topics: string[], qos: number[], callback: Function): void

订阅主题

参数说明：

• topics: 主题数组
• qos: QoS 等级数组
• callback: 订阅结果回调

unsubscribe(topic: string, callback: Function): void

取消订阅

参数说明：

• topic: 要取消订阅的主题
• callback: 取消订阅结果回调

publish(topic: string, message: string, qos: number, retained: boolean): void

发布消息

参数说明：

• topic: 目标主题
• message: 消息内容
• qos: QoS 等级 (0/1/2)
• retained: 是否保留消息

isConnected(): boolean

检查连接状态

返回值：

• boolean: true 表示已连接，false 表示未连接

disconnect(): void

断开连接

💡 最佳实践

1. 连接管理

// 页面显示时连接
onShow() {
  if (!mqttClient.isConnected()) {
    mqttClient.connect(options)
  }
},

// 页面隐藏时断开
onHide() {
  if (mqttClient.isConnected()) {
    mqttClient.disconnect()
  }
}

2. 错误处理

const connectWithRetry = (retryCount = 3) => {
  try {
    mqttClient.connect({
      ...options,
      connectSuccess: (success) => {
        if (!success && retryCount > 0) {
          setTimeout(() => {
            connectWithRetry(retryCount - 1)
          }, 5000)
        }
      }
    })
  } catch (error) {
    console.error('连接失败:', error)
  }
}

3. 消息处理

const messageHandler = (topic, message) => {
  try {
    // 尝试解析 JSON 消息
    const data = JSON.parse(message)

    // 根据主题路由处理
    switch (topic) {
      case 'sensor/temperature':
        handleTemperatureData(data)
        break
      case 'device/status':
        handleDeviceStatus(data)
        break
      default:
        console.log('未知主题:', topic)
    }
  } catch (error) {
    // 处理非 JSON 消息
    console.log('收到文本消息:', message)
  }
}

⚠️ 注意事项

1. 网络权限：确保应用已获得网络访问权限
2. 连接管理：避免重复连接，使用 isConnected() 检查状态
3. 资源释放：页面销毁时及时断开连接，避免内存泄漏
4. QoS 选择：根据业务需求选择合适的 QoS 等级
5. 主题设计：使用层次化的主题结构，便于消息路由和权限控制

🔧 故障排除

常见问题

Q: 连接失败怎么办？ A: 检查网络连接、服务器地址、端口号和认证信息

Q: 消息收不到？ A: 确认已正确订阅主题，检查 QoS 设置和网络状态

Q: 应用崩溃？ A: 检查回调函数中的异常处理，避免在回调中执行耗时操作

Q: 自动重连不工作？ A: 确保 automaticReconnect 设置为 true，检查网络环境

📞 技术支持

如需技术支持或反馈问题，请通过以下方式联系：

• 留言即可

📄 许可证

本插件遵循 MIT 许可证，免费用于商业和非商业项目。

© 2025 HMW-MQTT Plugin. 专业的物联网通信解决方案.