更新记录

1.6.1（2026-04-19） 下载此版本

新增功能

• 调试日志控制

  • 新增 setDebugLogEnabled(enabled) 方法，控制是否输出调试日志
  • 新增 isDebugLogEnabled() 方法，获取调试日志开关状态
  • 默认关闭调试日志，仅输出错误日志

• 定位轮询间隔配置

  • 新增 setLocationPollingInterval(intervalMs) 方法，自定义定位轮询间隔
  • 新增 getLocationPollingInterval() 方法，获取当前轮询间隔
  • 最小间隔限制为 1000ms，防止频繁定位消耗电量

问题修复

• UTS 类型转换问题修复

  • 修复 java.lang.Integer cannot be cast to java.lang.Long 类型转换错误
  • 修复 java.lang.Float cannot be cast to java.lang.Integer 类型转换错误
  • 使用 .toLong() 替代 as Long 进行类型转换
  • 使用 java.lang.Math.round() 进行 Float 到 Int 的安全转换

• Map 类型兼容性问题修复

  • 修复 hasPermissions() 返回的 Map 类型在 JS 端无法访问的问题
  • 将 Map<string, boolean> 改为 UTSJSONObject，支持 JS 端直接属性访问

• 调试日志开关失效问题修复

  • 将定位模块中的调试日志从 console.log 改为 debugLog 函数
  • 确保调试日志开关能正确控制日志输出

技术优化

• 遵循 UTS 编译器已知问题规范，避免类型转换陷阱
• 优化日志输出，区分调试日志和错误日志

1.4.1（2026-04-18） 下载此版本

UTS 编译器兼容性修复

• 修复 iOS 平台编译错误

  • 修复 performSelector Swift 命名参数语法问题
  • 改用 UTS 兼容的 perform(selector) 调用

• 修复 Android 平台编译错误

  • 修复匿名类构造函数问题（UTS 不支持匿名类构造函数）
  • 将 LocationListener 匿名类改为命名类 LocationListenerImpl
  • 将 Runnable 匿名类改为命名类 TimerRunnableImpl
  • 修复 shouldShowRequestPermissionRationale 方法调用问题
  • 修复数组类型转换问题，使用 toTypedArray() 转换

• 代码规范优化

  • 遵循 UTS 编译器已知问题规范
  • 移除不支持的语法模式
  • 确保三端代码一致性

1.1.2（2026-03-16） 下载此版本

修复问题

• 修复iOS平台UTS语法兼容性问题
  • 移除Swift命名参数语法（如 URL(string:)、Timer.scheduledTimer(withTimeInterval:)）
  • 使用 NSURL.URLWithString() 替代 URL(string:)
  • 使用 ES6 标准 setInterval/clearInterval 实现定时器功能
• 修复Android平台UTS语法兼容性问题
  • 修复类名与导出函数冲突问题（KeepLive 类改名为 KeepLiveImpl）
  • 修复 Icon.createWithResource 参数类型问题
  • 修复 List 遍历问题，使用 iterator() 替代 toArray()
  • 修复 CrashHandler 接口实现，使用 Throwable 类型
  • 修复 Notification.Builder 链式调用问题
  • 修复多处 number 到 Int/Long 类型转换问题

优化改进

• iOS平台定时器使用标准ES6 API实现，提高兼容性
• Android平台前台服务通知使用 Icon.createWithResource() API
• 统一所有平台的定时器实现方式

平台兼容性

uni-app(5.03)

uni-app x(5.03)

cy-Keepalive 应用保活插件

插件简介

cy-Keepalive 是一款专为 UniApp 应用设计的保活插件，支持 Android、iOS、鸿蒙三平台。该插件复刻自 android-keeplive 插件，通过多种保活策略确保应用在后台持续运行，防止系统自动终止进程，维持关键服务的稳定运行。

项目架构

插件采用模块化架构设计，各平台代码按功能模块拆分，index.uts 仅作为入口文件：

