更新记录

1.1.2(2026-11-20)

  • 文档细节修订。

1.1.1(2026-11-20)

  • 修正文档表述与示例细节。

1.1.0(2026-11-20)

补齐 8 项增强能力与 4 类事件回调。

新增能力

  • 静音音频保活 setBackgroundMusic:后台播放无声音频维持进程,不会打断用户正在听的音乐。
  • 网络保持 setNetLock:息屏后不断网,局域网设备发现类功能(投屏、设备搜索)仍可用。
  • 最近任务隐藏 setHideInRecents:不出现在多任务列表,降低被「一键清理」顺手杀掉的概率。
  • 息屏定时任务 setTaskInterval + onTaskTick:按间隔在后台执行任务,息屏与深度休眠时也能触发。
  • 重启与退到后台 restart() / toBackground()。
  • 通知完全可配 setNotificationConfig / updateNotification:标题、正文、渠道名、重要级别、分组、角标、静音、点击行为;运行中还能只改文案(比如同步进度)。
  • 高耗电设置页跳转 openHighBatterySettings:按机型匹配省电策略页。
  • 事件回调:应用前后台切换、屏幕亮灭、通知点击、定时任务。

状态增强

getState() 新增存活时长文案、静音音频状态、网络锁状态、最近任务隐藏、前后台状态、屏幕状态、任务计数、通知配置回显。

修复

  • 前台服务类型不匹配时逐级降级,旧基座也能正常启动。
  • 无精确闹钟权限时 restart() 不再失败,会自动降级为普通闹钟。
  • 修复部分机型启动后页面白屏的问题。
  • stop() 会一并释放静音音频、网络锁与最近任务标记,不再残留。
  • 新开关全部持久化,开机自启后按原配置恢复。
查看更多

平台兼容性

uni-app x(4.25)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × √ × × ×

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

uni-keep-alive · Android 进程保活

常驻前台服务 + 双进程互拉 + 息屏定时唤醒 + 白名单引导 + 一组可开关的增强能力。

先说清楚:非 root 设备没有「绕过系统」的通用方案

网上流传的「底层手段保活」在普通应用上都不成立:进程回收由系统直接执行,应用层拦不住;注入或提权需要 root 或系统签名,普通应用做不到,也违反应用商店规范;靠心跳探活只能发现进程没了,不能阻止它被回收。

所以本插件不含任何底层原生库,也没有隐藏玩法。真正决定存活率的是厂商白名单,插件做的是一键把用户引导过去。

保活分层(按真实效果排序)

  1. 常驻前台服务 —— 系统唯一正式认可的手段(Android 8+ 必须常驻通知,无法隐藏)
  2. 厂商白名单 —— 自启动 / 后台运行 / 电池优化,国产 ROM 上这一项的影响超过其余所有手段之和
  3. 双进程互拉 —— 守护进程与主进程互相监听,任一被回收由另一方拉起
  4. 定时唤醒 —— 系统定时唤醒周期检查并恢复服务,也能在息屏时给业务用
  5. Wi-Fi 锁 / 组播锁 —— 不提升存活率,但决定息屏后网络是否还通
  6. 静音音频 —— 让进程处于「正在播放音频」状态,Android 8+ 上收益很低(前台服务本身的存活优先级已经更高),默认关闭
  7. WakeLock —— 防 CPU 休眠,耗电明显,默认关闭

特性

  • 三种模式:service(仅前台服务)/ daemon(双进程)/ full(双进程 + 定时唤醒 + 保持唤醒)
  • 常驻通知完全可配:标题、正文、渠道名、重要级别、分组、静音、点击行为;运行时还能只改文案
  • 通知点击回调:能拿到「用户点了常驻通知」这个事件(可选同时拉起应用)
  • 前后台切换回调 / 屏幕亮灭回调
  • 息屏定时任务:setTaskInterval + onTaskTick,业务可用它做「每 N 分钟同步一次」
  • Wi-Fi 高性能锁 / 组播锁:长连接、局域网设备发现(投屏、设备搜索)必需
  • 从最近任务列表隐藏:降低被「一键清理」顺手杀掉的概率
  • 重启 / 退到后台:restart() 会自动杀掉旧进程并由系统拉起
  • 开机自启、应用更新后自启(配置持久化到本地,重启后自动恢复所有开关)
  • 按厂商自动匹配自启动管理页(小米/华为/荣耀/OPPO/realme/一加/vivo/iQOO/三星/魅族)与高耗电管理页
  • 状态与错误信息全中文,Android 14 / 15 前台服务新规已适配

快速上手

import { start, stop, getState } from '@/uni_modules/uni-keep-alive'

