更新记录

1.0.0（2026-05-10） 下载此版本

初次提交

平台兼容性

uni-app(5.08)

uni-app x(4.87)

laoqianjunzi-keep

laoqianjunzi-keep 是一个面向 uni-app x 的四端守护插件。它提供统一的保活配置、状态快照、通知权限、系统设置引导、调试日志。

插件按真实平台能力实现，不伪装成“所有平台能力完全一致”：

• Android：完整守护内核，包含前台服务、双进程守护、JobScheduler、宿主恢复、1 像素、静音音乐、设置引导、调试日志
• iOS：提供后台任务、后台音频壳层、通知权限、本地通知、统一状态接口
• Harmony：提供后台运行权限、后台任务壳层、通知权限、通知发布、统一状态接口
• Web：提供统一接口、状态与日志、浏览器通知权限适配

适用场景

• 需要在 Android 上维持宿主应用的守护运行态
• 需要统一处理通知权限、电池优化、自启动引导、后台活动等系统设置能力
• 需要一个可观测的状态模型，方便页面直接显示“当前保活链路是否真的生效”

平台能力概览

Android

支持的核心能力：

• 前台守护服务
• 远程守护进程互保
• JobScheduler 周期兜底
• 1 像素 Activity 策略
• 静音音乐后台维持
• 开机后宿主恢复
• 自启动 / 后台弹出 / 后台活动 / 电池优化 / 通知 / 悬浮窗引导
• 调试日志、待补偿恢复状态、最近开机恢复动作

注意事项：

• 1 像素 Activity 在 Android 10 及以上系统上受后台启动限制，是否有效取决于 ROM 策略
• 静音音乐、后台拉起宿主、双进程互保都属于高敏感策略，请按需启用
• 自启动、电池优化、通知、后台活动权限是否生效，最终以真机实际系统行为为准

iOS

支持的能力：

• 后台任务壳层
• 后台音频壳层
• 通知权限申请
• 跳转系统设置页
• 本地通知发送
• 统一状态与日志接口

注意事项：

• 不支持 Android 式开机恢复、自启动设置、电池优化设置、前台服务
• 后台任务与后台音频效果受系统调度、签名、后台模式配置影响

Harmony

支持的能力：

• 后台运行权限申请
• 后台任务壳层
• 通知权限申请
• 通知发布与取消
• 统一状态、兼容启动配置、调试日志

注意事项：

• 不支持 Android 式开机广播恢复、自启动页面、电池优化页面
• 后台运行能力依赖系统权限与设备策略

Web

支持的能力：

• 统一状态接口
• 浏览器 Notification 权限适配
• 调试日志

注意事项：

• 不支持原生保活、系统设置页、自启动、电池优化
• 通知权限是否可用依赖浏览器是否支持 Notification API

安装后目录

插件关键目录如下：

uni_modules/laoqianjunzi-keep/
├─ package.json
├─ readme.md
├─ pages/demo/index.uvue
└─ utssdk/
   ├─ interface.uts
   ├─ app-android/
   ├─ app-ios/
   ├─ app-harmony/
   └─ web/

快速开始

1. 导入新接口

import {
  configureKeep,
  startKeep,
  stopKeep,
  getKeepStatus,
  getKeepCapabilities
} from '@/uni_modules/laoqianjunzi-keep'

2. 配置策略

configureKeep({
  debug: true,
  notificationTitle: '孩子端守护中',
  notificationText: '正在维持宿主恢复与守护链路',
  enableForeground: true,
  enableJob: true,
  enableSinglePixel: false,
  enableMusic: false,
  enableBootRecovery: true,
  launchHostOnBoot: true,
  startForegroundServiceOnBoot: true
})

3. 启动与停止

startKeep()

const status = getKeepStatus()
console.log('当前状态', status)

stopKeep()

API 使用示例页面代码

下面给出一个更完整的页面级调用示例，适合直接放进 uni-app x 页面中联调：

