更新记录

1.1.80（2026-05-21）

优化ios和鸿蒙

1.1.79（2026-05-18）

优化iOS编译报错

1.1.78（2026-05-16）

优化已知问题

平台兼容性

uni-app(4.07)

uni-app x(4.07)

其他

android-keeplive

android-keeplive 是一个用于提升应用后台存活率的保活插件，适用于需要在后台持续维持连接、定时任务、蓝牙通信、推送协同等场景。

支持平台：

• uni-app
• uni-app x
• Android / iOS / Harmony（不同平台能力存在差异，以 Android 能力最完整）

功能概述

• 后台无声音乐保活
• 前台通知常驻保活
• 省电白名单引导
• 通知权限检查与设置页跳转
• 息屏后定时任务
• 唤醒锁 WakeLock
• WiFi 锁定
• 通知点击回调
• 前后台状态回调
• 屏幕亮灭状态回调

使用前必读

1. Android / iOS 需要使用自定义基座。
2. iOS 若用于 uni-app，需要在 manifest.json 的后台运行能力中启用 audio、fetch。
3. Android 端建议提醒用户：
   • 锁定最近任务
   • 开启自启动
   • 允许后台运行
   • 关闭省电限制
4. Android 默认通知 id 为 6234542。
5. Android 源码版本不包含 aar 源码；其它平台源码包含在插件内。

安装与调试

1. 通过插件市场导入到项目。
2. 在页面或 App 中引入：

// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif

3. 制作自定义基座。
4. 使用自定义基座运行到真机。
5. 若手机已安装旧基座，请先卸载后再运行。

重要兼容说明

uni-app x / uvue 页面调用

从当前版本开始，uni-app x / uvue 页面请优先使用插件提供的 Compat 方法；页面层示例不再展示 new UTSCallback(...) 写法：

• onOpenNotificationSettingCompat
• onAddNotificationClickListenerCompat
• onAddBackgroundCallbackCompat
• onAddScrrenListenerCallbackCompat
• startCSystemTimerCompat
• onStartCSystemTimerCompat

uni-app 页面调用

uni-app 页面直接传普通 function(...) {} 即可。

快速开始

uni-app x / uvue 示例

// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif

// #ifdef APP
const keep = new KeepLive()

const running = keep.isRunning()
if(running){
    console.log("保活正在运行")
    return;
}
keep.setTitle('app')
keep.setContent('app is running')
keep.setSmallIcon('icon')
keep.setWakeLock(1, 'keeptag')
keep.setAutoStartEnable(true)

keep.onAddBackgroundCallbackCompat(function(res: boolean) {
  console.log('后台运行 ' + res)
})

keep.onAddScrrenListenerCallbackCompat(function(res: boolean) {
  console.log('屏幕开启状态 ' + res)
})

keep.onAddNotificationClickListenerCompat(function(data: string) {
  console.log(data)
})

if (!keep.checkAppNotification()) {
  keep.onOpenNotificationSettingCompat(function(res: boolean) {
    keep.register()
    const ignoring = keep.isIgnoringBatteryOptimizations()
    if (!ignoring) {
      keep.requestIgnoreBatteryOptimizations()
    }
  })
} else {
  keep.register()
  const ignoring = keep.isIgnoringBatteryOptimizations()
  if (!ignoring) {
    keep.requestIgnoreBatteryOptimizations()
  }
}

keep.onStartCSystemTimerCompat(60, function() {
  console.log('onStartCSystemTimer')
  keep.acquire(1000)
})
// #endif

uni-app 示例

// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif

// #ifdef APP
const keep = new KeepLive()
const running = keep.isRunning()
if(running){
    console.log("保活正在运行")
    return;
}
keep.setTitle('app')
keep.setContent('app is running')
keep.setSmallIcon('icon')
keep.setWakeLock(1, 'keeptag')
keep.setAutoStartEnable(true)

keep.onAddBackgroundCallback(function(res) {
  console.log('后台运行 ' + res)
})

keep.onAddScrrenListenerCallback(function(res) {
  console.log('屏幕开启状态 ' + res)
})

keep.onAddNotificationClickListener(function(data) {
  console.log(data)
})

