更新记录

1.0.0（2026-08-13）

• 由原生 aar 插件（KeepAliveModule.java / KeepAliveService.java）移植为 UTS 插件
• 功能等价：前台 Service + WakeLock + 心跳 TCP + 自动重连 + pong 反馈
• 云服务器已配置，interval 限制 10~120（超范围默认 60）
• 首次发布

平台兼容性

uni-app(3.8.2)

uni-app x(3.91)

其他

ZXB-KeepAlive 后台保活插件 (UTS)

超长时间后台保活原生插件：前台 Service + WakeLock + 心跳 TCP + 自动重连 + pong 反馈，实测 51 小时+（直至手机电池耗尽）。

本插件由原生 aar 插件（KeepAliveModule.java / KeepAliveService.java）移植为 UTS 插件，最终产物为源码形式的 uni_modules 插件，无需手动集成 aar。

平台支持

安装

将 uni_modules/ZXB-KeepAlive 目录复制到你的 uni-app 项目的 uni_modules 目录下即可。

由于涉及 AndroidManifest 配置（Service 声明），需要 自定义基座 才能生效。

快速开始

// 引入插件
import { startKeepAlive, stopKeepAlive, onPongReceived } from '@/uni_modules/ZXB-KeepAlive'

// 1. 注册 pong 回调（可选，收到服务器心跳响应时触发）
onPongReceived((count) => {
  console.log('收到 pong，累计次数：', count)
})

// 2. 开始保活
startKeepAlive({
  port: 15678,        // 服务器端口（默认 15678）
  interval: 15,       // 心跳间隔秒数，限制 10~120，超范围自动用 60（默认 15）
  key: 'MyKey2026'    // 加密密钥（默认 MyKey2026）
})

// 3. 停止保活
stopKeepAlive()

参数说明

权限声明

插件已在 AndroidManifest.xml 中声明：

• android.permission.FOREGROUND_SERVICE（前台服务）
• android.permission.WAKE_LOCK（唤醒锁）
• android.permission.INTERNET（网络）
• android.permission.ACCESS_NETWORK_STATE（网络状态）
• android.permission.FOREGROUND_SERVICE_SPECIAL_USE（Android 14 前台服务类型）

与服务器协议

• 连接：TCP 长连接到云端服务器。
• 心跳：每 interval 秒发送 Heartbeat（XOR + Base64 加密）
• 响应：服务器回复 pong（同样加密），收到后刷新 lastPong 时间
• 重连：35 秒未收到 pong 自动重连

注意事项

1. 自定义基座：本插件修改了 AndroidManifest.xml（注册 Service），必须打自定义基座调试
2. Android 14：已声明 FOREGROUND_SERVICE_SPECIAL_USE 类型；部分 ROM（小米/华为等）可能需要在系统设置中允许自启动
3. 省电策略：如遇进程被杀，建议引导用户在系统设置中将应用加入电池优化白名单（即：不允许电池优化）
4. UTS 编译：Android 端 UTS 语法编译为 Kotlin，若 HBuilderX 报错请检查 UTS 版本

版本历史

• v1.0.0（2026-08-12）：由 aar 插件移植为 UTS 插件，功能等价