更新记录

1.0.2（2026-01-09）

1.可以不开启定位也能后台音视频保活，可以持续音视频通话

平台兼容性

uni-app(4.71)

uni-app x(4.71)

uni-keeplive

iOS 后台保活插件（UTS 实现）

简介

uni-keeplive 是一个专为 iOS 平台设计的后台保活插件，使用 UTS（Uni-app TypeScript）语言开发，通过定位服务和音频会话实现应用在后台的持续运行。

功能特性

• ✅ 定位保活：使用 iOS CoreLocation 框架实现后台定位保活
• ✅ 音频保活：使用 AVAudioSession 实现音频会话保活
• ✅ 前后台监听：自动监听应用前后台切换状态
• ✅ 回调机制：提供完整的状态回调接口
• ✅ UTS 原生实现：基于 UTS 语言，性能优异

平台支持

• ✅ iOS 11.0+

安装

方式一：从 uni_modules 导入

如果插件已在项目的 uni_modules 目录中，直接使用即可。

方式二：从插件市场导入

1. 在 HBuilderX 中打开项目
2. 点击菜单栏：工具 -> 插件安装
3. 搜索 uni-keeplive
4. 点击安装

配置

manifest.json 配置

在 manifest.json 中需要配置后台模式和定位权限：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSLocationAlwaysUsageDescription": "应用需要后台定位权限以保持通话连接",
          "NSLocationWhenInUseUsageDescription": "应用需要定位权限以保持通话连接"
        },
        "UIBackgroundModes": [
          "location",
          "audio"
        ]
      }
    }
  }
}

权限说明

• NSLocationAlwaysUsageDescription：始终访问定位权限（用于后台定位保活）
• NSLocationWhenInUseUsageDescription：使用期间访问定位权限
• UIBackgroundModes：后台模式配置
  • location：允许后台定位
  • audio：允许后台音频

API 文档

initSDK()

初始化插件 SDK。

示例：

// #ifdef APP-PLUS
import { initSDK } from '@/uni_modules/uni-keeplive/index.uts'

initSDK()
// #endif

setCallback(callback)

设置状态回调函数。

参数：

回调参数：

type KeepAliveCallbackResult = {
  opt: string,    // 操作类型：'appDidEnterBackground' | 'appWillEnterForeground'
  msg?: string    // 可选消息
}

type KeepAliveCallback = (res: KeepAliveCallbackResult) => void

示例：

// #ifdef APP-PLUS
import { setCallback } from '@/uni_modules/uni-keeplive/index.uts'

setCallback((res) => {
  console.log('保活状态变化:', res.opt)
  if (res.opt === 'appDidEnterBackground') {
    console.log('应用进入后台')
  } else if (res.opt === 'appWillEnterForeground') {
    console.log('应用即将进入前台')
  }
})
// #endif

startLocation(options?)

启动定位保活。

参数：

StartLocationOptions：

type StartLocationOptions = {
  interval?: number  // 定位更新间隔（毫秒），可选
}

注意：

• 首次调用会自动请求定位权限
• 需要用户授权"始终允许"定位权限才能实现后台保活
• 定位保活不会影响音频会话状态

示例：

// #ifdef APP-PLUS
import { startLocation } from '@/uni_modules/uni-keeplive/index.uts'

// 启动定位保活
startLocation()

// 或使用配置
startLocation({
  interval: 1000  // 定位更新间隔（可选）
})
// #endif

stopLocation()

停止定位保活。

示例：

// #ifdef APP-PLUS
import { stopLocation } from '@/uni_modules/uni-keeplive/index.uts'

stopLocation()
// #endif

startMusic()

启动音频保活。

注意：

• 音频保活会激活 AVAudioSession 的播放会话
• 不会播放实际音频文件，仅激活会话
• 如需播放音频，请自行添加音频文件

示例：

// #ifdef APP-PLUS
import { startMusic } from '@/uni_modules/uni-keeplive/index.uts'

startMusic()
// #endif

stopMusic()

停止音频保活。

示例：

// #ifdef APP-PLUS
import { stopMusic } from '@/uni_modules/uni-keeplive/index.uts'

stopMusic()
// #endif

使用示例

基础使用

// #ifdef APP-PLUS
import { 
  initSDK, 
  setCallback, 
  startLocation, 
  stopLocation 
} from '@/uni_modules/uni-keeplive/index.uts'

// 1. 初始化
initSDK()

// 2. 设置回调
setCallback((res) => {
  console.log('保活状态:', res.opt)
})

// 3. 启动定位保活
startLocation()

// 4. 停止定位保活（在适当时机）
// stopLocation()
// #endif