if (!keep.checkAppNotification()) {
  keep.onOpenNotificationSetting(function(res) {
    keep.register()
    const ignoring = keep.isIgnoringBatteryOptimizations()
    if (!ignoring) {
      keep.requestIgnoreBatteryOptimizations()
    }
  })
} else {
  keep.register()
  const ignoring = keep.isIgnoringBatteryOptimizations()
  if (!ignoring) {
    keep.requestIgnoreBatteryOptimizations()
  }
}

keep.onStartCSystemTimer(60, function() {
  console.log('onStartCSystemTimer')
  keep.acquire(1000)
})
// #endif

与定位插件配合使用

如需后台定位，可配合作者定位插件，在定时器回调中触发定位。

推荐插件：

• 安卓 ios 鸿蒙 原生gps定位
• 安卓 ios 高德定位
• 安卓 腾讯定位
• 安卓 ios 百度定位

uni-app x 定位示例

// #ifdef APP
import { isProviderEnabled, onStartLocs, type LocData, type LocationData } from '@/uni_modules/xtf-gpslocation'
// #endif

// #ifdef APP
keep.setBackgroundMusicEnabled(false)

const on = isProviderEnabled()
if (on) {
  keep.onStartCSystemTimerCompat(60, function() {
    onStartLocs({
      backgroud: true,
    } as LocData, function(data: LocationData) {
      console.log(data)
    })
  })
}
// #endif

uni-app 定位示例

import { isProviderEnabled, onStartLocs } from '@/uni_modules/xtf-gpslocation'

keep.setBackgroundMusicEnabled(false)

const on = isProviderEnabled()
if (on) {
  keep.onStartCSystemTimer(60, function() {
    onStartLocs({
      backgroud: true,
    }, function(res) {
      console.log(res)
    })
  })
}

常用 API

生命周期

keep.register()
keep.restart()
keep.unregister()

const running = keep.isRunning()

通知权限与设置

const on = keep.checkAppNotification()
keep.goNotificationSetting()
keep.requestIgnoreBatteryOptimizations()

const ignoring = keep.isIgnoringBatteryOptimizations()

uni-app x / uvue：

keep.onOpenNotificationSettingCompat(function(on: boolean) {
  console.log(on)
})

uni-app：

keep.onOpenNotificationSetting(function(on) {
  console.log(on)
})

通知点击回调

uni-app x / uvue：

keep.onAddNotificationClickListenerCompat(function(data: string) {
  console.log(data)
})

uni-app：

keep.onAddNotificationClickListener(function(data) {
  console.log(data)
})

前后台与屏幕状态回调

uni-app x / uvue：

keep.onAddBackgroundCallbackCompat(function(res: boolean) {
  console.log(res)
})

keep.onAddScrrenListenerCallbackCompat(function(res: boolean) {
  console.log(res)
})

uni-app：

keep.onAddBackgroundCallback(function(res) {
  console.log(res)
})

keep.onAddScrrenListenerCallback(function(res) {
  console.log(res)
})

定时器

定时器1：系统定时器

uni-app x / uvue：

keep.onStartCSystemTimerCompat(60, function() {
  console.log('onStartCSystemTimer')
})

uni-app：

keep.onStartCSystemTimer(60, function() {
  console.log('onStartCSystemTimer')
})

取消：

keep.cancelCSystemTimer()
keep.clearAllCTimer()

定时器2：原生闹钟定时器

说明：

• 当前更推荐优先使用“定时器1”
• uni-app x / uvue 当前没有对应 Compat 方法时，建议先在插件侧封装后再调用

uni-app x / uvue：

keep.startAleraTask(0, 65 * 1000, function() {
  console.log('onAleraTaskListener')
})

keep.cancleAleraTask()

uni-app：

keep.startAleraTask(0, 65 * 1000, function() {
  console.log('onAleraTaskListener')
})

keep.cancleAleraTask()

说明：

• startTime：首次执行延迟，毫秒
• intervalTime：循环时间，毫秒
• Android 上推荐大于 60s

定时器3：时钟定时器

说明：

• 当前更推荐优先使用“定时器1”
• uni-app x / uvue 当前没有对应 Compat 方法时，建议先在插件侧封装后再调用

uni-app x / uvue：

keep.startKeepClcokTimer(3, function() {
  console.log('startKeepClcokTimer')
})

