更新记录

1.2.9（2026-06-26）

-优化ios

1.2.8（2026-06-26）

-优化

1.2.7（2026-06-14）

-修复鸿蒙issues

平台兼容性

uni-app(4.18)

uni-app x(4.18)

ly028-KeepLive

uni-app / uni-app x UTS 原生保活插件：防止 App 在后台被系统回收。支持 Android 前台服务 + WakeLock + 通知点击唤起 + JobScheduler / AlarmManager 周期拉活 + 开机恢复、iOS 后台定位 + 音频 + BGTaskScheduler + 本地通知、HarmonyOS 后台任务 + 常驻通知 + 后台定位 + 审计日志。

提供统一的 register / unregister / isRunning API，各平台差异通过 getCapabilities() 查询。

点击下载体验

扫码体验

平台支持

• 环境：uni-app 建议 HBuilderX 3.7.2+；uni-app x 建议 HBuilderX 4.0+（鸿蒙建议 4.31+）
• 调试：原生 UTS 插件必须进入 自定义调试基座 或 正式云打包 才能运行；普通标准基座不包含本插件原生代码
• 定价：插件市场 免费

快速开始

1. 安装

在 DCloud 插件市场 搜索 ly028-KeepLive，导入到项目 uni_modules 后：

1. 确认 manifest.json 已配置正确的 AppID
2. 制作自定义调试基座 → 运行到自定义基座（真机）
3. 各平台按 平台配置 章节完成额外配置

2. uni-app x / UTS 调用

import { register, unregister, isRunning } from '@/uni_modules/ly028-KeepLive'
import type { KeepAliveOptions } from '@/uni_modules/ly028-KeepLive'

// 启动保活
register({
  channelId: 'keepalive_channel',
  channelName: '保活服务',
  title: 'App 运行中',
  content: '正在保持后台运行，不会影响您使用其他应用'
})

// 检查状态
const alive = isRunning()
console.log('保活状态:', alive)

// 停止保活
unregister()

3. uni-app (Vue2/Vue3) 调用

import { register, unregister, isRunning } from '@/uni_modules/ly028-KeepLive'

register({
  channelId: 'keepalive_channel',
  channelName: '保活服务',
  title: 'App 运行中',
  content: '正在保持后台运行'
})

API

register(options) → void

注册保活服务。Android 自动获取 WakeLock 并启动前台服务；iOS 注册 BGTaskScheduler + 请求通知权限 + 持久化标记；鸿蒙申请后台任务 + 常驻通知 + CPU 唤醒 + 开机监听。各平台都接受 debug 参数控制日志输出。

unregister() → void

注销保活服务。释放 WakeLock、停止前台服务、取消后台任务。

isRunning() → Boolean

检查保活服务是否正在运行。

getCapabilities() → KeepAliveCapability

获取当前平台的保活能力列表。

import { getCapabilities } from '@/uni_modules/ly028-KeepLive'

const caps = getCapabilities()
console.log(caps.foregroundService) // Android/HarmonyOS: true, iOS: false
console.log(caps.backgroundLocation) // iOS: true, others: false

返回字段：

Android 特有 API

import {
  openBatteryOptimizationSettings,
  getNotificationVisible,
  setNotificationVisible,
  checkNotificationPermission,
  openNotificationSettings,
  restoreKeepAlive,
  unregisterAndClear,
  startPeriodicTask,
  stopPeriodicTask,
  isPeriodicTaskRunning,
  getLastPeriodicTaskError,
  startAlarmRevive,
  stopAlarmRevive,
  isAlarmReviveRunning,
  getLastAlarmReviveError,
  canScheduleExactAlarms,
  openExactAlarmSettings,
  restoreReviveTasksFromPrefs,
  getAndroidKeepAliveState,
  getOemBatteryGuidance,
  getKeepAliveReviveLog,
  getPluginStartTime,
  getPluginRunningDurationMs,
  moveAppToBackground,
  setExcludeFromRecents,
  updateNotificationContent
} from '@/uni_modules/ly028-KeepLive'

// 跳转电池优化设置（Android 6+）
// 引导用户将本应用设为「不优化」
openBatteryOptimizationSettings()

// 通知栏可见性控制
const visible = getNotificationVisible()  // 当前是否显示通知
setNotificationVisible(false)             // 隐藏通知（仅 WakeLock 保活）
setNotificationVisible(true)              // 重新显示通知

// 通知权限检查（Android 13+）
const granted = checkNotificationPermission()
if (!granted) {
  openNotificationSettings()  // 跳转应用通知设置页
}

  // 从已保存配置自动恢复保活（用于 App 启动后同步状态）
  const restored = restoreKeepAlive()

  // 注销保活 + 清除开机自启配置（重启后不再自动恢复）
  unregisterAndClear()