<template>
    <scroll-view class="page" :scroll-y="true">
        <view class="card">
            <text class="title">laoqianjunzi-keep 示例</text>
            <text class="line">平台：{{ capabilities.platform }}</text>
            <text class="line">运行中：{{ status.running }}</text>
            <text class="line">前台服务：{{ status.foregroundServiceRunning }}</text>
            <text class="line">远程守护：{{ status.remoteServiceRunning }}</text>
            <text class="line">音乐保活：{{ status.musicServiceRunning }}</text>
            <text class="line">Job 调度：{{ status.jobScheduled }}</text>
            <text class="line">通知可用：{{ status.notificationEnabled }}</text>
            <text class="line">最近事件：{{ status.lastEvent == null ? '无' : status.lastEvent }}</text>
            <text class="line">最近恢复动作：{{ status.lastBootAction }}</text>
        </view>

        <view class="card">
            <button @click="applyConfig">应用配置</button>
            <button @click="handleStart">启动守护</button>
            <button @click="handleStop">停止守护</button>
            <button @click="handleRestart">重启守护</button>
            <button @click="handleRefresh">刷新状态</button>
        </view>

        <view class="card">
            <button @click="handleRequestNotification">请求通知权限</button>
            <button @click="handleOpenNotification">打开通知设置</button>
            <button @click="handleOpenAutoStart">打开自启动设置</button>
            <button @click="handleOpenBattery">打开电池优化设置</button>
            <button @click="handleOpenOverlay">打开悬浮窗设置</button>
        </view>

        <view class="card">
            <text class="title">待补偿恢复</text>
            <text class="line">pending：{{ pendingRecovery.pending }}</text>
            <text class="line">reason：{{ pendingRecovery.reason }}</text>
            <text class="line">createdAt：{{ pendingRecovery.createdAt }}</text>
            <text class="line">lastTrigger：{{ pendingRecovery.lastTrigger }}</text>
            <button @click="handleClearPending">清除待恢复状态</button>
        </view>

        <view class="card">
            <text class="title">调试日志</text>
            <text class="log">{{ debugLog }}</text>
            <button @click="handleClearLogs">清空日志</button>
        </view>
    </scroll-view>
</template>

<script lang="uts" setup>
    import {
        clearDebugLogs,
        clearPendingRecoveryStatus,
        configureKeep,
        getDebugLogText,
        getKeepCapabilities,
        getKeepStatus,
        getPendingRecoveryStatus,
        openAutoStartSetting,
        openBatteryOptimizationSetting,
        openNotificationSetting,
        openOverlayPermissionSetting,
        requestNotificationPermission,
        restartKeep,
        startKeep,
        stopKeep,
        type KeepCapabilities,
        type KeepStatus,
        type PendingRecoveryStatus,
        type KeepStrategyConfig
    } from '@/uni_modules/laoqianjunzi-keep'

    const status = ref<KeepStatus>({
        configured: false,
        running: false,
        foregroundEnabled: false,
        foregroundServiceRunning: false,
        musicEnabled: false,
        musicServiceRunning: false,
        jobEnabled: false,
        jobScheduled: false,
        singlePixelEnabled: false,
        singlePixelActive: false,
        bootRecoveryEnabled: false,
        launchHostOnBoot: false,
        startForegroundServiceOnBoot: false,
        batteryOptimized: true,
        remoteServiceRunning: false,
        notificationEnabled: false,
        lastEvent: null,
        lastBootAction: '',
        sdkInt: 0
    })

    const capabilities = ref<KeepCapabilities>({
        platform: 'unknown',
        supportsForeground: false,
        supportsJob: false,
        supportsSinglePixel: false,
        supportsBootRecovery: false,
        supportsNotificationPermission: false,
        supportsBatteryOptimization: false,
        supportsAutoStartGuide: false,
        supportsOverlayPermission: false,
        supportsBackgroundPopupGuide: false,
        supportsBackgroundActivityGuide: false
    })

    const pendingRecovery = ref<PendingRecoveryStatus>({
        pending: false,
        reason: '',
        openHost: false,
        createdAt: '',
        lastTrigger: ''
    })

    const debugLog = ref('')

    function refreshAll(): void {
        status.value = getKeepStatus()
        capabilities.value = getKeepCapabilities()
        pendingRecovery.value = getPendingRecoveryStatus()
        debugLog.value = getDebugLogText()
    }

    function applyConfig(): void {
        const config: KeepStrategyConfig = {
            debug: true,
            notificationTitle: '孩子端守护中',
            notificationText: '正在维持宿主恢复与守护链路',
            enableForeground: true,
            enableJob: true,
            enableSinglePixel: false,
            enableMusic: false,
            enableBootRecovery: true,
            launchHostOnBoot: true,
            startForegroundServiceOnBoot: true
        }
        configureKeep(config)
        refreshAll()
    }

    function handleStart(): void {
        startKeep()
        refreshAll()
    }

    function handleStop(): void {
        stopKeep()
        refreshAll()
    }

    function handleRestart(): void {
        restartKeep()
        refreshAll()
    }

    function handleRefresh(): void {
        refreshAll()
    }

    function handleRequestNotification(): void {
        requestNotificationPermission(function(_granted: boolean) {
            refreshAll()
        })
    }

    function handleOpenNotification(): void {
        openNotificationSetting()
    }

    function handleOpenAutoStart(): void {
        openAutoStartSetting()
    }

    function handleOpenBattery(): void {
        openBatteryOptimizationSetting()
    }

    function handleOpenOverlay(): void {
        openOverlayPermissionSetting(function(_granted: boolean) {
            refreshAll()
        })
    }

    function handleClearPending(): void {
        clearPendingRecoveryStatus()
        refreshAll()
    }

    function handleClearLogs(): void {
        clearDebugLogs()
        refreshAll()
    }

    onLoad(() => {
        applyConfig()
        refreshAll()
    })

    (() => {
        refreshAll()
    })
