更新记录

1.0.0（2026-09-21）

首个公开发布版本。支持 Android 8.0（API 26）及以上，适用于 uni-app Vue 2、uni-app Vue 3 与 uni-app x。功能与用法见 readme。

• 前台服务启动、更新与幂等停止；通知渠道、小图标、可点击停止操作与通知点击 payload。
• 状态查询与监听，含结构化错误码；getKeepAliveConfig 读取持久化配置。
• 可选 WakeLock 与 Wi-Fi Lock，支持 1 秒至 7 天超时，超时、停止、失败与销毁路径均释放。
• 统一事件监听，以及最多 50 条的本机事件历史。
• 后台诊断与就绪度评分，含 Android 11+ 最近一次进程退出记录。
• 厂商后台设置识别与导航，重点适配 Xiaomi/华为/荣耀/OPPO/vivo/三星等；入口失败时回退标准系统页面。
• 通知权限、通知设置与电池优化设置的查询与跳转。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

hans-keepalive

Android 前台服务与后台运行管理 UTS 插件。它通过持续可见的系统通知提高宿主任务在后台运行的可预期性，但不保证进程永不被系统或厂商策略终止。

平台支持

• 插件仅提供 Android 实现，最低 Android 8.0（API 26）。
• uni-app 与 uni-app x 使用同一个插件包，公共 API 名称、结果字段和错误语义一致。
• iOS、HarmonyOS、小程序和 Web 不在本插件的支持范围内，请勿在这些平台依赖本插件的任何返回行为。

安装

插件 ID 为 hans-keepalive。

• 从插件市场导入：在 HBuilderX 中导入到项目的 uni_modules 目录。
• 手动安装：将 uni_modules/hans-keepalive 整个目录放入项目根目录的 uni_modules 下。

import { startKeepAlive } from '@/uni_modules/hans-keepalive'

权限与宿主配置

插件的 AndroidManifest.xml 已声明下列权限与前台服务，宿主不需要重复声明：

前台服务以 specialUse 类型注册，并带有 PROPERTY_SPECIAL_USE_FGS_SUBTYPE 说明。

宿主仍需自行完成：Android 14+ 要求 specialUse 的用途与真实业务相符，发布前必须按实际持续后台任务复核 Manifest subtype，并在目标商店完成对应声明。插件不保证任意保活用途可通过审核。

插件不申请 REQUEST_IGNORE_BATTERY_OPTIMIZATIONS，也不会自动修改任何系统设置。

使用边界

• 用户"强行停止"应用后，插件不能自行恢复。
• Android 没有统一公开 API 可以读取厂商"自启动"开关。插件不会把厂商设置页包装成可查询权限。
• 插件不包含 SSE、WebSocket、TCP、定位、录音或其他业务任务。
• WakeLock 和 Wi-Fi Lock 默认关闭，仅在业务确有必要时开启。

基本调用

uni-app x

import {
  startKeepAlive,
  stopKeepAlive,
  getKeepAliveState,
  getKeepAliveConfig,
  getBackgroundDiagnostics,
  getBackgroundReadiness,
  updateKeepAliveNotification,
  getRecentKeepAliveEvents,
  getLastNotificationInteraction,
  onKeepAliveStateChange,
  offKeepAliveStateChange,
  onKeepAliveEvent,
  offKeepAliveEvent,
  getManufacturerBackgroundInfo,
  openManufacturerBackgroundSettings,
  openManufacturerBackgroundHelp,
  KeepAliveState,
  KeepAliveEvent,
} from '@/uni_modules/hans-keepalive'

const stateListener = (state : KeepAliveState) : void => {
  console.log('keep alive state', state.status)
}

const eventListener = (event : KeepAliveEvent) : void => {
  console.log('keep alive event', event.type, event.timestamp)
}

onKeepAliveStateChange(stateListener)
onKeepAliveEvent(eventListener)

startKeepAlive({
  notification: {
    channelId: 'my_background_task',
    channelName: '后台任务',
    channelDescription: '用户主动启动的持续后台任务',
    title: '后台任务运行中',
    content: '点击返回应用',
    smallIconResourceName: 'ic_stat_background',
    showStopAction: true,
    stopActionText: '停止',
    clickPayload: 'order-sync',
  },
  wakeLockEnabled: false,
  wakeLockTimeoutMs: null,
  wifiLockEnabled: false,
  wifiLockTimeoutMs: null,
  processStateSummaryEnabled: false,
  success: (state) => {
    console.log('启动请求已提交', state.status)
  },
  fail: (err) => {
    console.error('启动失败', err.errCode, err.errMsg)
  },
})