说明：

• register() 后若通知已显示，点击通知可唤起应用主界面（ContentIntent）。
• 定时任务 / 闹钟拉活为辅助手段，须先 register()；配置持久化后，开机与 restoreKeepAlive() 会一并尝试恢复。

Android 保活手段矩阵

iOS 特有 API

import {
  startLocation, stopLocation, startMusic, stopMusic,
  checkLocationPermission, checkNotificationPermission,
  openNotificationSettings, restoreKeepAlive,
  updateNotificationContent, getKeepAliveReviveLog
} from '@/uni_modules/ly028-KeepLive'

// 定位保活（需用户授予「始终允许」定位权限）
startLocation({
  distanceFilter: 100,   // 更新距离（米），默认 100
  desiredAccuracy: 100   // 精度，默认 kCLLocationAccuracyHundredMeters
})
stopLocation()

// 音频保活（需在 Bundle 中放入 keepalive_silent.wav 无声音频文件）
startMusic()
stopMusic()

// 检查定位授权状态
const status = checkLocationPermission()  // 返回中文描述

// 通知权限检查 + 跳转设置
const hasPermission = checkNotificationPermission()
if (!hasPermission) {
  openNotificationSettings()
}

// 从本地配置恢复保活状态
const restored = restoreKeepAlive()

// 发布本地通知（register 时会请求通知权限，退到后台或前台都会显示横幅）
updateNotificationContent('保活状态', '后台服务运行中')

// 获取拉活审计日志（需 register 时 debug: true）
const logs = getKeepAliveReviveLog()

平台配置

Android

插件已自动声明以下权限（在 AndroidManifest.xml）：

开机与拉活任务恢复：

1. register() 将保活配置写入 SharedPreferences。
2. 若已调用 startPeriodicTask() / startAlarmRevive() 且成功，对应开关会写入 SP。
3. 手机重启后 BootReceiver → 恢复前台服务 + JobScheduler + AlarmManager。
4. App 冷启动可调用 restoreKeepAlive() 同步前台服务，并调用 restoreReviveTasksFromPrefs() 恢复定时/闹钟。

拉活审计与 WakeLock 区别：

• register({ debug: true }) 会将 debug_enabled 写入 SP；此后 Boot/Job/Alarm/START_STICKY 触发的前台 Service 恢复会写入 getKeepAliveReviveLog()（debug: false 时不记录）。
• Job/Alarm/Boot 等不会在进程被杀后自动重新获取 WakeLock；WakeLock 仅在 App 进程内 register() / restoreKeepAlive() 成功时记录 wakelock_acquire 事件。

Android 13+ (API 33) 通知权限说明：

Android 13 及以上版本将 POST_NOTIFICATIONS 列为运行时权限，用户可以在系统设置中开关。如果通知不显示：

1. 使用 checkNotificationPermission() 检查权限状态
2. 未授予时调用 openNotificationSettings() 跳转到应用通知设置页
3. 用户手动开启后，重新注册前台服务即可显示常驻通知

插件采用「按需检查」策略：注册保活时不拦截通知权限，前台服务/通知控制按钮在点击时才动态检查并引导开启。

Android 6+ 电池优化说明：

部分厂商会强制休眠后台应用，即使有前台服务也可能受影响。建议引导用户：

1. 调用 openBatteryOptimizationSettings() 跳转到电池优化设置
2. 将本应用设为「不优化」

iOS

需要在项目的 info.plist 中添加：

<key>UIBackgroundModes</key>
<array>
    <string>location</string>
    <string>audio</string>
</array>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>保活需要在后台持续获取位置更新</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>需要定位权限以支持后台保活</string>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.yourapp.keeplive.refresh</string>
</array>

定位权限请使用 requestAlwaysAuthorization，仅 requestWhenInUseAuthorization 无法在后台持续获取位置。

⚠️ App Store 审核提示：

• 后台定位功能需要在审核时说明合理的使用理由
• 音频保活建议在 App 中有实际的音频播放上下文
• BGTaskScheduler 需声明使用目的

HarmonyOS

插件已自动声明以下权限（在 module.json5 中）：

• ohos.permission.KEEP_BACKGROUND_RUNNING — 后台运行
• ohos.permission.RUNNING_LOCK — CPU 唤醒锁
• ohos.permission.LOCATION — 后台定位（可选，使用 startLocation 时需授予）
• ohos.permission.LOCATION_IN_BACKGROUND — 后台持续定位

如需使用后台定位或音频保活，还需在入口模块的 module.json5 中配置 backgroundModes：

{
  "module": {
    "abilities": [{
      "name": "EntryAbility",
      "backgroundModes": ["location", "audioPlayback"]
    }]
  }
}

