更新记录

1.0.1（2026-08-14）

changelog

1.0.0（2026-08-13）

• 首发：Android / iOS / 鸿蒙 Next 三端后台保活定位
• 内置权限检测、申请、跳设置与 Android 厂商白名单深链
• 本地环缓 + 可选 HTTPS 批量上报
• 统一错误码、demo、manifest / App Store 审核文案模板

平台兼容性

uni-app(3.8.2)

keepalive-location

UTS 后台保活定位｜Android iOS 鸿蒙 Next｜外勤巡检后台持续 GPS 定位

三端 UTS 插件：后台定位启停、点位回调、权限内置、状态事件、本地环缓、可选 HTTPS 上报。普通授权 / 源码授权。

功能

• 后台定位开启 / 关闭；点位回调（经纬度、精度、速度、时间戳、高度）
• Android：前台服务 + 常驻通知，适配 8.0–14，唤醒锁；厂商自启动/白名单深链
• iOS：Background Modes location，Always 权限分步；挂起状态点位回调；附 App Store 审核文案模板
• 鸿蒙 Next：后台定位权限、长时任务自动续期、配额/取消监听
• 权限检测、申请、跳转设置（内置，不另发权限插件）
• 状态监听：权限丢失、系统限制、长时任务过期、服务异常、上报失败
• 统一错误码、demo、manifest 完整配置模板

安装

市场插件 ID 为 keepalive-location。本地目录名请与 ID 一致。

将本目录放入项目 uni_modules/keepalive-location，制作自定义调试基座后运行。

import {
    initTrack,
    startLocation,
    stopLocation,
    getStatus,
    onLocationUpdate,
    onStatusChange,
    destroy,
    requestPermissions,
    checkPermissions,
    openAppSettings,
    openVendorKeepAliveSettings,
    getCachedPoints,
    clearCachedPoints,
    flushUpload,
    getTrackCapabilities
} from '@/uni_modules/keepalive-location'

API

注意：对外初始化方法名为 initTrack（避免 iOS/Swift 保留字 init 导致云打包失败）。

坐标转换（插件点位为系统 WGS84）

返回值为 JSON 字符串（UTS 自定义对象跨 JS 桥易丢字段），需 JSON.parse。

import { toGaode, toBaidu, convertGpsPoint } from '@/uni_modules/keepalive-location'

onLocationUpdate((point) => {
  const gaode = JSON.parse(toGaode(point.latitude, point.longitude))
  const baidu = JSON.parse(toBaidu(point.latitude, point.longitude))
  // gaode.latitude / gaode.longitude
})

initTrack 选项

await initTrack({
    notificationTitle: '位置服务运行中',      // Android 通知标题
    notificationContent: '正在进行后台定位', // Android 通知内容
    enableWakeLock: true,                      // Android 唤醒锁
    enableForegroundService: true,             // Android 正式接入务必 true（后台保活）
    enableCache: true,
    cacheMaxPoints: 2000,
    upload: {                                  // 不传则不上报
        url: 'https://example.com/track',
        headers: [{ key: 'Authorization', value: 'Bearer xxx' }],
        batchSize: 20,
        intervalMs: 15000,
        includeDeviceId: false
    }
})

Android 前台服务（FGS）正式接入说明

正式接入 checklist：

1. initTrack({ enableForegroundService: true, notificationTitle, notificationContent })
2. 先 requestPermissions()（定位 + 后台定位 + 通知；Android 13+ 通知权限）
3. 制作自定义调试基座 或云打包（把 TrackForegroundService.kt + Manifest 打进包）
4. 开启定位后应出现常驻通知；没有通知却闪退 = FGS 未正确进包或权限不足
5. 建议引导用户关掉电池优化、加厂商白名单：openVendorKeepAliveSettings()

Demo 工程为避闪退可暂关 FGS；接入业务 App 时请打开。

startLocation 选项

await startLocation({
    distanceFilter: 10,   // 米
    desiredAccuracy: 50   // 米，映射 high/balanced/low
})

GpsPoint

上报 JSON

{
    "deviceId": "optional",
    "platform": "android|ios|harmony",
    "points": [{ "latitude": 0, "longitude": 0, "accuracy": 0, "speed": 0, "altitude": 0, "timestamp": 0, "provider": "gps" }]
}

仅支持 HTTPS POST。

错误码 803xxxx

Android manifest 模板

在 manifest.json → app-plus → distribute → android 中确保权限（插件 AndroidManifest.xml 也会合并）：

• ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION
• ACCESS_BACKGROUND_LOCATION
• FOREGROUND_SERVICE / FOREGROUND_SERVICE_LOCATION
• POST_NOTIFICATIONS
• WAKE_LOCK
• REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
• INTERNET（仅当使用上报）

Android 14 需声明前台服务类型 location（本插件已带 Service）。

厂商白名单：调用 openVendorKeepAliveSettings()，覆盖小米 / 华为荣耀 / OPPO / vivo / 三星常见页；失败回落应用设置。深链因系统版本可能失效。

iOS 配置模板

manifest.json：

"app-plus": {
    "ios": {
        "capabilities": {
            "UIBackgroundModes": ["location"]
        },
        "privacyDescription": {
            "NSLocationWhenInUseUsageDescription": "需要在使用期间获取您的位置，用于外勤巡检与轨迹记录",
            "NSLocationAlwaysAndWhenInUseUsageDescription": "需要在后台持续获取您的位置，用于外勤巡检、轨迹记录与现场任务核验",
            "NSLocationAlwaysUsageDescription": "需要在后台持续获取您的位置，用于外勤巡检、轨迹记录与现场任务核验"
        }
    }
}

App Store 审核文案模板（可直接改写提交）

用途说明（App Review Notes）：

本应用为外勤巡检 / 现场作业类工具。开启「始终」定位后，员工在巡检途中将 App 置于后台或锁屏时，仍需持续记录 GPS 轨迹，用于任务核验、路线留痕与异常位移告警。我们仅在用户主动开始巡检任务后采集位置，任务结束后立即停止；位置数据用于业务方自有服务器（可选上报），不用于广告追踪。

权限弹窗文案建议： 与上方 privacyDescription 保持一致，强调「外勤巡检 / 轨迹记录」。

鸿蒙 Next 配置

插件 config.json 已声明：

• ohos.permission.LOCATION / APPROXIMATELY_LOCATION
• ohos.permission.LOCATION_IN_BACKGROUND
• ohos.permission.KEEP_BACKGROUND_RUNNING
• ohos.permission.INTERNET（上报时）

主工程 Ability 需配置 backgroundModes: ["location"]（制作包含鸿蒙的自定义基座时请确认合并结果）。长时任务类型为 LOCATION；插件会定时续期并监听取消事件（long_task_expired / 8031004）。

最小示例

import {
    initTrack,
    requestPermissions,
    onLocationUpdate,
    onStatusChange,
    startLocation,
    stopLocation,
    destroy
} from '@/uni_modules/keepalive-location'

onLocationUpdate((p) => console.log('point', p))
onStatusChange((s) => console.log('status', s))

await initTrack({ enableCache: true })
await requestPermissions()
await startLocation({ distanceFilter: 10, desiredAccuracy: 50 })
// ...
await stopLocation()
destroy()

隐私声明

1. 本插件申请定位、后台定位、前台服务、通知、唤醒锁、电池优化、鸿蒙长时任务等权限，详见上文。
2. 点位可本地环缓；仅当业务配置 upload.url 时向该地址 HTTPS 上报。插件不默认上传至第三方。
3. 不含广告 SDK。