console.log(getKeepAliveState().status)
console.log(getKeepAliveConfig().notification.channelId)
console.log(getBackgroundDiagnostics().standbyBucket)
console.log(getBackgroundReadiness().score)
console.log(getRecentKeepAliveEvents(20).length)
console.log(getLastNotificationInteraction()?.payload ?? null)
stopKeepAlive()
offKeepAliveStateChange(stateListener)
offKeepAliveEvent(eventListener)

uni-app Vue 2 / Vue 3

同样的调用，普通 <script> 中不需要类型标注：

import { startKeepAlive, onKeepAliveStateChange, onKeepAliveEvent } from '@/uni_modules/hans-keepalive'

const stateListener = (state) => {
  console.log('keep alive state', state.status)
}

const eventListener = (event) => {
  console.log('keep alive event', event.type, event.timestamp)
}

onKeepAliveStateChange(stateListener)
onKeepAliveEvent(eventListener)

startKeepAlive({
  notification: { title: '后台任务运行中', content: '点击返回应用' },
  success: (state) => console.log(state.status),
  fail: (err) => console.error(err.errMsg),
})

类型标注规则（仅 uni-app x）：UTS 要求参数与返回值必须标注类型，所以独立声明的回调（如上面的 stateListener、eventListener）需要写全 (state : KeepAliveState) : void，并导入对应类型。而作为选项字段传进去的回调（success、fail 等）可以从 StartKeepAliveOptions、OpenSystemSettingsOptions 等类型推断出来，不需要再标注。其余示例同此规则。

仅更新通知，不改变锁和进程摘要配置：

updateKeepAliveNotification({
  notification: {
    title: '同步进行中',
    content: '已完成 60%',
    clickPayload: 'order-sync',
  },
  success: (state) => console.log(state),
})

按厂商打开后台运行设置：

const info = getManufacturerBackgroundInfo()
console.log(info.family, info.supportLevel, info.recommendedTarget)

openManufacturerBackgroundSettings({
  target: 'recommended',
  success: (result) => {
    console.log(result.openedTarget, result.destination, result.fallbackUsed)
  },
})

openManufacturerBackgroundHelp({
  success: (result) => console.log(result.url),
})

默认值

startKeepAlive 与 updateKeepAliveNotification 的字段全部可选，未传或传空字符串时使用：

参数校验

校验不通过的字段会以错误码 9012002 失败，errMsg 指明具体字段。约束如下：

getRecentKeepAliveEvents(limit) 的 limit 范围为 1..50。

API

• startKeepAlive(options)：提交启动请求；已运行时更新通知和锁配置。success 表示 Android 已接受请求，最终进入 running 或 failed 应通过状态监听或 getKeepAliveState() 确认。
• stopKeepAlive(options?)：幂等停止，清除恢复标记并释放插件持有的锁。
• getKeepAliveState()：读取服务、恢复标记、权限、通知渠道、锁、锁获取/超时时间和最近结构化错误。desiredRunning 只表示持久化恢复意图；新进程中服务尚未收到启动命令时，可能出现 status: 'stopped' 且 desiredRunning: true。
• getKeepAliveConfig()：读取当前持久化配置，适合页面重建后恢复表单。
• getBackgroundDiagnostics()：读取后台限制、省电、Doze、App Standby Bucket、电量、网络、低存储状态，以及 Android 11+ 最近一次主进程退出原因。
• getBackgroundReadiness()：返回 0..100 分、是否就绪和结构化阻断/提醒项；它是配置诊断，不承诺进程不会被终止。
• updateKeepAliveNotification(options)：独立更新通知字段，不改变锁配置；仅 clearClickPayload: true 会显式清除已有点击 payload。
• getLastNotificationInteraction() / clearLastNotificationInteraction()：读取或清除最后一次通知点击，支持进程冷启动后读取。
• getRecentKeepAliveEvents(limit?) / clearKeepAliveEvents()：读取或清除最近事件。
• onKeepAliveStateChange(callback) / offKeepAliveStateChange(callback?)：监听或移除状态监听；重复注册同一个回调不会重复触发。
• onKeepAliveEvent(callback) / offKeepAliveEvent(callback?)：统一监听服务、锁、屏幕、应用前后台与通知事件；实时回调只在当前进程存活时有效。
• checkNotificationPermission() / requestNotificationPermission(options)：查询和请求 Android 13+ 通知权限。
• openNotificationSettings(options?) / openBatteryOptimizationSettings(options?)：打开系统设置；支持 success、fail、complete。
• isIgnoringBatteryOptimizations()：查询当前应用是否已忽略电池优化。
• getManufacturerBackgroundInfo()：识别厂商系列、适配级别和推荐设置目标。
• openManufacturerBackgroundSettings(options?)：由用户操作触发厂商自启动或耗电设置导航，并返回实际入口及是否发生回退。
• openManufacturerBackgroundHelp(options?)：打开当前厂商对应的 DontKillMyApp 官方指南；插件不抓取或内嵌其内容。
• setLogEnabled(enabled) / isLogEnabled()：控制插件诊断日志。

