更新记录

1.0.0（2026-09-09）

首次发布，支持 Android 前台服务保活、开机自启动、后台延迟恢复及失败重试。支持停止保活并退出应用，设备重启后尝试恢复，提供 Vue3 使用示例。

平台兼容性

uni-app(4.25)

whd.AndroidKeepAlive.uts

Android 保活与开机自启动插件。以下示例用于普通 uni-app 的 Vue3 项目，UTS 调用直接写在 .vue 文件中。

接入

1. 将插件的 package.json 和 utssdk 放入项目的 uni_modules/whd-AndroidKeepAlive/。
2. 使用 HBuilderX 4.25 或以上版本制作 Android 自定义调试基座。
3. 运行项目时选择包含该插件的自定义基座。修改插件原生代码后需重新制作基座。

Android 最低版本为 5.0（API 21）。打包架构必须与设备匹配，RK3288 等 32 位工业机需勾选 armeabi-v7a。

App.vue：启动及前后台处理

将生命周期内容合并到项目现有的 App.vue，不要重复定义。

<script>
// #ifdef APP-PLUS
import {
  startKeepAlive,
  setKeepAliveForeground
} from '@/uni_modules/whd-AndroidKeepAlive'
// #endif

export default {
  onLaunch() {
    this.callKeepAlive(() => {
      // #ifdef APP-PLUS
      return startKeepAlive({
        channelName: '后台服务',
        notificationTitle: '应用运行中',
        notificationContent: '点击返回应用',
        restartDelayMs: 5000
      })
      // #endif
    })
  },
  onShow() {
    this.reportForeground(true)
  },
  onHide() {
    this.reportForeground(false)
  },
  methods: {
    callKeepAlive(action) {
      // #ifdef APP-PLUS
      if (uni.getSystemInfoSync().platform !== 'android') return
      try {
        const result = action()
        if (!result.success) {
          uni.showToast({ title: result.message, icon: 'none' })
        }
      } catch (error) {
        uni.showToast({ title: String(error), icon: 'none' })
      }
      // #endif
    },
    reportForeground(visible) {
      this.callKeepAlive(() => {
        // #ifdef APP-PLUS
        return setKeepAliveForeground(visible)
        // #endif
      })
    }
  }
}
</script>

本例在应用启动时开启保活。正式业务需将启动调用放在隐私授权完成后。onShow、onHide 只上报前后台状态，不重新开启已停止的保活；请保留这两个调用。

Vue3 页面

manifest.json 设置 "vueVersion": "3"。应用生命周期仍使用上面的 App.vue。

<template>
  <view>
    <button @click="start">启动保活</button>
    <button @click="stop(false)">停止保活</button>
    <button @click="stop(true)">停止保活并退出</button>
    <text>{{ message }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue'
// #ifdef APP-PLUS
import { startKeepAlive, stopKeepAlive } from '@/uni_modules/whd-AndroidKeepAlive'
// #endif

const message = ref('')

function execute(action) {
  // #ifdef APP-PLUS
  if (uni.getSystemInfoSync().platform !== 'android') return
  try {
    const result = action()
    message.value = result.message
  } catch (error) {
    message.value = String(error)
  }
  // #endif
}

function start() {
  execute(() => {
    // #ifdef APP-PLUS
    return startKeepAlive({ restartDelayMs: 5000 })
    // #endif
  })
}

function stop(exitApp) {
  execute(() => {
    // #ifdef APP-PLUS
    const result = stopKeepAlive()
    if (result.success && exitApp) plus.runtime.quit()
    return result
    // #endif
  })
}
</script>

查询状态

在需要查询状态的 .vue 文件中导入 getKeepAliveStatus，在页面方法或生命周期内调用。仅在 Android App 端执行：

const status = getKeepAliveStatus()

startKeepAlive() 成功只表示启动请求已提交。需要确认服务运行时，应随后查询 serviceRunning；启动失败后可再次调用 startKeepAlive()。

使用说明

• restartDelayMs 默认 1500 毫秒，范围 1000–60000；以上示例显式设置为 5000 毫秒。
• channelName、notificationTitle、notificationContent 均可选。不传时使用插件默认值，标题默认使用应用名称。
• 切到后台或划除任务后开始恢复计时，提前返回前台会取消。
• 未收到前台确认时，按 3、6、12 秒间隔额外重试 3 次；最后一次再等待 12 秒确认，达到上限后结束本轮尝试。返回前台或停止保活会取消重试。
• stopKeepAlive() 停止本次开机期间的自动恢复，但保留开机自启动登记。只有停止成功后才调用 plus.runtime.quit()。
• 设备重启后，插件通过开机次数或系统启动标识确认重启并恢复。两者均不可读时保持停止状态，需要手动启动保活。
• 按上述 App.vue 接入后，再次手动打开应用也会重新开启保活。
• 恢复时间、开机广播和后台打开界面受系统调度及设备管理策略影响。强行停止、清除应用数据不保证自动恢复。