更新记录

1.1.2（2026-10-29）

• 新增“基础保活 / 定时任务 / 系统设置”三个 Tab 示例，支持点击启动、停止，并查看真实本地文件写入、读回与任务执行结果。
• 修复 uni-app x Android Vapor 模式下接口参数转换异常导致查询和保活调用失败的问题。
• 修复 Android 持续监听回调的生命周期配置，保留定时器、任务与运行事件的后续回调。
• 修复 Web 降级入口的公开方法导出，以及 uni-app x Android 普通模式示例诊断模块的编译问题。
• 优化 uni-app 与 uni-app x 示例的操作分组、状态反馈和运行记录，按业务模块简化接入文档。
• 统一插件声明、示例报告与各平台运行诊断版本为 1.1.2；Android 升级后需重新制作并安装包含本插件的自定义基座。

1.1.0（2026-09-06）

• 归并本轮 uni-app x Android 修复：兼容对象序列化保留业务字段与回调，补齐 Android 入口公开 API 投影和示例选项类型；版本号保持 1.1.0，发布时与本版本内容一起提交。
• 2026-09-05 修复 Android UTS 兼容参数和单例转发的类型错误，保留各公开方法的参数与回调合同；修复 uni-app x 示例参数适配，完整传递预设启动、定时周期和事件筛选选项。
• Android 前台服务改为由项目按真实业务显式选择 dataSync 或 mediaPlayback；未选择时只保留最佳努力运行态，不会把通用保活伪装成某一种前台服务。历史的其他服务类型值不再启用前台服务。
• 看门狗和稳定定时器改为低频、非精确系统兜底，不再申请精确闹钟权限；原有查询与请求入口保留，但不会再跳转精确闹钟授权页。
• 修复主动取消注册后遗留闹钟和默认策略可能再次恢复的问题；屏幕状态监听改为运行期间动态注册，停止或取消注册后自动释放。
• iOS 与 Harmony 后台报告改为如实反映“进程内心跳观测”；不再将配置样板或人工确认标记为后台验收通过。iOS 不再为保活目的声明后台模式。
• 升级后需要重新制作并安装 Android 自定义基座；iOS、Harmony 如有对应原生配置或业务处理器，也需要重新原生联编或重新打包后按真实业务路径复测。

1.0.4（2026-07-31）

• 将真机回归清单迁出插件发布目录，并移除客户 README 的“当前版本”标题，避免内部验收资料进入市场包。
• 修复 uni-app x 示例日志样式在 HarmonyOS 编译时使用不受支持的 white-space: pre-wrap 导致构建失败的问题，改用平台支持的 normal 并保留自动换行。
• 同步 package.json、uni_modules.json 与多端运行诊断中的 pluginVersion；公开 API、保活策略和回调语义不变。
• 示例样式修复本身不要求新基座；如需运行诊断显示新版本号，App 端仍需重新原生联编或制作匹配自定义基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-app-keepalive

介绍

lizhao-app-keepalive 为 Android 应用提供前台服务、定时任务和后台运行设置引导，支持 uni-app 与 uni-app x。打开示例即可点击体验，并看到实际文件记录与运行状态。

功能特色

适合哪些场景

下载与导入

在 DCloud 插件市场搜索 lizhao-app-keepalive，下载后导入 uni-app 或 uni-app x 项目。

在需要调用的页面从插件根目录导入：

import * as keepAlive from '@/uni_modules/lizhao-app-keepalive'

后续示例都默认已完成上述导入。

将对应示例页面加入项目的 pages.json，在包含本插件的 Android 自定义基座或正式包中打开：

示例分为 基础保活、定时任务、系统设置 三个 Tab。点击开始后会实际写入并读回本地记录，直接显示服务检查、心跳次数、任务结果；无需自备服务器。演示使用 dataSync 前台服务，每次最多运行 60 秒，时间到后在回调可执行时停止。需要先授权时打开系统设置 Tab；单项接口与完整日志在“更多功能”“运行记录”中。