utssdk/
├── interface.uts          # 接口定义（跨平台共享）
├── unierror.uts           # 错误处理
├── app-android/           # Android 平台
│   ├── index.uts          # 入口文件
│   ├── types.uts          # 类型定义
│   ├── notification.uts   # 通知管理
│   ├── wakelock.uts       # 唤醒锁管理
│   ├── music.uts          # 后台音乐
│   ├── permission.uts     # 权限管理
│   ├── timer.uts          # 定时器
│   ├── receiver.uts       # 广播接收器
│   └── location.uts       # 后台持续定位
├── app-ios/               # iOS 平台
│   ├── index.uts          # 入口文件
│   ├── types.uts          # 类型定义
│   ├── notification.uts   # 通知管理
│   ├── wakelock.uts       # 唤醒锁管理
│   ├── permission.uts     # 权限管理
│   ├── timer.uts          # 定时器
│   └── location.uts       # 后台持续定位
└── app-harmony/           # 鸿蒙平台
    ├── index.uts          # 入口文件
    ├── types.uts          # 类型定义
    ├── notification.uts   # 通知管理
    ├── wakelock.uts       # 唤醒锁管理
    ├── permission.uts     # 权限管理
    ├── timer.uts          # 定时器
    └── location.uts       # 后台持续定位

架构优势

• 模块化设计 - 每个功能独立成模块，职责单一
• 易于维护 - 修改某功能只需修改对应模块
• 代码复用 - 模块间依赖清晰，可复用
• 入口简洁 - index.uts 仅负责组合各模块

平台支持

安装方式

1. 将 uni_modules/cy-Keepalive 目录复制到项目的 uni_modules 目录下
2. 在 HBuilderX 中重新编译项目

保活策略说明

Android 平台

iOS 平台

鸿蒙平台

API 文档

基本使用

// #ifdef APP
import { KeepLive } from '@/uni_modules/cy-Keepalive'
// #endif

// 创建实例
const keep = new KeepLive()

// 设置通知配置
keep.setTitle("app")
keep.setContent("app is running")
keep.setSmallIcon("icon")

// 添加回调
keep.onAddBackgroundCallback((isBackground: boolean) => {
  console.log("后台运行状态: " + isBackground)
})

keep.onAddScreenListenerCallback((isScreenOn: boolean) => {
  console.log("屏幕状态: " + isScreenOn)
})

keep.onAddNotificationClickListener((data: string) => {
  console.log("通知点击: " + data)
})

// 设置唤醒锁
keep.setWakeLock(1, "keeptag")

// 启动保活
keep.register()

// 启动系统定时器
keep.onStartCSystemTimer(60, () => {
  console.log("定时器触发")
  keep.acquire(1000) // 唤醒1秒
})

完整API列表

平台支持标识：✅ 支持 | ❌ 不支持 | ⚠️ 部分支持

通知相关

保活控制

权限相关

唤醒锁

后台音乐

回调

其他功能

定时器

权限管理

后台持续定位

LocationConfig 定位配置

type LocationConfig = {
  priority: number      // 精度优先级：0=高精度, 1=平衡, 2=低功耗
  interval: number      // 定位更新间隔（毫秒），默认1000
  minDistance: number    // 最小更新距离（米），默认0
}

LocationInfo 位置信息

type LocationInfo = {
  latitude: number      // 纬度
  longitude: number     // 经度
  altitude: number      // 海拔（米）
  accuracy: number      // 精度（米）
  speed: number         // 速度（米/秒）
  bearing: number       // 方向（度）
  timestamp: number     // 时间戳（毫秒）
  provider: string      // 定位提供者
}

定位使用示例

// 开启调试日志（可选，用于排查问题）
keep.setDebugLogEnabled(true)

// 配置定位参数
keep.setLocationConfig({
  priority: 0,        // 高精度模式
  interval: 1000,     // 每秒更新
  minDistance: 0      // 无最小距离限制
})

// 设置定位轮询间隔（可选，默认2000ms，最小1000ms）
keep.setLocationPollingInterval(3000)

// 开始持续定位
keep.startLocationUpdates(
  (location: LocationInfo) => {
    console.log(`纬度: ${location.latitude}, 经度: ${location.longitude}`)
    console.log(`精度: ${location.accuracy}m, 提供者: ${location.provider}`)
  },
  (error: string) => {
    console.log(`定位错误: ${error}`)
  }
)

