更新记录

1.2.1（2026-10-25）

兼容蒸汽模式

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

UTS 安卓后台保活与原生 HTTP 任务

Android 前台服务、原生 HTTP 定时请求、限时息屏唤醒、通知停止和厂商设置引导，附可直接运行的演示页。

HBuilderX 5.26+；插件 ID：austin-keep-x；版本 1.2.1。

原生 HTTP 任务需要 Android 6.0+。不支持 iOS、鸿蒙、Web、小程序通用保活。

第 1 步：导入插件

完整目录放到 你的项目/uni_modules/austin-keep-x/。uni_modules 与项目的 manifest.json、pages.json 同级，保留插件全部文件。

项目 manifest.json 无需为本插件重复填写权限、注册服务或勾选模块。插件自带的 utssdk/app-android/AndroidManifest.xml 会在打包时自动合并。

通知授权和手机的后台运行设置需要运行后操作，见第 4 步。

第 2 步：注册演示页

在项目 pages.json 的 pages 数组中添加：

{
  "path": "uni_modules/austin-keep-x/index",
  "style": { "navigationBarTitleText": "安卓后台保活", "disableScroll": true }
}

在自己的页面中打开演示页：

uni.navigateTo({ url: '/uni_modules/austin-keep-x/index' })

uni-app x 使用插件内 index.uvue；普通 uni-app Vue3 使用 index.vue，路由写法相同。

第 3 步：制作并运行自定义基座

1. HBuilderX 选中项目，进入 发行 → 原生 App 云打包 → Android，勾选 制作自定义调试基座。
2. 填写应用包名及签名信息，完成打包并安装新基座。
3. 在运行菜单选择 自定义基座，运行到 Android 手机，打开第 2 步的演示页。

首次导入、更新插件原生代码或权限后需要重打基座；只修改页面、调用参数或文档不需要。入口见 DCloud 自定义基座说明。

第 4 步：体验后台运行

演示页无需填写域名或接口。

1. 按需打开“手机设置”：建议允许后台运行、锁定最近任务；通知未授权时点 允许通知，按弹窗或设置页完成授权。
2. 点 开始体验，等页面显示“服务运行中”。
3. 返回桌面或锁屏，等待至少 60 秒。
4. 回到页面，查看后台新增心跳、离开时长和体验结果。
5. 点 结束体验，停止服务。

体验提供最多 2 分钟息屏运行支持，会增加耗电；到期释放 CPU 唤醒锁，服务仍可运行。结束体验会提前释放，结果保留供查看。已有 HTTP 业务任务时，需先明确结束并清除配置才能体验。

手机设置怎么选

vivo / iQOO 未找到后台开关时：手机设置 → 搜索“后台耗电管理”或“后台高耗电” → 本应用 → 允许后台高耗电。厂商页面可能受系统权限保护，按钮无法保证直达。

打开设置不代表完成授权。通知、电池优化状态可读取；厂商后台高耗电和最近任务锁定需用户确认。完成设置后回到页面，重新开始体验。

体验结果怎么看

每 30 秒记录一次原生心跳，离开 60 秒通常新增约 2 次，系统休眠可能延迟。

返回后的前台心跳不计入本次结果。页面不能自动证明用户已锁屏；心跳也不等于业务成功或全程连续执行。“运行记录”中可查看详细记录。

接入自己的业务

1. 导入并调用保活 API

业务页面从 @/uni_modules/austin-keep-x 导入，即 你的项目/uni_modules/austin-keep-x/ 目录。@/ 为包含 manifest.json 的项目源码目录，不要追加 index.uvue 或 utssdk/app-android。

uni-app x 放在 <script setup lang="uts">；普通 uni-app Vue3 使用 lang="ts"。

import {
  startKeepAlive, getKeepAliveStatus, stopKeepAlive,
  KeepAliveStartOptions
} from '@/uni_modules/austin-keep-x'

