更新记录

1.0.6（2026-10-06）

• 修复重启后长时间锁屏或息屏导致界面恢复提前耗尽重试次数的问题。
• 在用户解锁后按配置延迟继续恢复，已执行的次数仍计入上限。
• 增加服务解锁广播监听和服务不可用时的定时复查，停止保活可取消等待。
• 补充锁屏诊断及当前版本使用说明

平台兼容性

uni-app(4.25)

安卓开启自动保活插件

whd-autostayalive · 版本 1.0.6 · 普通版免费

为 uni-app / uni-app x 的 Android 应用提供前台服务、开机自启动登记、延迟恢复、权限设置引导及最近 10 次本地错误记录。要求 HBuilderX 4.25.0+、Android 5.0（API 21）+；随附示例为普通 uni-app Vue3。

安装

1. 从插件市场导入，或将插件包解压到 uni_modules/whd-autostayalive/，该目录下直接包含 package.json 与 utssdk/。
2. 制作并安装包含本插件的 Android 自定义基座，运行时选择该基座。修改 UTS、Kotlin 或清单后需重新制作。
3. 本地示例使用项目根目录的 AutoKeepAlive-demo；下载示例 ZIP 后，解压并用 HBuilderX 打开其中的工程。

App.vue 使用示例

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

<script>
// #ifdef APP-PLUS
import {
  startKeepAlive,
  setKeepAliveForeground
} from '@/uni_modules/whd-autostayalive'
// #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 只上报前后台状态，不重新开启已停止的保活；请保留这两个调用。

以上代码用于普通 uni-app；uni-app x 在 Android UTS 生命周期中调用同名 API。完整页面和按钮操作见示例工程。

常用接口

从 @/uni_modules/whd-autostayalive 导入，仅在 Android App 端调用。

启动、停止、前后台上报和设置跳转返回 { success, code, message }。启动请求成功后，用 getKeepAliveStatus().serviceRunning 确认服务是否运行。

startKeepAlive 的可选配置：restartDelayMs（毫秒，默认 1500，范围 1000–60000）、channelName、notificationTitle、notificationContent。示例默认延迟 5 秒，修改前先停止保活。

设置目标支持 app、overlay、battery、background、notifications、alarm、autostart、backgroundLaunch、vendorBattery。

Android 设备测试

已在以下设备上进行测试：

• 安卓工业一体机：Android 7.x、11.x。
• 雷电模拟器：Android 7.x、9.x、14.x。（注意雷电模拟器不支持自启动和顶部标签关闭自启动，雷电模拟器多任务关闭和其他设备不受影响）
• 小米 K30。

使用注意

• 息屏或锁屏时等待，解锁后按配置延迟继续恢复；等待不消耗恢复次数。进入设置、返回前台或停止保活会取消等待。
• 按设备要求分别核对自启动、省电策略和后台弹出界面；“需手动核对”不表示权限已关闭。
• 后台运行、开机广播和自动打开界面受系统及厂商策略影响，不能保证所有设备都能恢复；强行停止应用可能阻止自动启动。
• stopKeepAlive() 停止至设备重启；按示例接入后，再次手动打开应用也会开启保活。退出应用时，先确认停止成功，再调用 plus.runtime.quit()。
• 历史错误会保留，应结合时间判断是否为新错误。遇到接口缺失或 not found，先核对当前插件、自定义基座和实际安装包。

隐私与权限

无广告，不向服务器上传数据。保活配置和最近 10 次错误保存在应用本地；系统、厂商、型号、权限、屏幕及解锁状态仅用于兼容诊断。

插件声明以下权限，需按设备与功能授权；插件不创建悬浮窗：

android.permission.RECEIVE_BOOT_COMPLETED
android.permission.FOREGROUND_SERVICE
android.permission.FOREGROUND_SERVICE_SPECIAL_USE
android.permission.POST_NOTIFICATIONS
android.permission.SYSTEM_ALERT_WINDOW
android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
android.permission.SCHEDULE_EXACT_ALARM

普通版免费，不提供独立源码授权，使用范围见 license.md。

联系方式