</script>

<style>
    .page {
        flex: 1;
        background-color: #f6f6f6;
    }

    .card {
        margin: 12px;
        padding: 12px;
        border-radius: 12px;
        background-color: #ffffff;
    }

    .title {
        display: block;
        font-size: 16px;
        font-weight: 700;
        margin-bottom: 8px;
    }

    .line {
        display: block;
        font-size: 13px;
        line-height: 20px;
        margin-bottom: 4px;
    }

    .log {
        display: block;
        font-size: 12px;
        line-height: 18px;
        white-space: pre-wrap;
    }
</style>

这个示例页覆盖了最常见的接入路径：

• 初始化守护策略
• 启动 / 停止 / 重启守护
• 刷新能力和状态快照
• 请求通知权限
• 打开自启动、电池优化、通知、悬浮窗设置页
• 读取待补偿恢复状态与调试日志

推荐配置策略

保守模式

适合优先追求稳定性的应用：

configureKeep({
  debug: true,
  notificationTitle: '守护服务运行中',
  notificationText: '正在维持宿主恢复链路',
  enableForeground: true,
  enableJob: true,
  enableSinglePixel: false,
  enableMusic: false,
  enableBootRecovery: true,
  launchHostOnBoot: true,
  startForegroundServiceOnBoot: true
})

增强模式

适合需要更高运行韧性的 Android 业务：

configureKeep({
  debug: true,
  notificationTitle: '标题',
  notificationText: '前台服务、Job 与补偿恢复已启用',
  enableForeground: true,
  enableJob: true,
  enableSinglePixel: true,
  enableMusic: true,
  enableBootRecovery: true,
  launchHostOnBoot: true,
  startForegroundServiceOnBoot: true
})

核心类型

KeepStrategyConfig

统一守护策略配置：

• debug：是否记录详细日志
• notificationTitle：通知标题
• notificationText：通知正文
• enableForeground：是否启用前台守护
• enableJob：是否启用 JobScheduler 兜底
• enableSinglePixel：是否启用 1 像素策略
• enableMusic：是否启用静音音乐 / 后台音频壳层
• enableBootRecovery：是否启用宿主恢复
• launchHostOnBoot：恢复时是否尝试打开宿主
• startForegroundServiceOnBoot：恢复时是否先拉起前台守护

KeepStatus

统一状态快照：

• running：插件运行态是否开启
• foregroundServiceRunning：前台服务是否在运行
• remoteServiceRunning：远程守护服务是否在运行
• musicServiceRunning：音乐服务或音频壳层是否在运行
• jobScheduled：JobScheduler 是否已调度
• singlePixelActive：1 像素页面是否激活
• notificationEnabled：通知是否可用
• batteryOptimized：Android 是否仍受电池优化限制
• lastEvent：最近一次运行事件
• lastBootAction：最近一次恢复动作

KeepCapabilities

能力探测对象，适合页面按平台动态展示按钮。

BootLaunchConfig

宿主恢复配置：

• enabled
• launchHostOnBoot
• startForegroundServiceOnBoot
• lastBootAction

PendingRecoveryStatus

用于查看补偿恢复是否还未完成：

• pending
• reason
• openHost
• createdAt
• lastTrigger

口说明

守护控制

• configureKeep(config)：设置当前守护策略
• getKeepConfig()：读取当前策略
• startKeep()：启动守护
• stopKeep()：停止守护
• restartKeep()：重启守护
• isKeepRunning()：读取运行态

状态与诊断

• getKeepStatus()：读取当前状态快照
• getKeepCapabilities()：读取平台能力矩阵
• getLastBootHandleResult()：读取最近一次恢复结果
• getPendingRecoveryStatus()：读取待补偿恢复状态
• clearPendingRecoveryStatus()：手动清理待补偿恢复状态
• getDebugLogText()：获取调试日志
• clearDebugLogs()：清空调试日志
• getAutostartDebugLogText()：获取恢复 / 自启动日志别名
• clearAutostartDebugLogs()：清空恢复 / 自启动日志别名

恢复与引导

• setBootLaunchEnabled(enable)：切换宿主恢复总开关
• getBootLaunchEnabled()：读取宿主恢复总开关
• setBootLaunchConfig(config)：写入恢复配置
• getBootLaunchConfig()：读取恢复配置
• getLastBootAction()：读取最近一次恢复动作
• launchHostApp()：手动拉起宿主
• startGuardService()：手动触发前台守护服务
• getAutostartEnvironmentHint()：获取当前环境提示文本

