更新记录

v1.0.0（2026-08-13）

[新增] 首发支持 Android / iOS 双端后台定位保活。

Android 端:基于前台服务(Foreground Service) + 常驻通知 + GPS/网络双源持续定位;适配 Android 14+ 按类型启动前台服务(FGS_TYPE_LOCATION);支持电池优化白名单检测与跳转。

iOS 端:基于 CLLocationManager 后台定位(allowsBackgroundLocationUpdates),info.plist 自动合并 UIBackgroundModes。

统一 API:startKeepAlive / stopKeepAlive / onLocationChange / requestPermission / requestBackgroundPermission / isIgnoringBatteryOptimizations / requestIgnoreBatteryOptimizations / goToAppSettings / isKeepAliveRunning。

平台兼容性

定位保活插件(ts-location-keepalive)

App 后台持续定位保活 UTS 插件,一套代码覆盖 Android / iOS:

• Android:前台服务(Foreground Service)+ 常驻通知 + GPS/网络双源持续定位,兼容 Android 14+(按类型启动前台服务),并提供电池优化白名单引导
• iOS:CLLocationManager 后台定位(始终允许授权),App 退后台后持续回调经纬度

支持 uni-app(Vue2 / Vue3)与 uni-app x。

一、安装

1. 将 uni_modules/ts-location-keepalive 整个目录复制到你项目的 uni_modules/ 下;
2. HBuilderX 中点击「运行」→「运行到手机或模拟器」,选择 自定义基座 运行(UTS 插件必须自定义基座或打包生效);
3. iOS 还需要在项目的 manifest.json → App 模块配置中勾选 定位 模块。

权限声明、iOS 后台模式(UIBackgroundModes=location)、前台服务注册均已内置于插件,云端打包时自动合并,无需手动配置。

二、快速开始

import {
  startKeepAlive,
  stopKeepAlive,
  onLocationChange,
  requestPermission,
  requestBackgroundPermission
} from "@/uni_modules/ts-location-keepalive";

// 1. 注册定位回调(App 前后台都会收到)
onLocationChange((res) => {
  console.log("定位:", res.latitude, res.longitude, res.provider, res.speed);
});

// 2. 申请权限(建议在用户点击"开启"时调用)
async function grant() {
  const ok = await requestPermission();           // 前台定位权限
  if (ok) {
    await requestBackgroundPermission();           // 后台定位权限(Android 11+ 会跳设置页)
  }
}

// 3. 启动保活
startKeepAlive({
  title: "定位保活中",
  content: "正在持续获取位置信息",
  minTimeMs: 2000,      // 定位间隔(ms)
  minDistanceM: 0,      // 移动距离阈值(m)
  useGps: true,         // 开启 GPS
  useNetwork: true      // 开启网络定位
});

// 4. 停止保活
// stopKeepAlive();

三、API

KeepAliveOptions:

LocationResult 回调字段:latitude 纬度、longitude 经度、accuracy 精度(m)、altitude 海拔(m)、speed 速度(m/s)、bearing 方向角、time 时间戳(ms)、provider 定位来源。

四、保活注意事项(重要)

Android

1. 权限:前台定位权限会正常弹窗;后台定位权限(Android 10+)无法直接弹窗,requestBackgroundPermission() 会引导用户跳转设置手动选择「始终允许」;
2. 电池优化:Android 6+ 的 Doze 模式会限制后台,建议在设置页引导用户「忽略电池优化」,可用 isIgnoringBatteryOptimizations() 检测并展示引导;
3. 厂商白名单:小米(神隐模式)、华为、OPPO、vivo、荣耀等 ROM 需要用户在系统设置中开启「自启动 / 后台运行 / 锁屏清理白名单」,可用 goToAppSettings() 引导,各机型路径不同(见下表);
4. Android 14+:必须保留 FOREGROUND_SERVICE_LOCATION 权限(插件已内置),否则启动前台服务会抛异常;
5. 测试间隔:为了省电,线上建议 minTimeMs 不低于 1000ms,minDistanceM 建议 10m 以上。

iOS

1. 授权:后台定位必须「始终允许」授权(requestPermission() 会请求 Always);
2. 审核:App Store 审核需要说明后台定位用途(iOS 商店审核时注意在审核备注中说明有后台定位功能);
3. 真机验证:后台定位无法在模拟器验证,必须使用真机 + 付费开发者账号打包自定义基座;
4. 隐私:iOS 14+ 首次授权会弹「精确定位」开关,用户在设置里关闭精确定位时 accuracy 会大幅下降,属正常现象。

五、常见问题

Q1:导入后真机运行找不到插件 / 提示未编译? UTS 插件必须用「自定义基座」或正式打包运行,不能直接标准基座运行。

Q2:后台几分钟后收不到定位? 先确认:① 已授予后台定位权限;② 已忽略电池优化;③ 已加入厂商后台白名单。Android 上锁屏后建议保持通知常驻(前台服务通知不可滑动清除)。

Q3:华为/小米等机型锁屏后仍被杀? 厂商 ROM 的省电策略是保活最大的敌人,goToAppSettings() + requestIgnoreBatteryOptimizations() 双管齐下引导用户,这是目前唯一可靠的合规方案(不依赖系统漏洞)。

Q4:编译报错怎么办? 本插件为标准 UTS 写法,若你的 HBuilderX 版本较旧,请升级到 3.99+ 或 4.x 最新版;仍报错时把 HBuilderX 控制台报错信息贴出,按提示微调(如 UTSAndroid.requestPermissions 回调签名随版本略有差异)。

六、目录结构

uni_modules/ts-location-keepalive/
├── package.json                    # 插件清单
├── index.uts                       # 跨平台入口(条件编译映射)
├── readme.md
└── utssdk/
    ├── app-android/                # Android 实现
    │   ├── AndroidManifest.xml     # 权限 + 前台服务注册(自动合并)
    │   ├── config.json             # minSdk 等
    │   └── index.uts               # 前台服务 + 持续定位
    └── app-ios/                    # iOS 实现
        ├── info.plist              # 后台定位模式 + 权限文案(自动合并)
        ├── config.json
        └── index.uts               # CLLocationManager 后台定位

七、免责说明

• 保活受系统版本、厂商 ROM 策略影响,本插件采用系统官方允许的「前台服务 / 后台定位」方案,不承诺任何机型 100% 不被杀;
• 后台定位会增加耗电,请按业务需要设置合理的定位间隔;
• 请遵守各应用商店对后台定位、隐私合规的要求。