从基础到进阶：按业务模块使用

代码片段放入对应宿主页面脚本或按钮方法；uni-app x 保留 UTS 类型，使用 javascript 标记仅用于市场语法着色。整页示例按其标注的 Vue 版本使用。

1. 先确认当前平台能力

不同平台允许的后台能力不同。首次接入时先查询能力，再决定是否启动对应业务。

keepAlive.getCapabilities({
  success(capabilities) {
    console.log('当前平台：', capabilities.platform)
    console.log('是否支持后台保活：', capabilities.keepAlive)
    console.log('受限原因：', capabilities.restrictedReason)
  },
  fail(err) {
    console.error('能力查询失败：', err)
  }
})

2. 启动基础保活

以正在处理本地文件或同步数据的 Android 业务为例，先注册，再用 setConfig 修改需要的字段，最后启动。register.config 要求完整配置对象，首次接入建议省略它。业务结束后应立即停止。

keepAlive.register({
  success() {
    keepAlive.setConfig({
      config: {
        foregroundServiceType: 'dataSync',
        heartbeatIntervalMs: 5000,
        notice: { title: '文件处理进行中', content: '正在处理应用数据' }
      },
      success() {
        keepAlive.startKeepAlive({
          success(status) {
            console.log('运行状态：', status.running)
            keepAlive.getKeepAliveForegroundServiceComplianceReport({
              success(report) { console.log('前台服务检查：', report.summaryText) }
            })
          },
          fail(err) { console.error('启动失败：', err); keepAlive.unregister({}) }
        })
      },
      fail(err) { console.error('配置失败：', err); keepAlive.unregister({}) }
    })
  },
  fail(err) {
    console.error('注册保活失败：', err)
  }
})

foregroundServiceType 默认是 none，仅注册、启动不会自动获得 Android 前台服务。请按实际业务选择服务类型；上例的 dataSync 用于数据处理期间，不用于无限期空转。系统可限制启动和运行时长。

业务不再需要后台运行时，主动停止并取消注册：

keepAlive.stopKeepAlive({
  success() {
    keepAlive.unregister({
      success() {
        console.log('保活已停止')
      }
    })
  }
})

模块一：连接守护

适合设备连接、消息连接或页面轮询。业务在收到连接成功、消息到达或关键操作完成时记录一次心跳；运行事件可以用于更新页面状态或写入业务日志。sendHeartbeat 只更新插件本地计数和时间，不会创建连接、发送网络请求或自动重连。

keepAlive.setOnKeepAliveEvent({
  listener(event) {
    console.log('运行事件：', event.name)
  }
})

function reportDeviceOnline(deviceId: string) {
  keepAlive.sendHeartbeat({
    tag: 'device-online',
    payload: { deviceId },
    success(result) {
      console.log('心跳已记录：', result)
    }
  })
}

模块二：周期任务

适合订单同步、设备巡检、待办刷新等需要定时执行的业务。完成前面的注册和启动后，插件按间隔通知业务；业务完成后才回传结果。下面实际写入并读回一条本地存储记录，完整示例使用文件写读。

keepAlive.setOnKeepAliveTaskListener({
  listener(event) {
    try {
      const record = Date.now().toString()
      uni.setStorageSync('keepalive-demo-record', record)
      if (uni.getStorageSync('keepalive-demo-record') != record) {
        keepAlive.reportKeepAliveTaskResult({ taskId: event.taskId, result: 'failure', message: '本地记录读回不一致' })
        return
      }
      keepAlive.reportKeepAliveTaskResult({ taskId: event.taskId, result: 'success', message: '本地记录写入并读回成功' })
    } catch (error) {
      keepAlive.reportKeepAliveTaskResult({ taskId: event.taskId, result: 'failure', message: '本地记录处理失败' })
    }
  }
})