枚举值

status（KeepAliveStatus）：stopped | starting | running | stopping | failed

event.type（KeepAliveEventType）：serviceStarting | serviceRunning | serviceStopping | serviceStopped | serviceDestroyed | serviceFailed | operationFailed | taskRemoved | wakeLockTimedOut | wifiLockTimedOut | notificationClicked | notificationUpdated | screenOn | screenOff | appForeground | appBackground

readiness.issues[].code（KeepAliveReadinessIssueCode）：notificationPermissionNotGranted | notificationsDisabled | notificationChannelDisabled | backgroundRestricted | batteryOptimizationActive | standbyRestricted | powerSaveModeActive | deviceIdleModeActive | manufacturerSetupRecommended

readiness.issues[].severity：blocker | warning

readiness.issues[].action：notificationSettings | batteryOptimizationSettings | manufacturerSettings | none

manufacturer.supportLevel（ManufacturerBackgroundSupportLevel）：supported | experimental | standard | unsupported

manufacturerSettings.openedTarget（ManufacturerBackgroundOpenedTarget）：autoStart | battery | applicationDetails

diagnostics.standbyBucket（KeepAliveAppStandbyBucket）：exempted | active | workingSet | frequent | rare | restricted | never | unknown

错误码

fail(err) 回调中 err.errSubject 为 hans-keepalive，err.errCode 为下列值之一，err.errMsg 默认英文。

厂商后台设置

重点适配：Xiaomi/Redmi/POCO、Huawei、Honor、OPPO、Realme、OnePlus、vivo/iQOO、Samsung。实验性适配：ASUS、Meizu、TECNO/Infinix/itel、nubia、ZTE、Lenovo/ZUI、Nokia、LeTV，以及只有 DontKillMyApp 指南的 Motorola、Sony、Wiko、Blackview、Ulefone/RugOne、Unihertz。HTC 同样为实验性。Google/Pixel 归类为标准 AOSP。其余厂商标记为 standard 或 unsupported。

• target 支持 recommended、autoStart 和 battery。插件会依次尝试当前厂商已知入口；入口不存在或被系统禁止时，回退到 Android 单应用电池页或应用详情页。
• 返回成功只表示系统接受了页面跳转，不表示用户已经开启自启动或后台白名单。
• 厂商组件会随 ROM 版本变化，"重点适配"表示有明确候选路径，不表示已覆盖该厂商全部系统版本。发布前仍需在目标设备验证。

注意事项

锁超时：wakeLockTimeoutMs 和 wifiLockTimeoutMs 为空时不设置超时。锁超时后服务仍继续运行，只释放对应锁并更新状态。Wi-Fi Lock 不会隐式附带 CPU WakeLock；设备在名义截止时间处于深度休眠时，释放会推迟到主线程恢复执行或下次亮屏。长时间锁会显著增加耗电，应优先设置与真实任务相符的最短时限。

通知权限：权限被拒绝不等同于前台服务无法启动。Android 仍会向系统提交前台服务通知，但通知抽屉中的可见性受系统版本和用户设置影响。

小图标：smallIconResourceName 必须是宿主 drawable 或 mipmap 中的小写 Android 资源名，不带目录和扩展名。找不到指定资源时会回退到宿主应用图标；正式应用应提供符合 Android 状态栏规范的单色小图标。

通知停止操作：默认开启。用户点击后，插件清除恢复标记、释放 WakeLock/Wi-Fi Lock、移除前台通知并停止服务。

进程退出记录：lastProcessExit 可能为 null。退出原因由 Android 系统历史记录提供，可区分低内存、Java/Native 崩溃、ANR、资源使用过量、用户停止、依赖进程死亡、系统 freezer 和应用更新等情形。该记录是有限长度的系统环形历史，不应当作永久审计日志。

进程状态摘要：processStateSummaryEnabled 默认关闭；开启后只在 Android 11+ 写入版本、服务状态、恢复标记、锁状态和更新时间，不得用于保存业务或隐私数据。它是进程级共享槽位，可能与宿主中的崩溃或诊断 SDK 互相覆盖。写入失败不会影响服务生命周期。

数据存储：事件历史最多保留 50 条，只用于本机短期诊断并可由调用方清除。持久化事件不保存通知 payload；最后一次通知点击会单独保存调用方设置的 payload，最长 1024 字符，因此不要放入令牌、密码、身份证号或其他敏感数据。插件不进行远程上传。