更新记录

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 端仍需重新原生联编或制作匹配自定义基座。

1.0.3（2026-07-22）

• 修复 HBuilderX 5.15 更严格类型检查下，公共 RegisterOptions/KeepAliveBaseOptions 直接传入 Android AndroidBaseCallbackOptions 触发的四处 error17。
• Android 根入口改为显式构造平台 options 并完整复制 success/fail/complete 与注册配置，避免用运行时类强转掩盖编译错误；公共 API 和保活状态机保持不变。
• 同步 package、README、Android PLUGIN_VERSION 及多端降级报告到 1.0.3。升级后需重新原生联编或重新打 Android 自定义基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-app-keepalive

lizhao-app-keepalive 用于让需要持续处理业务的应用，在进入后台后更稳定地保持运行状态、记录业务心跳，并按约定执行周期任务。

它能帮你做什么

适用场景

• 设备管理：持续关注设备在线状态，发现连接中断后及时处理。
• 消息与客服：在后台保持业务心跳，避免长时间无状态反馈。
• 订单与工单：定时同步待处理数据，并记录每次执行结果。
• 巡检与上报：按照固定节奏触发巡检、告警检查或状态上报。
• 运营排查：查看当前运行状态，定位通知、系统限制或设置项带来的影响。

开始使用

1. 下载并导入

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

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

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

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

2. 先确认当前平台能力

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

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

3. 启动基础保活

先注册，再启动。下面只设置最常用的心跳间隔和运行提示操作，其余配置会使用插件默认值。

keepAlive.register({
  config: {
    heartbeatIntervalMs: 15000,
    notificationActionsEnabled: true
  },
  success() {
    keepAlive.startKeepAlive({
      success(status) {
        console.log('保活已启动：', status.running)
      },
      fail(err) {
        console.error('启动保活失败：', err)
      }
    })
  },
  fail(err) {
    console.error('注册保活失败：', err)
  }
})

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

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

按业务模块接入

模块一：连接守护

适合设备连接、消息连接或页面轮询。业务在收到连接成功、消息到达或关键操作完成时发送一次心跳；运行事件可以用于更新页面状态或写入业务日志。

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) {
    console.log('开始执行任务：', event.taskId)

    // 在这里执行自己的同步、巡检或上报业务。
    keepAlive.reportKeepAliveTaskResult({
      taskId: event.taskId,
      result: 'success',
      message: '订单同步完成'
    })
  }
})

keepAlive.registerKeepAliveTask({
  task: {
    taskId: 'sync-order',
    title: '订单同步',
    intervalMs: 30000,
    runImmediately: true
  },
  success(tasks) {
    console.log('已注册任务：', tasks)
  },
  fail(err) {
    console.error('任务注册失败：', err)
  }
})

模块三：策略与运行提示

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

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

模块五：定时心跳

适合只需要按固定节奏上报状态、无需注册完整业务任务的场景。先监听定时事件，再在事件中发送业务心跳。

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('定时心跳已停止')
  }
})

按用途找功能

常用配置

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

支持平台

常见错误码

常见问题

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

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

应该选择哪种策略？

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

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

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

业务退出时要做什么？

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

联系方式

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

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。