更新记录

1.1.0（2026-08-21）

• 新增 Will 遗嘱消息（四端统一）：willTopic / willPayload / willQos / willRetain，异常断线由 Broker 代为发布离线状态
• 新增 TLS 证书 cert：Android 作为信任锚点并校验主机名（防中间人），Web 透传 mqtt.js ca；证书解析失败直接连接失败，不静默降级
• 新增 Android 锁屏降耗：lockReleaseDelay 锁屏 N 秒后释放电源锁，亮屏/网络变化自动恢复，降低耗电与系统清理概率
• 新增 Android 凭据安全：账号/密码/证书经系统 Keystore（AES/GCM）加密落盘，不存明文
• 新增 Android 前台服务 dataSync 类型并声明 FOREGROUND_SERVICE_DATA_SYNC 权限（Android 14+ 兼容）
• 新增 Android 心跳动态调整：前台按 foregroundHeartInterval、后台按 heartInterval 发送 PINGREQ
• 修复 Android QoS2 完整闭环：SUBSCRIBE/SUBACK/PINGREQ 等报文常量越界修正，消息收发正确
• 修复 Web/小程序连接地址规范化：协议缺失时自动补 mqtt:///ws://，避免默认连接握手失败
• 修复小程序 QoS1/2 消息 ACK 回执缺失：收到消息正确回 PUBACK/PUBREC/PUBREL/PUBCOMP，消息不丢
• 修复断线重连固定间隔：改为指数退避 + 随机抖动，避免雪崩式重连
• 统一四端 onWarning 事件结构（code / message），并补齐必填参数、非法 QoS、协议不匹配等参数校验告警
• 统一 start() 热更新语义：已启动时重复调用先停旧连接，再按新配置重启
• 新增开机自启 + 进程被杀恢复能力说明完善
• 示例工程与文档同步更新（index.uvue、readme.md）

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,           // 心跳间隔（秒），作为 Broker 侧 keepalive 安全上限
  foregroundHeartInterval: 60, // 前台心跳（秒），App 处于前台时的实际发送频率
  enableWakeLock: true,        // Android 电源锁
  foregroundTitle: '设备监控运行中',
  foregroundContent: 'MQTT 长连接保活中',
  cacheLimit: 500,             // 离线缓存上限（条）
  willTopic: 'device_001/status', // 遗嘱主题：异常断线由 Broker 代为发布
  willPayload: 'offline',
  willQos: 1,
  willRetain: false,
  lockReleaseDelay: 60,        // 锁屏 60s 后释放电源锁省电（Android，亮屏自动恢复）
}, {
  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)
  },
})

start() 支持热更新：已启动时再次调用会先停止旧连接，再按新配置重启。

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+：原生请求 POST_NOTIFICATIONS。
• iOS：原生 UNUserNotificationCenter 申请可见通知权限（后台保活依赖 APNs 静默推送，本身无需授权）。
• Web：浏览器 Notification.requestPermission()。
• 小程序：无系统通知权限概念，引导打开设置页；订阅消息需在公众平台配置模板 ID 后由用户点击触发。

cert 证书支持范围

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

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

主题约定

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

注意事项

• Web 平台依赖 mqtt npm 包：在插件目录 utssdk/web 下执行 npm install
• 小程序端建议 broker 使用 wss://（微信限制非安全域名连接）
• Android 前台通知不能由用户关闭，否则前台服务失效（保活中断）
• Android 前台服务类型为 dataSync（需申请 FOREGROUND_SERVICE_DATA_SYNC 权限），锁屏后超过 lockReleaseDelay 会释放电源锁以降低耗电、减少被系统清理概率，亮屏或网络变化自动恢复
• Android 账号/密码/证书经系统 Keystore（AES/GCM）加密后落盘，不存明文；支持开机自启与进程被杀后的自动恢复
• Android 12+ 需适配厂商自启动/后台活动权限，插件已提供引导跳转 API
• iOS 静默推送需服务端搭建推送通道，详见「各端保活能力边界」
• QoS 支持：原生端（Android/iOS）与 Web 已实现 QoS0/1/2 完整协议闭环；小程序端为自研 WebSocket 报文，支持 QoS0/1/2（收到 QoS1/2 消息会正确回 ACK）

常见问题

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

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

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