keep.cancelKeepClcokTimer()
keep.cancelAllKeepClcokTimer()

uni-app：

keep.startKeepClcokTimer(3, function() {
  console.log('startKeepClcokTimer')
})

keep.cancelKeepClcokTimer()
keep.cancelAllKeepClcokTimer()

说明：当前更推荐优先使用“定时器1”。

唤醒锁与 WiFi 锁

keep.setWakeLock(1, 'tag')
keep.acquire(1000)
keep.releaseAcquire()

keep.wifilock()
keep.wifiunlock()

通知栏配置

keep.setNotifationId(333)
keep.setChannelId('keeplive')
keep.setChannelName('保活')
keep.setTitle('title')
keep.setContent('content')
keep.setSmallIcon('icon')
keep.setLargeIcon('icon')
keep.setAutoCancel(false)
keep.setNotifaicationSoundEnable(false)
keep.setChannelImportance(3)
keep.setLockscreenVisibility(1)
keep.enableVibration(true)
keep.setAllowBubbles(true)
keep.setShowChannelBrage(true)
keep.setNotifationMsgGroup('group')
keep.setNotifationExterData('data')
keep.setGroupSummary(true)
keep.updateNotification()

补充：

• 不同 id 会生成不同通知
• 相同 id 会更新已有通知
• Android 通知 channel 首次创建后不可修改，修改配置请更换新的 channelId

通知取消

keep.cancelNotifation(333)
keep.cancelGroupNotifaon('group')
keep.closeNotifation()

其它能力

keep.toBackground()
keep.hideRecentTask(true)
keep.goAndroidSystemAppSetting()
keep.setCrashRestartUIEnabled(true)
keep.doStartApplicationWithPackageName('com.test')
keep.restartThisApp()
keep.startAutoStart()
keep.startHighBattery()

const liveTime = keep.getLiveTime()
const liveText = keep.getLiveStr()
const notifationId = keep.getNotifationId()
const pkgName = keep.getPkgName()

后台音乐相关

keep.setBackgroundMusicEnabled(true)
keep.setMusicVol(0)
keep.setMusicId('music')
keep.setMusicInterval(6000)

说明：

• setMusicId('music') 对应资源文件为 res/raw/music.mp3
• 音量范围通常为 0 ~ 1

完整方法清单

以下表格按当前插件实现整理。

平台标记说明：

• A = Android
• I = iOS
• H = Harmony

说明：

• 表中“支持平台”表示该方法在对应平台存在实现或兼容占位，不代表每个平台效果完全一致
• Compat 方法主要给 uni-app x / uvue 页面使用，用来避免页面层直接处理 UTSCallback
• 表格中的 uni-app x 示例只保留 uni-app x 一种写法；如果当前方法没有对应 Compat，会明确标注“建议先封装 Compat”
• 示例统一写成最短调用形式，实际项目中请结合 #ifdef APP、权限判断、异常处理一起使用

权限与系统设置

生命周期与运行状态

通知与通道配置

通知、前后台、屏幕回调

定时器与线程

唤醒锁、后台音乐与保活辅助

状态查询与调试辅助

图标与资源放置

uni-app x uni-app

Android 小图标资源放在：

• uni_modules/android-keeplive/utssdk/app-android/res

Android 小图标资源放在插件 Android 原生 drawable 资源目录，图标名称通过 setSmallIcon('icon') 传入。

常见问题

1. UTSCallback 在 uvue 页面里标红

原因通常是 HBuilderX 页面编辑器的语法服务对 UTSCallback 识别不完整，不代表编译失败。

建议：

• 在 uvue 页面中优先使用本文档里的 Compat 方法
• 页面层统一直接写普通 function(...) {} 回调

3. 标准基座运行无效

本插件依赖原生能力，运行到标准基座时相关能力可能不生效，请使用自定义基座。

注意事项

• Android 平台能力最完整
• iOS / Harmony 部分接口仅做兼容保留，不一定具备与 Android 相同的原生效果
• 息屏保活、后台执行、通知常驻等行为会受到 ROM、系统版本、厂商限制影响
• 对于高频后台任务，请结合用户系统设置、自启动、忽略电池优化等方式一起使用