在 App.vue 中使用

// App.vue
<script>
// #ifdef APP-PLUS
import { initSDK, setCallback } from '@/uni_modules/uni-keeplive/index.uts'
// #endif

export default {
  onLaunch() {
    // #ifdef APP-PLUS
    // 初始化保活插件
    initSDK()

    // 设置回调监听
    setCallback((res) => {
      if (res.opt === 'appDidEnterBackground') {
        console.log('应用进入后台，启动保活')
        // 可以在这里启动定位保活
      } else if (res.opt === 'appWillEnterForeground') {
        console.log('应用进入前台，停止保活')
        // 可以在这里停止保活
      }
    })
    // #endif
  }
}
</script>

通话场景使用

在通话场景中，通常需要在通话开始时启动保活，通话结束时停止保活：

// #ifdef APP-PLUS
import { startLocation, stopLocation } from '@/uni_modules/uni-keeplive/index.uts'

// 通话开始
function onCallStart() {
  console.log('通话开始，启动保活')
  startLocation()
}

// 通话结束
function onCallEnd() {
  console.log('通话结束，停止保活')
  stopLocation()
}
// #endif

封装使用（推荐）

在实际项目中，建议封装一个工具类来管理保活逻辑：

// common/keepalive.js
// #ifdef APP-PLUS
import { 
  initSDK, 
  setCallback, 
  startLocation, 
  stopLocation 
} from '@/uni_modules/uni-keeplive/index.uts'

let isInitialized = false

/**
 * 初始化保活
 */
export function initKeepAlive() {
  if (isInitialized) return

  initSDK()
  setCallback((res) => {
    console.log('[KeepAlive] 状态变化:', res.opt)
  })

  isInitialized = true
}

/**
 * 启动保活（仅在特定条件下，如通话中）
 */
export function forceStartKeepAlive(skipCheck = false) {
  if (skipCheck) {
    startLocation()
  } else {
    // 检查条件，如是否在通话中
    const isInCall = checkCallStatus()
    if (isInCall) {
      startLocation()
    }
  }
}

/**
 * 停止保活
 */
export function forceStopKeepAlive() {
  stopLocation()
}

function checkCallStatus() {
  // 检查通话状态的逻辑
  return false
}
// #endif

然后在 App.vue 中使用：

// App.vue
// #ifdef APP-PLUS
import { initKeepAlive } from '@/common/keepalive.js'
// #endif

export default {
  onLaunch() {
    // #ifdef APP-PLUS
    initKeepAlive()
    // #endif
  }
}

注意事项

1. 权限要求

• 定位权限：必须获得用户授权"始终允许"定位权限，才能实现后台定位保活
• 后台模式：必须在 manifest.json 中配置 UIBackgroundModes

2. 审核注意事项

• 使用定位保活需要向用户说明用途，避免被 App Store 审核拒绝
• 建议仅在必要时（如通话中）使用保活功能
• 应用进入前台后应及时停止保活，节省电量

3. 性能考虑

• 定位保活会持续消耗电量，应谨慎使用
• 建议仅在特定场景（如语音通话、导航等）使用
• 应用进入前台后应及时停止保活

4. 兼容性

• 插件仅支持 iOS 11.0 及以上版本
• Android 平台调用不会报错，但不会执行任何操作

常见问题

Q1: 为什么定位保活不生效？

A: 请检查以下几点：

1. 是否已获得"始终允许"定位权限（不是"使用期间"）
2. 是否在 manifest.json 中配置了 UIBackgroundModes 的 location
3. 是否在应用进入后台前调用了 startLocation()

Q2: 定位保活会影响音频播放吗？

A: 不会。定位保活使用 CLLocationManager，不会改变音频会话状态。

Q3: 音频保活和定位保活有什么区别？

A:

• 定位保活：使用定位服务保持应用活跃，不影响音频会话，适合通话场景
• 音频保活：使用音频会话保持应用活跃，会占用音频会话，适合音频播放场景

Q4: 如何判断保活是否生效？

A: 可以通过以下方式验证：

1. 查看控制台日志，确认 startLocation() 已调用
2. 在系统设置中查看应用的定位权限状态
3. 将应用切换到后台，观察应用是否仍在运行

Q5: 应用被系统杀死怎么办？

A: iOS 系统可能会在内存不足时杀死后台应用。这是系统行为，无法完全避免。建议：

1. 优化应用内存使用
2. 使用推送通知来唤醒应用
3. 在应用启动时恢复状态

更新日志

v1.0.2

• 初始版本发布
• 支持定位保活和音频保活
• 支持前后台状态监听
• 提供完整的回调机制

技术支持

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

许可证

MIT License