更新记录

1.0.0（2026-07-07）

• 首版发布，支持 Android、iOS、HarmonyOS 后台保活。
• Android：前台服务、WakeLock/WiFiLock、JobScheduler/WorkManager 增强模式，以及通知与电池优化引导。
• iOS：静音音频与可选后台定位。
• HarmonyOS：短时后台任务。
• 附 uni-app / uni-app x 示例页面。

平台兼容性

uni-app(5.06)

uni-app x(5.06)

其他

xview-keepalive

xview-keepalive 是一个 UTS API 插件，用于把 App 后台持续运行相关能力封装成统一接口。

平台策略

• Android：使用合规前台服务常驻通知作为主保活方式，可选 WakeLock / WiFiLock，并提供通知、电池优化设置引导。
• iOS：使用系统允许的后台 audio 静音音频会话，可选后台定位会话；必须在自定义基座或正式包中启用后台能力。
• HarmonyOS：默认封装 requestSuspendDelay 短时后台任务；长时后台任务必须在主工程 harmony-configs 中配置 backgroundModes 与 ohos.permission.KEEP_BACKGROUND_RUNNING。

快速开始

uni-app

// #ifdef APP
import {
    requestNotificationPermission,
    startKeepalive,
    stopKeepalive,
    getKeepaliveStatus,
    openNotificationSettings,
    requestIgnoreBatteryOptimizations
} from '@/uni_modules/xview-keepalive'
// #endif

requestNotificationPermission(
    () => {
        startKeepalive({
            title: 'Xview Keepalive',
            content: '后台任务正在运行',
            enableWakeLock: true,
            wakeLockTimeoutMs: 60000,
            keepaliveMode: 'resilient',
            enableBackgroundAudio: true,
            reason: '后台同步',
            success(res) {
                console.log(res)
            },
            fail(err) {
                console.log(err.errMsg)
            }
        })
    },
    () => {
        openNotificationSettings()
    }
)

uni-app x

// #ifdef APP
import {
    requestNotificationPermission,
    startKeepalive,
    XviewKeepaliveFail,
    XviewKeepaliveStatus
} from '@/uni_modules/xview-keepalive'
// #endif

requestNotificationPermission(
    (allRight : boolean, grantedList : Array<string>) => {
        startKeepalive({
            title: 'Xview Keepalive',
            content: '后台任务正在运行',
            enableWakeLock: true,
            wakeLockTimeoutMs: 60000,
            keepaliveMode: 'resilient',
            enableBackgroundAudio: true,
            reason: '后台同步',
            success: (res : XviewKeepaliveStatus) => {
                console.log(res.message)
            },
            fail: (err : XviewKeepaliveFail) => {
                console.log(err.errMsg)
            }
        })
    },
    (doNotAskAgain : boolean, grantedList : Array<string>) => {
        console.log('通知权限未开启')
    }
)

API

startKeepalive(options)

启动当前平台支持的后台运行能力。

其他方法

• requestNotificationPermission(success, fail)：Android 13+ 申请 POST_NOTIFICATIONS 运行时权限；低版本、iOS、Harmony 返回兼容结果。
• restartKeepalive()：Android 使用上次配置重启前台服务；iOS/Harmony 返回当前状态。
• stopKeepalive()：停止保活并释放相关锁。
• updateKeepaliveNotification(options)：Android 刷新前台通知标题/内容；iOS/Harmony 返回当前状态。
• getKeepaliveStatus()：返回运行状态。
• isKeepaliveRunning()：返回是否运行中。
• checkNotificationEnabled()：Android 13+ 检查通知权限；iOS/Harmony 返回兼容值。
• openNotificationSettings()：打开通知或应用设置。
• isIgnoringBatteryOptimizations()：Android 检查电池优化白名单；iOS/Harmony 返回兼容值。
• requestIgnoreBatteryOptimizations()：Android 请求忽略电池优化。
• openBatteryOptimizationSettings()：打开电池优化设置。
• acquireWakeLock(timeoutMs)：Android 临时申请 WakeLock；其他平台返回当前状态。

iOS 配置

插件内包含 Info.plist 片段，但实际运行仍建议在 manifest.json 的 App 常用其它设置中开启后台运行能力：

audio, location

如果只使用静音音频保活，可只启用 audio；若启用 enableLocation，需要启用 location 并准备合规的定位使用说明。

HarmonyOS 主工程配置

Harmony 端如果只调用插件，短时任务可以工作；如果需要长时后台能力，必须在项目根目录新增或修改：

harmony-configs/entry/src/main/module.json5

在 EntryAbility 下增加：

"backgroundModes": [
  "dataTransfer"
]

并在 requestPermissions 中加入：

{
  "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
  "reason": "$string:EntryAbility_label",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
}

dataTransfer 是当前更稳妥的通用后台模式。若业务是定位、音频播放等，应根据真实业务选择对应 background mode，避免系统返回后台任务校验错误。

注意

后台保活不是绕过系统调度的永久驻留能力。请只在定位、蓝牙、推送协同、长连接同步等有明确用户价值的场景中使用，并向用户解释通知、电池优化和后台权限的用途。

功能满足度检查

当前实现满足“合规后台运行能力封装”的基础需求，但不应理解为“所有系统上永久不被杀”：

• Android：基本满足保活主需求。实现了前台服务、通知渠道、Android 14+ dataSync 前台服务类型权限、Android 13+ 通知权限申请、WakeLock、WiFiLock、电池优化白名单引导。keepaliveMode: 'resilient' 会额外注册 JobScheduler / WorkManager 兜底任务，但这些任务由系统调度，不能保证秒级拉活。实际稳定性仍受厂商省电策略、用户关闭通知、用户强行停止应用影响。
• iOS：满足系统允许场景下的后台运行。实现了后台 audio 静音会话和可选 location 会话，但 iOS 不允许普通应用无业务理由永久常驻；必须启用对应 UIBackgroundModes 并通过审核。
• HarmonyOS：当前只满足短时后台任务保活，不满足长时任务完整闭环。插件封装了 requestSuspendDelay，适合退后台后完成一次同步/上报；如果业务要求持续运行，需要在主工程中补 startBackgroundRunning 所需的 WantAgent、backgroundModes 和 ohos.permission.KEEP_BACKGROUND_RUNNING，并按真实业务类型选择 dataTransfer、location、audioPlayback 等模式。

Android 增强模式说明

增强模式吸收了旧版 Ima-Keepalive 中低风险、可解释的兜底思想，但没有迁移一像素 Activity、隐藏通知、GET_TASKS 或双进程互拉。

startKeepalive({
  title: 'Xview Keepalive',
  content: '后台任务正在运行',
  keepaliveMode: 'resilient',
  enableWakeLock: true
})

增强模式会保存最近一次启动配置，restartKeepalive() 和系统兜底任务会复用该配置：

const status = restartKeepalive()

刷新通知：

const status = updateKeepaliveNotification({
  title: 'Xview Keepalive',
  content: '同步中'
})