// 分别绑定页面的开始、刷新、停止按钮。
function startTask(): void {
  const options: KeepAliveStartOptions = {
    notificationTitle: '后台任务运行中',
    notificationText: '点击返回应用，或停止后台任务',
    autoRestart: true,
    wakeLockTimeoutMs: 0,
    heartbeatIntervalMs: 30000
  }
  const result = startKeepAlive(options)
  console.log('是否接受启动请求', result.ok, result.errMsg)
}
function refreshTask(): void {
  const status = getKeepAliveStatus()
  console.log('服务是否运行', status.running, status.serviceState)
}
function stopTask(): void {
  const result = stopKeepAlive()
  console.log('是否接受停止请求', result.ok, result.errMsg)
}

启动是异步过程，ok 表示接受请求，稍后刷新得到的 running 才是实际状态。插件提供前台服务支持；页面 JS 定时器、WebSocket、录音或定位需要各自原生后台实现。首次启动服务、申请通知权限应在前台页面发起。

需要申请 Android 13+ 通知权限时，在前台按钮中调用：

import {
  requestKeepAliveNotificationPermission, KeepAlivePermissionResult
} from '@/uni_modules/austin-keep-x'

function requestNotification(): void {
  requestKeepAliveNotificationPermission({
    complete: (result: KeepAlivePermissionResult) => {
      console.log('通知是否已授权', result.granted)
    }
  })
}

2. 按需设置息屏唤醒

wakeLockTimeoutMs 默认 0；需要息屏期间继续处理原生任务时，填任务所需时长，最长 600000 毫秒（10 分钟）。到期自动释放、不续期；提前完成时调用：

import { releaseKeepAliveWakeLock } from '@/uni_modules/austin-keep-x'

releaseKeepAliveWakeLock()

唤醒锁不点亮屏幕，会增加耗电，不保证网络可用；Doze 仍可能限制未豁免应用。系统恢复只沿用未到期额度，开机恢复不重新取得旧锁。见 Android 电源限制。

3. 按需使用原生 HTTP 任务

适合状态同步、在线状态上报和定时查询。请求由 Android 原生线程执行，无需先调用 startKeepAlive()。

import {
  startKeepAliveHttpTask, getKeepAliveHttpTaskStatus, stopKeepAliveHttpTask,
  KeepAliveHttpTaskOptions
} from '@/uni_modules/austin-keep-x'

// 分别绑定开始、刷新、停止按钮，替换为自己的 HTTPS 接口。
function startHttpTask(): void {
  const options: KeepAliveHttpTaskOptions = {
    taskId: 'status-sync',
    url: 'https://你的域名/api/status',
    method: 'GET',
    intervalMs: 60000,
    timeoutMs: 15000,
    maxRetries: 2,
    autoRestart: true
  }
  const result = startKeepAliveHttpTask(options)
  console.log('是否接受启动请求', result.ok, result.errMsg)
}
function refreshHttpTask(): void {
  const status = getKeepAliveHttpTaskStatus()
  console.log('服务运行状态 / HTTP 2xx 次数', status.serviceRunning, status.successCount)
}
function stopHttpTask(): void {
  const result = stopKeepAliveHttpTask()
  console.log('是否接受停止请求', result.ok, result.errMsg)
}

同次逻辑请求重试复用 requestId，不同周期生成新 ID；服务端仍需正确去重。停止会尽力取消请求，已到达服务端的操作不会回滚。不要循环续唤醒锁维持请求。

Android 15+ 且 targetSdk 35+：dataSync 后台运行受 6 小时 / 24 小时时限约束，且不能从开机广播启动。触及时限或系统暂停后，读取原因，回前台由用户重新开始。见 Android 超时说明及 dataSync 限制。

4. 按需复制演示页

复制后在 pages.json 注册 pages/keep/index。页面中的 @/uni_modules/austin-keep-x 导入保持原样，插件目录继续保留。

API 与参数

以下 API、类型均从 @/uni_modules/austin-keep-x 导入。

旧设置 API 保持可用，true 只表示页面已打开，不表示用户已授权。新接入建议使用 openKeepAliveSettings()，读取实际去向和后续步骤。

设置跳转与返回字段

import { openKeepAliveSettings, KeepAliveSettingsResult } from '@/uni_modules/austin-keep-x'

