更新记录

1.0.1（2026-08-09）

• 修复 P0 示例页崩溃：pages/index/index.uvue 漏导入 computed，导致页面 ReferenceError 白屏
• 修复 P0 Android 心跳死锁：原单线程池被读循环阻塞，心跳永不执行，后台长连被 Broker 断开；改独立心跳调度线程 + 读线程，disconnect() 释放心跳线程
• 修复 P1 iOS 假在线：写完 CONNECT 即置在线不读 CONNACK，改为校验 CONNACK 返回码
• 修复 P1 小程序 UTF-8 乱码：decodeUTF8 用 fromCharCode 逐字节拼导致中文乱码，改用 TextDecoder('utf-8')
• 修复 P2 Android 健壮性：CONNACK 读取加超时、报文按 remaining 整段消费，防粘包失步
• 修复 P2 Android 写流串行化：心跳与 publish 写同一 output 加 @Synchronized，避免字节交错
• 修复 P2 重连线程泄漏：替换旧 client 前 shutdown() 回收读/心跳线程
• 修复 P2 端口判断：port=0 时回退 URL 显式端口再回退协议默认端口
• 修复 P2 iOS 写流串行化 + 主线程回调：写操作统一串行队列，UTS 回调切主线程
• 修复 P1 小程序 WebSocket 子协议：connectSocket 增加 protocols: ['mqtt']，否则 broker 拒绝握手
• 修复 P2 Web 多余手动心跳：删除 pingreq 手动心跳（mqtt.js 已内置），避免重复 PINGREQ
• 落地 P3 enableBackground 真实语义：false 时退化为普通后台服务（无常驻通知）
• 新增 P3 开机自启 + 进程被杀恢复：BootReceiver + 配置持久化 + START_STICKY 重建连接
• 新增 P3 通知权限引导：Android 13+ 未授权时 onWarning(1003) 提示
• 三端在线语义统一：握手成功后才上报 online
• Demo 默认 Broker 按平台自适应：原生端 mqtt://:1883，Web/小程序 ws://:8083

1.0.0（2026-08-08）

• 首个版本
• Android：前台服务保活、WakeLock/WifiLock、网络监听、指数退避重连、SQLite 离线缓存补发、权限引导（电池白名单/自启动/应用详情/通知）
• iOS：后台任务 + 生命周期补偿 + MQTT(TCP/TLS) 客户端 + 内存离线缓存补发
• Web(H5)：mqtt.js(WebSocket) + 页面可见性休眠补偿
• 微信小程序：connectSocket(MQTT over WS) + onAppShow/Hide 生命周期补偿 + 内存离线缓存补发
• 统一 API：start / stop / resume / getStatus / publish / subscribe / getCacheCount / openBatteryOptimizationSettings / openAutoStartSettings / openAppDetailSettings / requestNotificationPermission

平台兼容性

uni-app x(4.75)

mqtt-keepalive

MQTT 全端后台保活 UTS 插件。UTS 原生底层接管保活逻辑，Android / iOS / Web(H5) / 微信小程序 四端统一 API，业务层零平台判断代码。

特性

• Android 原生保活：前台服务 + 常驻通知 + WakeLock 电源锁 + WifiLock + 网络监听 + 指数退避自动重连 + 原生 SQLite 离线消息缓存补发
• iOS 有限后台保活：后台任务申请 + 生命周期补偿 + MQTT 前台连接（iOS 系统限制严格，无法真正后台长连，推荐配合 APNs 静默推送唤醒）
• Web / 小程序休眠补偿：页面隐藏自动停心跳、回到前台秒级重建连接
• 离线消息缓存：设备上报、控制指令断线期间本地缓存，重连后按序批量补发，不丢数据
• 零三方原生依赖：MQTT 3.1.1 客户端为原生自研（Kotlin / Swift），不依赖 Paho 等 aar/framework，导入即用
• 权限引导：一键跳转电池优化白名单、厂商自启动管理、应用详情设置

导入

import { start, stop, getStatus } from '@/uni_modules/mqtt-keepalive'

快速开始