// 监听网络状态变化
keep.onNetworkStatusChange((isConnected: boolean) => {
  console.log(`网络状态: ${isConnected ? '已连接' : '已断开'}`)
})

// 获取最后已知位置
const lastLocation = keep.getLastKnownLocation()
if (lastLocation != null) {
  console.log(`最后位置: ${lastLocation.latitude}, ${lastLocation.longitude}`)
}

// 停止定位
keep.stopLocationUpdates()

// 关闭调试日志
keep.setDebugLogEnabled(false)

智能定位策略说明

本插件采用并行定位策略，而非优先级选择机制：

• Android：同时启用GPS和Network定位提供者，通过智能位置选择算法自动选择最佳位置
• iOS：配置activityType为导航类型，GPS卫星定位不依赖网络
• 鸿蒙：使用geoLocationManager持续定位，支持多种定位场景
• 网络状态感知：实时监测网络变化，动态调整定位策略，确保无缝过渡
• 离线定位：GPS卫星定位完全不依赖网络，无网络环境下仍可获取定位数据

PermissionType 权限类型

PermissionStatus 权限状态

type PermissionStatus = {
  granted: boolean           // 是否已授权
  shouldShowRationale: boolean  // 是否应该显示解释（用户拒绝过）
  canRequest: boolean        // 是否可以请求
}

权限使用示例

// 检查权限
const status = keep.checkPermission('camera')
if (!status.granted) {
  keep.requestPermission('camera', (granted) => {
    if (granted) {
      console.log('相机权限已授权')
    } else {
      keep.openPermissionSettings()
    }
  })
}

// 批量检查权限
const permissions = ['camera', 'microphone']
const results = keep.hasPermissions(permissions)
results.forEach((granted, permission) => {
  console.log(`${permission}: ${granted ? '已授权' : '未授权'}`)
})

// 打开电池优化设置（Android）
keep.openBatteryOptimizationSettings()

完整使用示例

<template>
  <view class="container">
    <view class="status-card">
      <text class="title">保活状态</text>
      <text class="status">{{ isRunning ? '运行中' : '已停止' }}</text>
      <text class="info">运行时间: {{ formatTime(liveTime) }}</text>
    </view>

    <view class="btn-group">
      <button type="primary" @click="startKeepAlive">启动保活</button>
      <button type="warn" @click="stopKeepAlive">停止保活</button>
      <button @click="checkStatus">检查状态</button>
    </view>
  </view>
</template>

<script>
// #ifdef APP
import { KeepLive } from '@/uni_modules/cy-Keepalive'
// #endif

export default {
  data() {
    return {
      isRunning: false,
      liveTime: 0,
      keep: null
    }
  },

  onLoad() {
    // #ifdef APP
    this.keep = KeepLive()
    this.checkStatus()
    // #endif
  },

  methods: {
    startKeepAlive() {
      // #ifdef APP
      this.keep.setTitle("我的应用")
      this.keep.setContent("应用正在后台运行")
      this.keep.setSmallIcon("icon")

      this.keep.onAddBackgroundCallback((isBackground) => {
        console.log("后台状态: " + isBackground)
      })

      this.keep.setWakeLock(1, "keeptag")
      this.keep.setAutoStartEnable(true)

      if (!this.keep.checkAppNotification()) {
        this.keep.onOpenNotificationSetting((enabled) => {
          this.keep.register()
          if (!this.keep.isIgnoringBatteryOptimizations()) {
            this.keep.requestIgnoreBatteryOptimizations()
          }
        })
      } else {
        this.keep.register()
        if (!this.keep.isIgnoringBatteryOptimizations()) {
          this.keep.requestIgnoreBatteryOptimizations()
        }
      }

      this.keep.onStartCSystemTimer(60, () => {
        console.log("定时器触发")
        this.keep.acquire(1000)
      })

      this.isRunning = true
      // #endif
    },

    stopKeepAlive() {
      // #ifdef APP
      this.keep.unregister()
      this.isRunning = false
      // #endif
    },

    checkStatus() {
      // #ifdef APP
      this.isRunning = this.keep.isRunning()
      this.liveTime = this.keep.getLiveTime()
      // #endif
    },

    formatTime(ms) {
      if (!ms) return '0秒'
      const seconds = Math.floor(ms / 1000)
      const minutes = Math.floor(seconds / 60)
      const hours = Math.floor(minutes / 60)

      if (hours > 0) {
        return `${hours}小时${minutes % 60}分钟`
      } else if (minutes > 0) {
        return `${minutes}分钟${seconds % 60}秒`
      } else {
        return `${seconds}秒`
      }
    }
  }
}
</script>

