更新记录
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 或系统签名,普通应用做不到,也违反应用商店规范;靠心跳探活只能发现进程没了,不能阻止它被回收。
所以本插件不含任何底层原生库,也没有隐藏玩法。真正决定存活率的是厂商白名单,插件做的是一键把用户引导过去。
保活分层(按真实效果排序)
- 常驻前台服务 —— 系统唯一正式认可的手段(Android 8+ 必须常驻通知,无法隐藏)
- 厂商白名单 —— 自启动 / 后台运行 / 电池优化,国产 ROM 上这一项的影响超过其余所有手段之和
- 双进程互拉 —— 守护进程与主进程互相监听,任一被回收由另一方拉起
- 定时唤醒 —— 系统定时唤醒周期检查并恢复服务,也能在息屏时给业务用
- Wi-Fi 锁 / 组播锁 —— 不提升存活率,但决定息屏后网络是否还通
- 静音音频 —— 让进程处于「正在播放音频」状态,Android 8+ 上收益很低(前台服务本身的存活优先级已经更高),默认关闭
- 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 申请长时任务,
并且必须满足两个工程级前置条件(插件无法替你完成):
- 在主工程
EntryAbility 的 module.json5 里声明 backgroundModes: ['dataTransfer']
(只配在插件的 module.json5 里不生效)
- 声明
ohos.permission.KEEP_BACKGROUND_RUNNING(when: 'always')
配置完成后调用 backgroundTaskManager.startBackgroundRunning(context, BackgroundMode.DATA_TRANSFER, wantAgent)。
注意 dataTransfer 也不保证永不被终止:用户主动结束、拒绝后台权限、或 CPU/内存/IO 超配额时系统仍可停止进程。