注意事项

Android 版本兼容

Android 厂商适配

• 不同手机厂商（华为、小米、OPPO、vivo、三星、中兴、传音、Google 等）的后台管理策略不同
• 调用 getOemBatteryGuidance() 获取结构化引导文案，在前端自定义弹窗或设置页展示
• register({ debug: true }) 时仍会将相同引导输出到 UTS 日志（debug: false 时静默）
• 建议引导用户将 App 加入厂商的「受保护应用」或「自启动」白名单

OemBatteryGuidance 字段：brand（归一化 key，如 xiaomi）、manufacturer（展示名）、guideContent（多行引导正文）、rawManufacturer / rawBrand（原始设备信息）。

iOS 限制

• iOS 系统对后台活动有严格限制，保活效果不如 Android
• 定位保活会持续消耗电量，建议仅在对定位实时性要求高的场景使用
• 音频保活建议在合适的时机启动，避免影响用户体验
• 通知使用说明：updateNotificationContent() 发布的是本地通知，非 Android 常驻通知栏。
  • register() 时会自动弹出通知权限请求弹窗，请选择「允许」
  • 通知在 App 退到后台或以任何方式在前台时都会显示横幅
  • iOS 通知中心会保留最近的通知记录，下滑可查看历史
  • 如果没看到通知，请检查：设置 → 通知 → 本应用 → 允许通知

HarmonyOS 限制

• 后台任务有系统时间限制（约 6~10 分钟），到期后会回调过期事件
• 插件在过期回调中会自动重新申请后台任务
• 后台定位需要用户在系统设置中授予位置权限（始终允许）
• 无声音频保活和 WorkScheduler 周期拉活功能需 SDK 版本支持，当前标记为暂不可用
• 开机自启恢复功能为实验性，可能受鸿蒙 NEXT 系统限制
• 鸿蒙 NEXT 版本可能有 API 变更，请关注适配

常见问题

Q：unregister() 和 unregisterAndClear() 有什么区别？
A： 仅停止保活、释放资源，但保留注册配置到 SharedPreferences。如果用户重启手机，BootReceiver 会自动恢复前台服务。 在停止保活的同时清除所有保存的配置，重启后不会自动恢复。

Q：保活一定能防止 App 被杀吗？
A：不能保证 100% 保活。保活是提升 App 进程优先级，降低被系统杀死的概率。极端情况下（内存不足、厂商强杀）仍可能被杀死。

Q：注册后通知栏没有常驻通知？
A：请检查：① 是否使用自定义调试基座/正式包（标准基座不生效）；② Android 13+ 是否已开启通知权限（可调用 checkNotificationPermission() 检测）；③ register 参数是否正确。

Q：Android 13+ 通知权限怎么处理？
A：插件提供 checkNotificationPermission() 和 openNotificationSettings() 两个 API，你可以在需要显示通知的时机（如点击「前台服务」按钮时）动态检查权限，未开启时引导用户前往系统设置打开。注册保活本身不拦截权限。

Q：前台服务通知可以隐藏吗？
A：可以。调用 setNotificationVisible(false) 隐藏通知栏常驻通知，此时 WakeLock 持续保活但进程优先级会降低。需要重新显示时调用 setNotificationVisible(true)。register() 不会替你自动关闭通知，显隐由业务侧按需调用。

Q：JobScheduler / 闹钟拉活怎么用？重启还有效吗？
A：先 register()，再 startPeriodicTask(15) 或 startAlarmRevive(15)（间隔不得小于 15 分钟）。成功后会持久化到 SP，重启手机由 BootReceiver 恢复；App 启动可再调 restoreReviveTasksFromPrefs()。失败时用 getLastPeriodicTaskError() / getLastAlarmReviveError() 查看原因。

Q：Android 12+ 闹钟拉活失败？
A：多为未授予「闹钟与提醒」权限。先 canScheduleExactAlarms() 检查，失败时调用 openExactAlarmSettings() 跳转系统设置。

Q：启动后通知栏没有图标？
A：请确保 register 的 icon 参数传入了有效的资源 ID（如 R.drawable.ic_notification 或应用图标资源）。不传则使用应用图标。

Q：真机调试没有反应？
A：是否使用 自定义调试基座？UTS 原生插件必须在自定义基座或正式包中运行。

Q：耗电情况如何？
A：Android 前台服务是系统级高优先级进程，功耗相对较低。WakeLock 使用 PARTIAL_WAKE_LOCK（CPU 唤醒，屏幕可关闭），正常待机功耗增加约 5%-10%。iOS 定位保活持续使用 GPS，功耗较高，建议仅在必要时启用。

更新日志

见 changelog.md

许可

见 license.md

点击下载体验

扫码体验