更新记录

1.0.0（2026-02-05）

首发版本：支持 Android 前台服务保活、电池优化/自启动/通知引导，提供 iOS/鸿蒙后台任务骨架与能力探测。

平台兼容性

uni-app(4.11)

uni-app x(5.0)

其他

KeepAlive Guard 前台保活套件（uni-app x）

本项目是一个基于 uni-app x + UTS 的前台保活示例插件，名称暂定为 KeepAlive Guard，用于在合规前提下，尽量让 App 在后台稳定执行关键任务，同时提供可视化的诊断与引导能力。

说明：本插件不提供任何“绕过系统限制”的黑科技，只是在系统允许的能力范围内，把保活相关能力做成工程化、可观测、可配置的套件。

一、功能概述

• Android

  • 前台服务保活：通过 Service + startForeground 在关键任务期间提升进程优先级。
  • 通知与能力诊断：
  • 检测通知权限是否打开，并可跳转到应用通知设置页。
  • 提供“调试通知”按钮，发送一条普通通知，方便肉眼验证通知通路是否正常。
  • 保活引导：
  • 引导用户开启自启动/后台运行权限。
  • 引导用户加入电池优化白名单（忽略电池优化）。
  • 可选开启开机自启（通过 BootReceiver）。
  • 可观测诊断接口：
  • getStatus()：查看当前保活策略与运行状态。
  • getCapabilities()：查看当前平台支持的保活能力。
  • diagnoseAndroidKeepAlive()：综合 ROM、白名单、自启动、通知等给出建议列表。

• iOS / 鸿蒙

  • 不做违规“常驻保活”，仅提供：
  • 后台能力探测（bgTask 等方向）。
  • 合规后台任务骨架，方便后续按业务场景扩展。

二、运行与调试

1. 运行到 Android 真机

1. 使用 HBuilderX 打开本工程。
2. 通过菜单 “运行 → 运行到手机或模拟器”：
   • 首次请先选择 “制作自定义调试基座”，等待基座构建并安装到手机。
   • 之后选择该自定义基座运行。
3. 在 App 底部 Tab 页切换到 “KeepAlive” 页面。

2. 页面操作说明

在 pages/keepalive/keepalive.vue 页面，可以进行如下操作：

• 基础控制

  • 「启动前台服务 start()」：启动 Android 前台服务。
  • 「停止前台服务 stop()」：停止前台服务。
  • 「查看状态 getStatus()」：查看当前保活状态（platform/strategy/running）。
  • 「发送调试通知（普通通知）」：发送一条普通通知，验证通知通路是否正常。

• 定时检查（实时打印）

  • 「开启定时检查」：每 3 秒自动调用 getStatus()，并在 Android 上额外检查引导中 notifications 步骤的状态。
  • 「关闭定时检查」：停止定时器。

• Android 保活引导

  • 「加载引导 getKeepAliveGuide()」：拉取当前 ROM 下各步骤状态：
  • 前台服务是否开启。
  • 自启动/后台运行是否可引导。
  • 电池优化白名单状态。
  • 通知权限状态。
  • 开机自启状态。
  • 为每个步骤提供：
  • 「跳转系统设置」：打开对应系统页面（厂商管家、电池优化、通知设置等）。
  • 「我已完成 / 标记未完成」：用户手动标记步骤状态，解决无法可靠检测的场景。

• 一键测试所有功能

  • 调用插件提供的主要 API，并将结果打印到页面日志与控制台，方便一次性验证：
  • 状态 / 能力 / 诊断。
  • 引导步骤。
  • 白名单、自启动、通知相关 API。

三、API 列表与使用示例

1. 通用接口（多端可用）

引入方式（uni-app x 项目中）：
import * as keepAlive from '@/uni_modules/uts-keepalive-guard'

• start(options?: KeepAliveStartOptions): KeepAliveStartResult

  启动保活策略：

  • Android：启动前台服务，并按可选参数配置通知文案/渠道；
  • iOS/鸿蒙：标记为“已启用后台任务骨架”，不做违规常驻。

  import { start } from '@/uni_modules/uts-keepalive-guard'
  
  const res = start({
  android: {
    notificationTitle: '任务运行中',
    notificationContent: 'KeepAlive Guard 正在后台保护任务',
    notificationChannelId: 'uts-keepalive-guard-v2',
    notificationChannelName: 'KeepAlive Guard'
  }
  })
  console.log('start =>', res)

• stop(): KeepAliveStartResult

  停止保活策略（Android 会停止前台服务）：

  import { stop } from '@/uni_modules/uts-keepalive-guard'
  
  const res = stop()
  console.log('stop =>', res)

• getStatus(): KeepAliveStatus

  查询当前保活状态：

  import { getStatus } from '@/uni_modules/uts-keepalive-guard'
  
  const status = getStatus()
  // { running: boolean, platform: 'android' | 'ios' | 'harmony', strategy: string }
  console.log('keep alive status =>', status)

• getCapabilities(): KeepAliveCapabilities

  查询当前平台支持的保活能力：

  import { getCapabilities } from '@/uni_modules/uts-keepalive-guard'
  
  const caps = getCapabilities()
  // Android: { platform: 'android', android: { foregroundService: true, ... } }
  console.log('keep alive capabilities =>', caps)