权限配置

Android 权限

插件已内置必要的权限配置：

• FOREGROUND_SERVICE - 前台服务权限
• FOREGROUND_SERVICE_SPECIAL_USE - 特殊前台服务权限
• WAKE_LOCK - 电源锁权限
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS - 请求忽略电池优化权限
• RECEIVE_BOOT_COMPLETED - 开机自启动权限
• POST_NOTIFICATIONS - 通知权限 (Android 13+)
• INTERNET - 网络权限
• ACCESS_WIFI_STATE - WiFi状态权限
• CHANGE_WIFI_STATE - 修改WiFi状态权限
• ACCESS_NETWORK_STATE - 网络状态权限
• ACCESS_FINE_LOCATION - 精确定位权限
• ACCESS_COARSE_LOCATION - 粗略定位权限
• ACCESS_BACKGROUND_LOCATION - 后台定位权限 (Android 10+)

iOS 配置

插件已内置后台模式配置：

• audio - 后台音频
• fetch - 后台获取
• processing - 后台处理
• location - 后台定位

插件已内置定位权限描述：

• NSLocationWhenInUseUsageDescription - 使用时定位权限描述
• NSLocationAlwaysAndWhenInUseUsageDescription - 始终定位权限描述
• NSLocationAlwaysUsageDescription - 始终定位权限描述（兼容旧版）

鸿蒙配置

插件已内置权限配置：

• ohos.permission.CAMERA - 相机权限
• ohos.permission.MICROPHONE - 麦克风权限
• ohos.permission.READ_CONTACTS - 通讯录读取权限
• ohos.permission.KEEP_BACKGROUND_RUNNING - 后台长时任务权限
• ohos.permission.APPROXIMATELY_LOCATION - 粗略定位权限
• ohos.permission.LOCATION - 精确定位权限
• ohos.permission.LOCATION_IN_BACKGROUND - 后台定位权限

重要说明

回调函数生命周期

重要: HBuilderX 4.25+ 版本后，UTS插件导出方法中的回调函数参数触发一次后会自动回收。

本插件已为所有需要持续触发的回调方法添加 @UTSJS.keepAlive 装饰器，确保回调函数可以多次执行。涉及的方法包括：

• onStartCSystemTimer - 系统定时器回调
• startAleraTask - Alarm定时器回调
• onAddBackgroundCallback - 后台状态回调
• onAddScreenListenerCallback - 屏幕状态回调
• onAddNotificationClickListener - 通知点击回调
• onOpenNotificationSetting - 通知设置回调

参考文档: UTS插件回调函数说明

注意事项

1. 自定义基座: Android/iOS端需要自定义基座才能使用
2. iOS配置: uniapp端需要在manifest.json配置后台运行能力 audio,fetch
3. 合规使用: 请确保保活功能符合应用商店审核规范
4. 用户知情: 使用保活功能时应告知用户
5. 资源消耗: 保活会消耗额外的系统资源，请合理使用
6. 系统限制: 不同厂商ROM对后台限制策略不同

更新日志

v1.6.1

• 新增调试日志控制
  • 新增 setDebugLogEnabled(enabled) 方法，控制是否输出调试日志
  • 新增 isDebugLogEnabled() 方法，获取调试日志开关状态
  • 默认关闭调试日志，仅输出错误日志
• 新增定位轮询间隔配置
  • 新增 setLocationPollingInterval(intervalMs) 方法，自定义定位轮询间隔
  • 新增 getLocationPollingInterval() 方法，获取当前轮询间隔
  • 最小间隔限制为 1000ms
• 问题修复
  • 修复 UTS 类型转换错误（Integer/Long/Float）
  • 修复 Map 类型在 JS 端无法访问的问题
  • 修复调试日志开关失效问题

