更新记录

1.0.0（2026-07-19）

首发：自研高性能原生 MQTT 客户端核心，提供 uni-app 可调的异步 JS API：连接 MQTT broker，订阅/发布/取消订阅，入站消息走后台线程 p

平台兼容性

uni-app x(5.14)

nex-mqtt

自研高性能原生 MQTT 客户端核心，提供 uni-app 可调的异步 JS API。物联网设备上下行、实时推送、车联网首选。

仅 App 端（Android / iOS）。v1 仅明文 TCP（TLS / WebSocket 留后续项）。Android 需 android.permission.INTERNET。

形态

• 有状态对象：connectMqtt(opts) 工厂（异步）→ MqttClient 实例。一实例 = 一条 broker 连接，可并存多实例。
• 异步：连接/订阅/发布/取消订阅返回 Promise；pollMessages/isConnected/disconnect 为同步小方法。
• 入站走 poll-queue：原生后台线程跑事件循环，把订阅到的消息攒进有界队列；JS 定时调 pollMessages() 取走（drain）。
• 弱网自动重连（核心内建）；握手同步确认（连不上立即 reject）。

API

import { connectMqtt } from '@/uni_modules/nex-mqtt';

const client = await connectMqtt({
  host: '192.168.1.10',
  port: 1883,           // 默认 1883
  clientId: 'app-1',
  keepAliveSecs: 30,    // 默认 60，0 关闭心跳
  // username / password 可选
});

await client.subscribe('dev/+/up', 0);              // qos 0/1/2
await client.publish('dev/1/cmd', '{"on":true}', 1, false);  // topic, payload, qos, retain
await client.unsubscribe('dev/+/up');

// 定时轮询入站消息
const timer = setInterval(() => {
  const msgs = client.pollMessages();   // MqttMessage[]，无则 []
  for (const m of msgs) {
    console.log(m.topic, m.payload, m.qos);
  }
}, 500);

console.log(client.isConnected());      // boolean

// 退出
clearInterval(timer);
client.disconnect();

类型

type MqttOptions = {
  host: string;
  port?: number;          // 默认 1883
  clientId: string;
  keepAliveSecs?: number; // 默认 60
  username?: string;
  password?: string;
};

type MqttMessage = { topic: string; payload: string; qos: number };

错误（Promise reject / try-catch）

ConnectFailed（连不上/被拒）、Timeout（握手超时）、ConnectionLost（已断开/已 disconnect）、InvalidParam（端口越界、QoS>2）。

设计要点

• 入站消息先走 poll-queue（原生后台线程收、JS 轮询取），回调推送（poll-then-callback）为后续项。
• 入站队列有界（上限 1024，超限丢最旧），避免 JS 久不取导致内存无界增长。

验证状态

• 核心：连接 → 订阅 → 收消息 → pollMessages 往返全链路（MQTT 3.1.1）及多项异常边界均有自动化测试覆盖，出错抛可捕获错误、不闪退。
• v1 仅明文 TCP；TLS / WebSocket 为后续项，真机联调建议先对接自家 broker 环境验证。