start({
  mode: 'daemon',
  title: '巡检服务运行中',
  content: '点击返回应用',
  wifiLock: true,            // 息屏后不断网
  hideInRecents: true,       // 不在最近任务里露脸
  taskIntervalMin: 5,        // 每 5 分钟唤醒一次
  success: (state) => console.log('已开启', state.aliveText),
  fail: (err) => console.error(err.errCode, err.errMsg)   // 9150002 = 基座没声明服务
})

引导用户加白名单(这一步比任何技术手段都管用):

import { requestIgnoreBatteryOptimizations, openAutoStartSettings, openHighBatterySettings } from '@/uni_modules/uni-keep-alive'

requestIgnoreBatteryOptimizations({})   // 系统弹窗,用户点「允许」
openAutoStartSettings({})                // 按机型跳自启动管理
openHighBatterySettings({})              // 按机型跳省电策略页

API

生命周期

方法 说明
start(options) 开启保活,返回 KeepState
stop(options) 关闭保活(服务、守护进程、定时任务、WakeLock、静音音频、网络锁、最近任务全部还原)
getState(options) 查询状态
restart(options) 延迟重启自身:先杀掉当前进程,再由系统拉起启动页
toBackground(options) 切到后台(等价按 Home,不结束进程)
getVersion() 插件版本

白名单与系统设置

方法 说明
isIgnoringBatteryOptimizations(options) 是否已加入电池优化白名单
requestIgnoreBatteryOptimizations(options) 跳系统授权页
openAutoStartSettings(options) 跳厂商自启动管理页
openHighBatterySettings(options) 跳厂商「高耗电 / 省电策略」页
openNotificationSettings(options) 跳本应用通知设置页(渠道被关闭时唯一的恢复入口)

通知

方法 说明
setNotificationConfig(options) 配置标题/正文/渠道名/重要级别/分组/静音/点击行为,服务在跑时立即刷新
updateNotification(options) 只改标题/正文(高频调用,如同步进度)

增强能力

方法 说明
setBackgroundMusic({ enabled }) 静音音频保活(不申请音频焦点,不会打断用户正在听的内容)
setNetLock({ wifi, multicast }) Wi-Fi 高性能锁 / 组播锁
setHideInRecents({ enabled }) 从最近任务列表隐藏 / 恢复
setTaskInterval({ minutes }) 业务定时器,0 关闭

事件回调

方法 说明
onAppStateChange(cb) 前后台切换,注册时立即回调一次当前状态
onScreenStateChange(cb) 屏幕亮灭
onNotificationClick(cb) 常驻通知被点击
onTaskTick(cb) 定时任务到点
clearHooks() 注销全部回调(页面 onUnload 必须调用)

start 参数

参数 默认 说明
mode daemon service / daemon / full
title 应用正在运行 常驻通知标题
content 点击返回应用 常驻通知正文
heartbeatSec 60 心跳间隔
wakeLock false 是否保持 CPU 唤醒(耗电)
bootStart true 是否开机自启
music false 静音音频保活
wifiLock false Wi-Fi 高性能锁
multicast false 组播锁
hideInRecents false 从最近任务隐藏
taskIntervalMin 0 定时任务周期(分钟),0 关闭

KeepState

{
  running: boolean            // 主服务在跑
  daemonAlive: boolean        // 守护进程在线
  mode: string
  startedAt: number
  aliveSec: number            // 已存活秒数
  aliveText: string           // 中文描述,如「2 小时 13 分」

  // 系统状态
  batteryWhitelisted: boolean
  exactAlarmAllowed: boolean
  holdingWakeLock: boolean
  vendor: string
  tips: string                // 按机型给出的设置建议

  // 增强能力实况
  musicEnabled: boolean       // 是否开启静音音频
  musicPlaying: boolean       // 是否真的在播(被系统掐掉时为 false)
  wifiLocked: boolean
  multicastLocked: boolean
  hiddenInRecents: boolean

  // 运行态
  appForeground: boolean
  screenOn: boolean
  tickCount: number           // 本次启动以来收到的唤醒次数
  taskIntervalMin: number

  // 通知诊断
  notificationTitle: string
  notificationContent: string
  clickAction: string
  notificationEnabled: boolean
  notificationVisible: boolean
  channelImportance: number   // -1 未知 / 0 已关闭 / 2 低 / 3 默认
  foregroundType: number      // 1073741824=specialUse / 2=mediaPlayback / 1=dataSync
  androidSdk: number
  strictNoticeVendor: boolean
}

错误码

错误码 说明
9150001 参数错误
9150002 前台服务启动失败(多为基座未声明服务,需重打自定义基座)
9150003 通知权限未授予,或通知渠道被用户在系统设置里关闭
9150004 系统拒绝启动前台服务(Android 15 配额耗尽 / 后台受限)
9150005 当前机型没有对应的保活设置页
9150006 保活未在运行 / 当前状态不允许该操作
9150007 当前平台不支持
9150008 内部错误

各能力的真实收益(避免过度期待)