权限与系统设置

• openAutoStartSetting()
• openAutostartPermissionSetting()
• openBackgroundPopupSetting()
• openBackgroundActivitySetting()
• openBatteryOptimizationSetting()
• openBatteryOptimizationPermissionSetting()
• openNotificationSetting()
• openNotificationPermissionSetting()
• isNotificationEnabled()
• isNotificationPermissionEnabled()
• requestNotificationPermission(callback)
• openNotificationSettingWithResult(callback)
• openNotificationPermissionSettingWithResult(callback)
• isIgnoringBatteryOptimizations()
• isBatteryOptimizationIgnored()
• requestIgnoreBatteryOptimizations()
• requestBatteryOptimizationIgnore()
• isAutoStartEnabled()
• isAutostartPermissionEnabled()
• isOverlayPermissionGranted()
• openOverlayPermissionSetting(callback)

import { KeepLive } from '@/uni_modules/laoqianjunzi-keep'

const keep = new KeepLive()
keep.setTitle('孩子端守护中')
keep.setContent('正在维持宿主恢复链路')
keep.setWorkerEnabled(true)
keep.setMusicEnabled(false)
keep.setAutoStartEnable(true)
keep.register()

• 守护启停：register、unregister、restart、isRunning
• 通知相关：setTitle、setContent、updateNotification、goNotificationSetting
• 权限相关：requestNotifationPer、checkAppNotification、checkNotificationPer
• 定时器辅助：startAleraTask、startCSystemTimer、cancelCSystemTimer 等
• 自启动引导：setAutoStartEnable、goKeepLiveSetting、startAutoStart

说明：兼容类是迁移层，不建议新业务继续围绕它扩展复杂逻辑。新页面与新模块优先使用函数式新接口。

演示页

插件内置统一演示页：

uni_modules/laoqianjunzi-keep/pages/demo/index.uvue

该页面可直接演示：

• 平台能力概览
• 当前运行状态
• 守护策略切换
• 新接口调用
• 调试日志与待恢复状态

Android 使用建议

推荐上线前验证项

• 通知是否真实可见
• 前台服务是否能长期稳定存在
• JobScheduler 是否已调度
• 自启动页是否能准确跳转
• 电池优化是否已加入白名单
• 开机后宿主恢复日志是否符合预期
• 最近任务被划掉后前台守护链路是否能重新维持

推荐运行顺序

1. configureKeep() 写入策略
2. requestNotificationPermission() / 系统设置引导
3. startKeep() 启动守护
4. getKeepStatus() 验证状态
5. 通过 getDebugLogText() 观察恢复链路与策略是否真实生效

iOS 使用建议

• 勾选并确认后台模式配置已生效
• 若启用音频壳层，请确保宿主工程允许后台音频能力
• 使用 openNotificationSettingWithResult() 时，应在用户从设置页返回后读取结果，而不是依赖同步返回值

Harmony 使用建议

• 首次运行时建议优先调用通知权限与后台运行权限相关入口
• 读取 getKeepStatus() 时，应重点关注 notificationEnabled、foregroundServiceRunning、lastEvent
• 若只是需要统一状态与引导界面，可以仅使用新接口，不一定要启用兼容类

Web 使用建议

• 在支持 Notification 的浏览器中使用通知权限相关接口
• 浏览器不支持 Notification 时，接口会返回失败或不可用状态
• Web 端更适合作为统一调试与兼容壳层，而不是原生保活实现

常见问题

1. startKeep() 后为什么状态仍显示部分能力未开启？

因为系统能力是否真正生效，不只由插件配置决定，还受系统权限、ROM 策略、通知开关、电池优化、自启动白名单等影响。请结合：

• getKeepStatus()
• getAutostartEnvironmentHint()
• getDebugLogText()

一起排查。

2. 为什么 Android 上 supportsSinglePixel 可能为 false？

在较新的系统版本中，后台直接拉起 1 像素页面受限制，插件会按平台兼容性返回能力边界，而不是强行声称支持。

3. 为什么 iOS / Harmony / Web 的某些开机恢复接口存在，但能力并不完整？

这是为了保持四端统一接口与页面接入体验。接口会保留，但状态和返回值会按平台真实能力降级。

4. 如何确认“恢复链路真的跑了”？

重点看：

• getLastBootHandleResult()
• getPendingRecoveryStatus()
• getLastBootAction()
• getDebugLogText()

版本要求

• HBuilderX：^5.0.0
• uni-app x：^4.87
• Android：minSdkVersion 21
• iOS：deploymentTarget 12
• Harmony：minVersion 12