更新记录

1.0.0（2026-09-25）

安卓后台保活

平台兼容性

uni-app(5.26)

uni-app x(5.26)

后台保活插件

UTS 插件，为 App 提供后台保活能力：

• Android：常驻通知栏通知 + WakeLock，防止应用被系统休眠
• HarmonyOS（鸿蒙）：申请 DATA_TRANSFER 长时任务（连续任务），防止应用退后台后被挂起

支持平台

引入插件

// #ifdef APP-ANDROID || APP-HARMONY
import * as keepalive from '@/uni_modules/yao-keepalive'
// #endif

API 说明

startFrontService(config, callback?) 开启保活

keepalive.startFrontService({
    title: '应用运行中',      // 通知栏标题（可选，默认"应用运行中"）
    content: '正在后台运行',  // 通知栏内容（可选，默认"正在后台运行"）
    mode: 'none'             // 预留字段（可选）
}, (res) => {
    // res: KeepaliveResult { flag: boolean, msg: string }
    console.log(res.flag, res.msg)
})

• Android：创建通知渠道并发出常驻通知，同时持有 WakeLock；Android 13+ 未授予通知权限时回调 flag: false
• HarmonyOS：申请 DATA_TRANSFER 长时任务，成功后通知栏显示系统关联通知
• 重复调用时直接回调 flag: true, msg: "保活服务已在运行中"

stopFrontService() 停止保活

keepalive.stopFrontService()

isKeepaliveRunning() 查询状态

const running = keepalive.isKeepaliveRunning()

checkIsLimit() 检查后台限制

const result = keepalive.checkIsLimit()
const battery = result.batteryOptimization     // true=未加入电池优化白名单（受限）
const notification = result.notificationPermission // false=通知权限未授予（受限）
const isLimited = result.isLimited             // 任一项受限即为 true

鸿蒙端目前为占位实现，固定返回 batteryOptimization: false、notificationPermission: true、isLimited: false。

openSafeSetting() 打开应用设置

const ok: boolean = keepalive.openSafeSetting() // Android 打开应用详情页；鸿蒙端不支持，返回 false

uni-app x 快速上手

<script setup lang="uts">
    // #ifdef APP-ANDROID || APP-HARMONY
    import * as keepalive from '@/uni_modules/yao-keepalive'
    // #endif

    // 推荐做法：退后台自动开启，回前台自动停止
    onHide(() => {
        // #ifdef APP-ANDROID || APP-HARMONY
        keepalive.startFrontService({ title: '应用运行中', content: '正在后台运行' })
        // #endif
    })

    onShow(() => {
        // #ifdef APP-ANDROID || APP-HARMONY
        if (keepalive.isKeepaliveRunning()) {
            keepalive.stopFrontService()
        }
        // #endif
    })
</script>

uni-app（Vue3）使用说明

调用方式与 uni-app x 完全一致，仅需注意：

1. 使用条件编译 #ifdef APP-ANDROID || APP-HARMONY 包裹 import 与调用代码
2. 在 uni-app 的 js 环境中，config 直接传普通 JSON 对象即可，callback 收到的 res 也是普通对象，无需 as 断言：

// uni-app（js）中
import * as keepalive from '@/uni_modules/yao-keepalive'

keepalive.startFrontService({ title: '应用运行中' }, (res) => {
    console.log(res.flag, res.msg) // 普通对象，直接取值
})

平台配置

Android

插件已通过 config.json 声明所需权限，云打包/自定义基座会自动合并：

• android.permission.WAKE_LOCK
• android.permission.POST_NOTIFICATIONS（Android 13+ 通知权限，需运行时授权）
• android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS

Android 13+ 建议开启保活前先申请通知权限：

uni.requestNotificationPermission({})

HarmonyOS（重要）

在鸿蒙工程 entry/src/main/module.json5 中做两处配置（uni-app x 项目即 harmony-configs/entry/src/main/module.json5）：

1. EntryAbility 下声明长时任务类型（缺了会报 9800005 check continuous modes fail）：

"abilities": [
    {
        "name": "EntryAbility",
        // ...
        "backgroundModes": [
            "dataTransfer"
        ]
    }
]

2. 声明保活权限：

"requestPermissions": [
    {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
        "reason": "$string:background_running_reason",
        "usedScene": {
            "abilities": ["EntryAbility"],
            "when": "inuse"
        }
    }
]

reason 引用的字符串需在 resources/base/element/string.json 等资源文件中定义。插件内置的 utssdk/app-harmony/module.json5 已包含该权限声明（无 reason 的系统授权权限），正常情况下无需手动配置；如你在工程中手动配置了带 reason 的版本，以手动配置为准。

注意事项

1. 保活不是绝对的：受厂商 ROM、系统省电策略影响，极端情况下仍可能被杀。建议配合 checkIsLimit() 引导用户加白名单。
2. 鸿蒙 DATA_TRANSFER 运行限制：系统会校验应用是否真正执行了数据传输业务，且要求持续更新进度；首次超过 10 分钟未更新，系统会自动取消长时任务并挂起应用。
3. 鸿蒙上架审核：长时任务须在用户可感知的业务场景中使用（如后台上传/下载），不得用于恶意保活，需遵守华为《Background Tasks Kit 接入规范》。
4. 重复申请：鸿蒙端一个 UIAbility 同一时刻只能申请一个长时任务，先 stopFrontService() 再重新申请；用户删除通知栏消息时，系统会自动停止长时任务。
5. iOS 不支持本插件，需自行使用其他后台模式方案。