能力 真实收益 代价
前台服务 决定性,系统唯一认可 必须常驻通知
厂商白名单 决定性,国产 ROM 上超过其他手段之和 需要用户手动操作
双进程互拉 中等,能拉起被「普通杀进程」清掉的一方 多一个进程,内存 +10MB 左右
定时唤醒 中等,能恢复被杀的服务;深度休眠时间隔会被系统拉长 轻微耗电
Wi-Fi 锁 不提升存活率,但决定息屏后网络是否还通 轻微耗电
组播锁 不提升存活率,局域网设备发现的前提 几乎为零
静音音频 低。Android 8+ 上前台服务的存活优先级已经更高,只有少数 ROM 吃这一套 出现在系统的「正在播放」里,用户可能困惑
隐藏最近任务 中等,能避免「一键清理」顺手带走 用户切回应用变麻烦
WakeLock 低,只防 CPU 休眠不防被杀 耗电明显

注意事项(重要)

  • 必须打自定义基座:插件包含前台服务、守护进程、3 个广播接收器与若干权限,全部需要随基座打进清单。
  • Android 8+ 前台服务通知不可隐藏,只能降低打扰程度。本插件默认 IMPORTANCE_LOW(无声、无振动): 用 IMPORTANCE_MIN 会被小米 HyperOS 折叠进「不重要通知」,状态栏完全看不到。试图隐藏通知属于违规行为,插件不提供。
  • Android 15 前台服务配额:dataSync 有 24 小时内 6 小时上限,超时后系统直接拒绝启动。 插件在 Android 14+ 自动切到无时长限制的 specialUse(开静音音频时切 mediaPlayback),清单里三种类型同时声明。
  • 小米 / HyperOS 专项:常驻通知会归入通知栏「正在运行」分组(Android 13+ 原生行为), 需要向下展开才能看到。若状态栏始终没有图标,用 openNotificationSettings() 让用户检查 「允许通知」与「后台运行」类别。getState().notificationVisible 会直接告诉你结果。
  • 定时任务不是精确 cron:系统深度休眠时,实际间隔会被拉长到 9 分钟以上。 需要严格定时请改用推送或服务端调度。
  • 隐藏最近任务依赖系统的最近任务标记,部分第三方桌面不遵循该标记, 此时 hiddenInRecents 会返回 true 但界面仍可见。
  • restart() 会真的杀掉进程:已排的闹钟、临时状态都会丢,仅持久化配置会自动恢复。
  • 回调必须注销:原生侧会持有回调引用,页面 onUnload 不调 clearHooks() 会导致内存无法释放。
  • onScreenStateChange 的熄屏事件不保证送达:屏幕亮灭属于受保护广播,只能动态注册; 熄屏后进程很快被系统冻结,该事件可能在派发前就被拦下(部分设备上更明显)。 需要精确判断屏幕状态请以 getState().screenOn 为准,或在页面 onShow 时主动查一次。
  • Android 12+ 后台启动服务受限,双进程互拉能生效的前提是宿主本身处于「前台服务」状态。
  • 国产 ROM 的省电策略差异极大,不保证 100% 存活;强可靠场景请接入厂商推送(华为/小米/OPPO/vivo)。
  • 请遵守《个人信息保护法》与应用商店审核要求:后台常驻需在隐私政策中告知用途,不得静默驻留。
  • 刻意不提供「崩溃自动重启」:吞掉崩溃会让本该暴露的问题变成莫名其妙的白屏或卡死,多数应用商店也将其视为恶意行为。

平台支持

平台 支持
Android ✅ 完整
鸿蒙 ⚠️ 仅 API 兼容(返回 9150007 并给出配置指引)
iOS ❌

鸿蒙要真正保活需要做什么

鸿蒙没有 Android 那套前台服务模型,正规做法是向 BackgroundTaskManager 申请长时任务, 并且必须满足两个工程级前置条件(插件无法替你完成):

  1. 在主工程 EntryAbility 的 module.json5 里声明 backgroundModes: ['dataTransfer'] (只配在插件的 module.json5 里不生效)
  2. 声明 ohos.permission.KEEP_BACKGROUND_RUNNING(when: 'always')

配置完成后调用 backgroundTaskManager.startBackgroundRunning(context, BackgroundMode.DATA_TRANSFER, wantAgent)。 注意 dataTransfer 也不保证永不被终止:用户主动结束、拒绝后台权限、或 CPU/内存/IO 超配额时系统仍可停止进程。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

需要 FOREGROUND_SERVICE、FOREGROUND_SERVICE_DATA_SYNC、POST_NOTIFICATIONS、RECEIVE_BOOT_COMPLETED、WAKE_LOCK、REQUEST_IGNORE_BATTERY_OPTIMIZATIONS、SCHEDULE_EXACT_ALARM

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集、不上传任何数据;保活配置仅存于本机

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。