v1.6.0

• 新增后台持续定位模块
  • 新增 setLocationConfig、startLocationUpdates、stopLocationUpdates、getLastKnownLocation、isLocationEnabled、requestLocationPermission、onNetworkStatusChange API
  • 新增 LocationInfo、LocationConfig、LocationCallback、LocationErrorCallback、NetworkStatusCallback 类型定义
  • 新增 Android/iOS/鸿蒙三平台的 location.uts 模块
  • Android: 同时启用GPS和Network定位提供者，智能位置选择算法
  • Android: 实时监测网络状态变化，动态调整定位策略
  • iOS: 使用CLLocationManager实现后台持续定位
  • 鸿蒙: 使用geoLocationManager实现持续定位
  • 新增 Android 定位相关权限（ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、ACCESS_BACKGROUND_LOCATION）
  • 新增 iOS 后台定位模式及定位权限描述
  • 新增鸿蒙定位相关权限（APPROXIMATELY_LOCATION、LOCATION、LOCATION_IN_BACKGROUND）
  • 新增错误码 9010008（定位服务未启用）、9010009（定位权限未授予）

v1.5.0

• 移除定位模块
  • 移除 setLocationConfig、startLocationUpdates、stopLocationUpdates、getLastKnownLocation、isLocationEnabled、requestLocationPermission API
  • 移除 LocationInfo、LocationConfig、LocationCallback、LocationErrorCallback 类型定义
  • 移除 Android/iOS/鸿蒙三平台的 location.uts 模块
  • 移除 Android 定位相关权限（ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、ACCESS_BACKGROUND_LOCATION）
  • 移除 iOS 后台定位模式及定位权限描述
  • 移除鸿蒙定位相关权限（APPROXIMATELY_LOCATION、LOCATION、LOCATION_IN_BACKGROUND）
  • 权限管理模块保留定位权限类型（location、location_always、background_location）的检查和请求能力

v1.4.1

• UTS 编译器兼容性修复
  • 修复 iOS 平台 performSelector Swift 命名参数语法问题
  • 修复 Android 平台匿名类构造函数问题（改为命名类实现）
  • 修复 Android 平台 shouldShowRequestPermissionRationale 方法调用问题
  • 修复 Android 平台数组类型转换问题
  • 遵循 UTS 编译器已知问题规范

v1.4.0

• 代码架构重构
  • 将三个平台的代码按功能模块拆分
  • index.uts 现在仅作为入口文件
  • 新增模块：types.uts、notification.uts、wakelock.uts、permission.uts、timer.uts
  • Android 平台额外新增：music.uts、receiver.uts
  • 提高代码可维护性和可读性
• 多端一致性改进
  • iOS 实现本地通知功能（使用 UserNotifications 框架）
  • iOS 实现唤醒锁功能（使用后台任务）
  • iOS 支持打开 URL Scheme 和应用设置
  • iOS 支持切换到后台功能
  • 大部分 API 实现双平台一致性
• 鸿蒙平台完善
  • 实现权限检查和请求功能（使用 abilityAccessCtrl）
  • 添加必要的权限配置
  • 完善接口实现，确保三端一致性

v1.3.0

• 新增权限管理模块
  • 支持检查和请求各种权限（相机、麦克风、通知等）
  • 支持批量权限检查和请求
  • 新增打开系统设置页面方法（电池优化、定位设置等）
  • Android 支持电池优化白名单检查和设置

v1.1.3

• 修复iOS平台编译错误
• 修复回调函数释放问题，添加@UTSJS.keepAlive装饰器

v1.1.2

• 修复iOS/Android平台UTS语法兼容性问题

v1.1.1

• 修复接口定义方法名拼写错误
• 优化各平台接口实现

v1.1.0

• 完全重构，复刻 android-keeplive 插件全部功能
• 新增鸿蒙平台支持
• 新增后台无声音乐保活
• 新增系统定时器、Alarm定时器
• 新增通知管理功能
• 新增屏幕状态监听
• 新增崩溃自动重启

v1.0.0

• 初始版本发布

技术支持

如有问题，请提交 Issue 或联系开发者。