keepAlive.registerKeepAliveTask({
  task: {
    taskId: 'local-record',
    title: '本地记录',
    intervalMs: 5000,
    runImmediately: true
  },
  success(tasks) {
    console.log('已注册任务：', tasks)
  },
  fail(err) {
    console.error('任务注册失败：', err)
  }
})

停止这个任务时调用 unregisterKeepAliveTask({ taskId: 'local-record' })；页面卸载时解绑本页面设置的监听。网络业务请在请求真正成功或失败后再报告，不要在发出请求时就报告成功。

模块三：策略与运行提示

适合不想逐项配置的项目。先选择贴近业务的预设，再按需修改通知文字或其他配置。

keepAlive.applyKeepAlivePreset({
  presetId: 'balanced',
  startImmediately: true,
  success(result) {
    console.log('已应用策略：', result.presetId)
  },
  fail(err) {
    console.error('策略应用失败：', err)
  }
})

keepAlive.setNotice({
  title: '设备服务运行中',
  content: '正在保持设备连接',
  success() {
    console.log('运行提示已更新')
  }
})

模块四：状态检查与问题提示

适合在设置页或运维页展示当前状态。报告会给出是否可用、当前得分和建议处理项；业务可以直接把建议展示给用户或记录到日志。

keepAlive.getKeepAliveReadinessReport({
  success(report) {
    if (report.ready) {
      console.log('当前可以正常使用保活')
      return
    }

    console.log('需要处理：', report.nextSteps)
  },
  fail(err) {
    console.error('状态检查失败：', err)
  }
})

keepAlive.getKeepAliveHealthReport({
  success(report) {
    console.log('当前状态：', report.level)
    console.log('建议：', report.recommendations)
  }
})

模块五：定时心跳

适合按固定节奏记录本地状态、无需注册完整业务任务的场景。先监听定时事件，再记录本地业务心跳。sendHeartbeat 只更新本地心跳计数和时间，不执行网络上报；需要向服务端上报时，由业务在事件中发起自己的网络请求。

keepAlive.setOnStableTimerListener({
  listener(event) {
    keepAlive.sendHeartbeat({
      tag: 'periodic-report',
      payload: { tick: event.tick },
      success() {
        console.log('已记录本地心跳')
      }
    })
  }
})

keepAlive.startStableTimer({
  intervalMs: 60000,
  tag: 'periodic-report',
  success() {
    console.log('定时心跳已启动')
  }
})

不需要继续定时记录时调用：

keepAlive.stopStableTimer({
  success() {
    console.log('定时心跳已停止')
  }
})

API 用途速查

完整调用示例见页面各分类中的“更多功能”；公共参数类型见插件的 utssdk/interface.uts。

常用配置

只在确有业务需要时传入配置。下面列出首次接入最常用的字段。

错误码说明

errSubject 为 lizhao-app-keepalive。保留原始错误码与错误说明，再按下表处理。

注意事项

App 首次接入或修改原生 UTS、权限、Manifest、后台服务配置后，需重新原生联编并安装匹配源码的自定义基座或正式包；Harmony 修改原生模块后需重建匹配 HAP。仅更新页面、wgt 或 appResource 不能替换旧包中的原生实现。

支持平台

常见问题

可以保证应用永远不被系统停止吗？

不能。不同手机和系统对后台运行的限制不同。插件会明确返回当前状态和建议，但不承诺绕过系统或厂商限制。

应该选择哪种策略？

一般业务从 balanced 开始；对设备在线、消息连接或重要同步要求较高时，再评估 strong；只有明确的高强度业务需求才使用 ultra。

如何知道周期任务有没有执行？

使用 getKeepAliveTaskStatuses 查询任务状态，或在 setOnKeepAliveTaskListener 中记录每次触发和业务回执。

业务退出时要做什么？

不再需要后台处理时，按 stopKeepAlive、unregister 的顺序释放运行状态；不再需要定时心跳时，同时调用 stopStableTimer。

联系作者

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列 UTS 插件

以下为作者已上架的 UTS 插件，详情见各市场页面或作者主页。