const entry: KeepAliveSettingsResult = openKeepAliveSettings('background')
// entry.opened：是否打开了页面；entry.direct：是否直达目标。
// entry.message：向用户展示的后续操作；不能据 opened 推断已授权。

KeepAliveSettingsResult 的 5 个字段均存在：

自启动入口按当前设备尝试；厂商后台高耗电等页面可能受系统权限保护，无法直达时需手动进入。最近任务“锁定”是厂商功能，不能用 Android 的屏幕固定替代。电池豁免与厂商“允许后台高耗电”是不同设置。参见 Android 设置入口与屏幕固定／Lock task 说明。

KeepAliveHttpTaskOptions

所有时间单位为毫秒；范围内需填整数。taskId、url 必填，其余可省略。

普通失败仅对网络错误、408、429、5xx 按上限退避重试；401 等其他 4xx 与重定向不重试，整数秒 Retry-After 最多等待 5 分钟。离线不消耗请求次数，每 30 秒检查；每次完成后再等待 intervalMs，不追补休眠时错过的周期。总超时会结算失败并尽力中断 I/O；系统 DNS 等底层调用可能延迟释放，下一次请求等待前一次退出，不并发叠加。

进程中断时，已发送的 POST 可能处于服务端已处理但客户端未收到结果的状态。无幂等约定时任务暂停并说明原因，避免自动重复提交；配置幂等头仍需服务端正确实现去重，恢复同一请求也不会突破剩余重试次数。

KeepAliveHttpTaskStatus

以下字段全部存在。时间戳为毫秒，未发生为 0；计数为当前任务统计。

HTTP 启动错误码：31001 上下文不可用、31002 参数无效、31003 服务启动失败、31004 本机存储失败、31005 平台不支持、31006 权限或前台启动条件不满足。运行时请求失败在 lastErrorCode / lastErrorMessage 中读取。

KeepAliveStartOptions

KeepAliveResult

KeepAliveStatus

诊断与厂商说明

KeepAliveDiagnostics 包含 lastFailureReason: string、lastFailureAt: number、lastAutoStartEntry: string、lastAutoStartFallback: string、lastReceiverAction: string、lastReceiverAt: number，含义同状态表；recentLogsText: string 是有限条数的本机记录。

通知授权回调

KeepAlivePermissionOptions 的 success?、fail?、complete? 均为 (result: KeepAlivePermissionResult) => void。结果字段为 ok: boolean、granted: boolean、errCode: number、errMsg: string；complete 在本次请求结束后调用。通知未授权不代表禁止前台服务，但通知栏控制可能不可见；另查通知总开关和渠道状态。

插件自动合并的权限与组件

以下内容已在 uni_modules/austin-keep-x/utssdk/app-android/AndroidManifest.xml 声明，项目 manifest.json 无需重复填写，也不需要复制这份 XML。

KeepAliveForegroundService、KeepAliveHttpService、KeepAliveBootReceiver 和设置跳转所需 queries 也由插件合并。组件类名前缀为 uts.sdk.modules.austinKeepX。

发布应用前：普通保活使用 specialUse，在上述插件 XML 中找到 PROPERTY_SPECIAL_USE_FGS_SUBTYPE，把 android:value 改为应用实际的后台任务用途；修改后重新打包。HTTP 使用 dataSync，录音、导航需各自专用实现。见 Android 前台服务类型。

恢复与系统边界

Android 12+ 后台首次启动前台服务受限制，应由用户在可见页面启动。见 前台服务后台启动限制。

Android 13+“活动应用”的停止按钮不会向应用发送回调。插件在下次读取状态或系统恢复前检查退出记录；识别到用户停止后取消恢复，需再次点启动。退出记录跨重启可能丢失，因此开启恢复时，“活动应用”停止后仍可能在下次开机恢复。需要明确取消后续恢复时，使用插件页面或插件通知中的“停止”。 Android 11～13 的退出原因可能同时代表应用更新，遇到无法区分的记录时优先取消恢复，更新后可能需要手动启动。见 Android 用户停止处理说明。

错误处理

没有通知时先查 notificationPermissionGranted、notificationsEnabled、channelBlocked，不要直接判定服务未运行。配置不匹配时查看诊断失败记录。