更新记录

1.0.0（2026-06-17）

首次提交

平台兼容性

uni-app(4.86)

uni-app x(4.86)

hl-keep-alive-uts (进程保活与系统防杀插件)

新手必读：
首次使用 UTS 插件，请优先阅读 《UTS 插件新手使用与调试指南》。

简介

hl-keep-alive-uts 是一款旨在提升应用在后台运行存活率的 UTS 原生控制插件。通过结合系统的合法驻留机制与电池优化配置向导，适用于即时通讯、心跳长连接、后台持续监听等核心业务场景，降低因系统休眠策略导致的网络中断与进程终止风险。

核心特性

• 跨平台后台驻留机制：
  • Android 端：基于原生前台常驻服务 (ForegroundService) 与电源锁 (WAKE_LOCK) 维持应用活跃。
  • iOS 端：采用静默音频流播放（AudioSession）配合后台任务续期机制，延长应用在挂起状态下的存活时间。
• 系统电池优化向导：提供接口主动唤起 Android 系统的“忽略电池优化”授权界面，避免因 Doze 模式造成的网络连接挂起。
• 厂商白名单向导引擎：集成国内主要 Android 厂商（华为、小米、OPPO、vivo 等）的深层设置跳转逻辑，直接引导用户至“自启动管理”或“后台耗电管理”页面，降低业务配置门槛。
• 常驻通知自定义：支持自定义 Android 状态栏常驻通知的标题与内容文本，符合不同的业务提示需求。

快速接入

1. 引入与初始化

import * as HlKeepAlive from '@/uni_modules/hl-keep-alive-uts'

const controller = HlKeepAlive.createKeepAliveController()

// 监听保活引擎状态变更
controller.onState((state) => {
  console.log(`保活状态更新: ${state.message}`)
})

// 监听底层保活拦截日志
if (controller.onLog) {
  controller.onLog((log) => {
    console.log(`[引擎日志 ${log.level}]: ${log.message}`)
  })
}

2. 启动与停止保活服务

// 启动保活
controller.start({
  title: '通讯服务运行中',        // [Android] 常驻状态栏标题
  content: '正在保持网络连接稳定...', // [Android] 常驻状态栏描述
  enableSilentAudio: true         // [iOS/Android] 是否开启底层静默音频循环播放保活
})

// 停止保活并释放资源
controller.stop()

3. 配置电池优化豁免 (Android)

针对 Android 6.0 引入的 Doze 模式，应用需要向用户申请忽略电池优化授权。

// 检查是否已经在白名单
if (!controller.isIgnoringBatteryOptimizations()) {
  // 主动唤起系统级授权弹窗，用户点击允许即可
  controller.requestIgnoreBatteryOptimizations()
}

4. 厂商白名单深层跳转向导

对于部分实行严格后台限制的定制系统，可通过代码引导用户进入系统设置页开启“自启动”和“后台运行”。

// 方案 A：自动化向导跳转
// 插件会自动分析当前手机品牌（如华为、小米等），并跳转至对应的底层设置界面
controller.guideToAllWhiteLists()

// 方案 B：直接跳转自启动设置页
controller.jumpToAutoStartSettings()

(说明：iOS 端不存在自启动与电池白名单概念，在 iOS 平台调用以上向导接口时，插件内部会自动降级调用 jumpToSettings 打开 iOS 系统的应用专属设置中心。)

上架提示

关于静默音频保活：iOS 对应用在后台长时间存活的控制较为严格。利用静默音频绕过墓碑机制在提交 App Store 审核时可能会面临退回风险。建议在审核期间将 enableSilentAudio 设置为 false，并在审核通过后通过业务接口动态调整开启。