start({
  clientId: 'device_001',
  broker: 'mqtt://your-broker.com', // Android/iOS 支持 mqtt/mqtts/tcp/ssl；Web/小程序必须 ws/wss
  port: 1883,
  username: 'user',
  password: 'pass',
  heartInterval: 30,           // 后台心跳（秒）
  enableWakeLock: true,        // Android 电源锁
  foregroundTitle: '设备监控运行中',
  foregroundContent: 'MQTT 长连接保活中',
  cacheLimit: 500,             // 离线缓存上限（条）
}, {
  onStatusChange: (e) => {
    // e.status: connecting / online / reconnecting / offline / stopped
    console.log('状态变化', e.status, e.reason)
  },
  onMessage: (e) => {
    console.log('收到消息', e.topic, e.payload)
  },
  onCacheFlush: (e) => {
    console.log('离线缓存补发完成', e.count)
  },
  onWarning: (e) => {
    console.log('告警', e.code, e.message)
  },
})

API

start(options, callbacks)

启动 MQTT 保活。options 说明见 utssdk/interface.uts 的 MqttKeepAliveOptions。

stop()

停止保活并断开连接。

publish(options : MqttPublishOptions) : boolean

发布消息。离线时自动写入本地缓存，重连后按序补发（Android 存 SQLite，iOS 存内存，小程序存内存）。

publish({
  topic: 'device_001/cmd',
  payload: JSON.stringify({ action: 'open' }),
  qos: 1,        // 可选，默认取 start 配置
  retained: false, // 可选
})

subscribe(topics : string[], qos?) : boolean

订阅主题。

subscribe(['device_001/cmd', 'device_001/status'], 1)

getCacheCount() : number

获取当前离线缓存条数（未补发的消息）。

resume()

回到前台 / 收到推送时手动触发重连。iOS 平台在 APNs 静默推送唤醒应用时调用；其他平台已自动处理，保留此 API 供业务层显式触发。

// iOS 配合 uni-push：收到静默推送时唤醒重连
import { resume } from '@/uni_modules/mqtt-keepalive'
uni.onPushMessage((res) => {
  if (res.type === 'click' || res.type === 'receive') {
    resume()
  }
})

getStatus() : MqttKeepAliveSnapshot

返回 { status, reconnectCount, cacheCount }。

openBatteryOptimizationSettings()

跳转系统电池优化白名单设置（Android）。iOS/Web/小程序为打开设置页。

openAutoStartSettings()

跳转厂商自启动管理（Android 小米/华为/OPPO/vivo）。iOS/Web/小程序为打开设置页。

openAppDetailSettings()

跳转应用详情设置页。

requestNotificationPermission()

请求通知权限（Android 13+）。iOS 为订阅消息请求。

各端保活能力边界（重要）

iOS 后台保活需要服务端配合：设备离线时服务端通过 APNs 下发静默推送（content-available）唤醒 APP 重连同步。请在接入文档中如实向最终客户说明，避免售后纠纷。

主题约定

• 业务下发主题：${clientId}/cmd
• 离线补发主题：${clientId}/offline（可选，subscribeOffline=true 时订阅）

注意事项

• Web 平台依赖 mqtt npm 包：在插件目录 utssdk/web 下执行 npm install
• 小程序端建议 broker 使用 wss://（微信限制非安全域名连接）
• Android 前台通知不能由用户关闭，否则前台服务失效（保活中断）
• Android 12+ 需适配厂商自启动/后台活动权限，插件已提供引导跳转 API
• iOS 静默推送需服务端搭建推送通道，详见「各端保活能力边界」

常见问题

Q：锁屏后仍断线？ A：请确保已调用 openBatteryOptimizationSettings() 加入电池白名单，并允许常驻通知；部分厂商（小米/华为/OPPO/vivo）还需 openAutoStartSettings() 允许自启动。

Q：断线期间的数据会丢吗？ A：不会。Android 端设备上报与控制指令会写入原生 SQLite，重连后自动按序补发，onCacheFlush 回调告知补发数量。Web/小程序端依赖服务端离线缓存。

Q：iOS 能像 Android 一样后台常驻吗？ A：不能，这是 iOS 系统策略。请使用 APNs 静默推送唤醒方案，服务端需配合改造。