2. Android 诊断与引导接口

• diagnoseAndroidKeepAlive(): AndroidKeepAliveDiagnosis

  综合 ROM、白名单、自启动、通知等返回诊断结果和建议：

  import { diagnoseAndroidKeepAlive } from '@/uni_modules/uts-keepalive-guard'
  
  const diag = diagnoseAndroidKeepAlive()
  console.log('diagnose =>', JSON.stringify(diag))

• getKeepAliveGuide(): AndroidKeepAliveGuide

  获取“保活引导步骤”（带状态）：

  import { getKeepAliveGuide } from '@/uni_modules/uts-keepalive-guard'
  
  const guide = getKeepAliveGuide()
  guide.steps.forEach(step => {
  console.log(step.id, step.status, step.title)
  })

• openKeepAliveGuide(stepId?: AndroidKeepAliveStepId): AndroidKeepAliveGuideOpenResult

  按步骤 ID 跳转到对应系统设置页（如自启动、电池优化、通知设置等）：

  import { openKeepAliveGuide } from '@/uni_modules/uts-keepalive-guard'
  
  // 例：引导用户打开电池优化白名单设置页
  const r = openKeepAliveGuide('batteryWhitelist')
  console.log('openKeepAliveGuide(batteryWhitelist) =>', r)

• markKeepAliveGuideStepDone(stepId) / markKeepAliveGuideStepTodo(stepId) / resetKeepAliveGuideStep(stepId) / resetKeepAliveGuide()

  手动标记或重置引导步骤状态，用于无法可靠检测的场景（如自启动）：

  import {
  markKeepAliveGuideStepDone,
  markKeepAliveGuideStepTodo,
  resetKeepAliveGuideStep,
  resetKeepAliveGuide
  } from '@/uni_modules/uts-keepalive-guard'
  
  markKeepAliveGuideStepDone('autoStart')
  markKeepAliveGuideStepTodo('autoStart')
  resetKeepAliveGuideStep('autoStart')
  resetKeepAliveGuide() // 重置全部步骤

• 电池优化 / 自启动 / 通知相关快捷接口

  import {
  isIgnoringBatteryOptimizations,
  requestIgnoreBatteryOptimizations,
  openIgnoreBatteryOptimizationsSettings,
  openAutoStartSettings,
  openAppDetailsSettings,
  getBootAutoStartEnabled,
  setBootAutoStartEnabled
  } from '@/uni_modules/uts-keepalive-guard'
  
  const ignoring = isIgnoringBatteryOptimizations()
  const reqRes = requestIgnoreBatteryOptimizations()
  const listRes = openIgnoreBatteryOptimizationsSettings()
  const autoStartRes = openAutoStartSettings()
  const appDetails = openAppDetailsSettings('从设置页打开应用通知')
  
  const bootOn = getBootAutoStartEnabled()
  const toggleRes = setBootAutoStartEnabled(true) // 开启开机自启（需用户授权/系统支持）

3. 调试通知（普通通知）

• showDebugNotification(): KeepAliveStartResult

  发送一条高优先级的普通通知，用于在复杂 ROM 上快速验证“通知通路是否正常”：

  import { showDebugNotification } from '@/uni_modules/uts-keepalive-guard'
  
  const res = showDebugNotification()
  console.log('debug notification =>', res)

四、权限与声明

Android 所需权限

• android.permission.FOREGROUND_SERVICE：启动前台服务。
• android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS：申请加入电池优化白名单。
• android.permission.RECEIVE_BOOT_COMPLETED：可选，启用开机自启功能时使用。
• android.permission.POST_NOTIFICATIONS（Android 13+）：发送通知。

iOS / 鸿蒙

当前版本仅做能力探测与后台任务骨架，不额外申请系统权限。

五、数据采集与隐私

• 插件本身 不采集任何用户个人数据，也 不会向任何服务器发送数据。
• 所有状态（电池优化、自启动、通知等）均在本地通过系统 API 获取，仅用于本机生成保活引导和诊断结果。
• 若你在自己的项目中集成其他第三方 SDK，请自行遵守对应 SDK 的隐私与合规要求。

六、注意事项与已知差异

• 不同厂商 ROM 对通知和后台策略差异较大：

  • 在部分华为机型上，普通通知可以正常显示，但前台服务通知可能被系统弱化/隐藏，即便权限已开启。
  • 本项目已提供「调试通知（普通通知）」按钮，用于验证通知通路是否正常。
  • 在这种 ROM 上，可通过「running 状态 + 调试通知可见」来判断前台服务是否真实运行。

• iOS / 鸿蒙 不支持 Android 式的“前台服务常驻通知”，请根据业务场景选择合规的后台模式（如音频、定位、BGTask 等）。

七、适用场景示例

• 需要在 Android 上进行：

  • 长时间任务（上传/下载/同步）；
  • 定时轮询或心跳；
  • 对任务可靠性有较高要求的业务。

• 同时希望：

  • 通过统一的 JS/UTS 接口在多端获取保活能力与状态；
  • 在设置页/引导页中，清晰提示用户如何开启自启动、白名单、通知等。