更新记录

1.0.0（2026-05-20）

UTS 跨平台保活插件：前台服务（Android）、后台定位+音频保活（iOS）、后台任务+常驻通知（鸿蒙）。防止 App 在后台被系统回收。

平台兼容性

uni-app(3.7.7)

uni-app x(4.0)

ly028-KeepLive

uni-app / uni-app x UTS 原生保活插件：防止 App 在后台被系统回收。支持 Android 前台服务 + WakeLock + 通知栏控制、iOS 后台定位 + 音频保活、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 端仅标记状态（需额外调用 startLocation/startMusic），鸿蒙端申请后台任务 + 常驻通知 + CPU 唤醒。

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
} from '@/uni_modules/ly028-KeepLive'

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

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

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

iOS 特有 API

import { startLocation, stopLocation, startMusic, stopMusic } from '@/uni_modules/ly028-KeepLive'

// 定位保活
startLocation({
  distanceFilter: 100,   // 更新距离（米），默认 100
  desiredAccuracy: 100   // 精度，默认 kCLLocationAccuracyHundredMeters
})
stopLocation()

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

平台配置

Android

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

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>

⚠️ App Store 审核提示：

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

HarmonyOS

需要在 module.json5 中配置权限（插件已提供默认配置）：

• ohos.permission.KEEP_BACKGROUND_RUNNING — 后台运行
• ohos.permission.NOTIFICATION_USER_INITIATED — 通知发送

注意事项

Android 版本兼容

Android 厂商适配

• 不同手机厂商（华为、小米、OPPO、vivo 等）的后台管理策略不同
• 插件内置厂商检测逻辑，注册时自动输出省电策略设置路径到控制台
• 建议引导用户将 App 加入厂商的「受保护应用」或「自启动」白名单

iOS 限制

• iOS 系统对后台活动有严格限制，保活效果不如 Android
• 定位保活会持续消耗电量，建议仅在对定位实时性要求高的场景使用
• 音频保活建议在合适的时机启动，避免影响用户体验

鸿蒙限制

• 后台任务有系统时间限制（约 6~10 分钟），到期后会回调过期事件
• 插件在过期回调中会自动重新申请后台任务
• 鸿蒙 NEXT 版本可能有 API 变更，请关注适配

常见问题

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)。

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