uni-app 定位打卡插件实操----三端接入、后台定位与 9010002/9010007 排查

0 阅读10分钟

一、wz-location 是什么

wz-location 是一个 uni-app 插件,App 端调用维智原生定位 SDK,微信小程序端走云端融合定位,对 JS 层暴露同一套接口:

  • 单次定位 getOnceLocation / 快速定位 getQuickLocation(Android 5 秒内返回)

  • 前台连续定位 startForegroundLocation,后台连续定位 startBackgroundLocation

  • 返回值直接带结构化地址:address、province/city/district/street、placeName,不用自己再调一次逆地理编码

先说清楚支持范围,免得白干半天:

端支持备注
Android✅minSdk 21,必须自定义调试基座
iOS✅14.0+,必须自己的开发证书做基座
微信小程序✅基础库 2.8.0+,不用基座
H5 / 鸿蒙 / uni-app x / 其他小程序❌跑上去只会收到 9010004

二、调用顺序,先背下来

整条链的顺序是固定的:

agreePrivacy → initSdk(appKey) → 申请系统定位权限 → 定位

页面卸载时补两个清理:stopLocation() 和 offSdkLog()。顺序错了不报错,但定位会直接失败——比如没 agreePrivacy 就 initSdk,错误码 9010005;没初始化就定位,9010006。

import {
  agreePrivacy, initSdk,
  getOnceLocation, getQuickLocation,
  startForegroundLocation, startBackgroundLocation,
  stopLocation, setLogEnabled, onSdkLog, offSdkLog
} from '@/uni_modules/wz-location'

安装方式:把插件市场的 uni_modules/wz-location 导入工程,或直接拷贝这个目录。

三、三个端的 manifest 配置

Android

"app-plus" : {
    "distribute" : {
        "android" : {
            "minSdkVersion" : 21,
            "targetSdkVersion" : 30,
            "permissions" : [
                "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
                "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
                "<uses-permission android:name=\"android.permission.ACCESS_BACKGROUND_LOCATION\"/>",
                "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE\"/>",
                "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE_LOCATION\"/>",
                "<uses-permission android:name=\"android.permission.READ_PHONE_STATE\"/>"
            ]
        }
    }
}

三个要点:

  1. ACCESS_BACKGROUND_LOCATION 只在 Android 10 且 targetSdkVersion >= 29 时才真正生效,配低了后台定位申请不出来。

  2. READ_PHONE_STATE 用于辅助定位,隐私政策里要一并说明,应用市场审核会看。

  3. 后台定位服务由插件自己声明(com.wayz.location.WzService),不要重复写。

iOS

"ios" : {
    "UIBackgroundModes" : "location",
    "privacyDescription" : {
        "NSLocationWhenInUseUsageDescription" : "需要使用位置信息进行定位",
        "NSLocationAlwaysAndWhenInUseUsageDescription" : "需要使用位置信息进行后台定位"
    }
}

用途描述没写进 Info.plist,系统弹窗根本不会出现,用户无从授权——这是 iOS 上 9010001 的高频原因。

微信小程序

"mp-weixin" : {
    "__usePrivacyCheck__" : true,
    "permission" : {
        "scope.userLocation" : { "desc" : "需要获取您的位置信息用于定位服务" }
    },
    "requiredBackgroundModes" : [ "location" ],
    "requiredPrivateInfos" : [
        "getLocation", "startLocationUpdate",
        "startLocationUpdateBackground", "onLocationChange"
    ]
}

requiredPrivateInfos 四个接口要在小程序后台逐个开通,漏一个对应功能直接不可用;后台连续定位还要开通 startLocationUpdateBackground,没开通时失败文案是「微信未开通后台定位接口」。

四、初始化和 AppKey 的两个坑

agreePrivacy({ agree: true })

initSdk({
  appKey: '你的 AppKey',
  success(res) { console.log(res.message) },   // "SDK已初始化"
  fail(err) { console.log(err.errCode, err.errMsg) }
})

坑一:AppKey 只从 initSdk 传。 不要在 AndroidManifest 里写 com.wayz.location.appkey——原生 SDK 会优先用 Manifest 里的值,直接忽略 setApiKey。网上老教程里这个写法流传很广,中招后初始化一切正常,定位永远失败,排查方向全错。

坑二:Key 填错,initSdk 依然返回成功。 错误不在初始化阶段暴露,而是拖到定位阶段才返回 9010002。所以“初始化成功”不能作为 Key 正确的依据,联调时第一次定位失败,先核对 Key,再查别的。

三端 Key 可以各不相同(Android 走 setApiKey,iOS 走 initKey,微信走 setAk),调用方式一样。

五、权限:三端三种问法

SDK 自己会检查权限并拉起系统弹窗,但各应用市场都要求在系统弹窗之前由应用自己说明用途。所以建议先自己判断、申请,再调定位接口。

Android:前后台必须分两次申请

这是 Android 上最容易翻车的点:把 ACCESS_BACKGROUND_LOCATION 和前台权限放在同一次申请里,系统会直接拒绝后台权限。正确写法是先要前台,拿到之后再单独要后台:

function requestAndroidPermissions(permissions) {
  return new Promise((resolve) => {
    plus.android.requestPermissions(permissions, (result) => {
      resolve({ granted: result.granted || [], deniedAlways: result.deniedAlways || [] })
    }, () => resolve({ granted: [], deniedAlways: permissions }))
  })
}

async function ensureAndroidLocation(needBackground) {
  // 第一步:前台权限
  const first = await requestAndroidPermissions([
    'android.permission.ACCESS_FINE_LOCATION',
    'android.permission.ACCESS_COARSE_LOCATION',
    'android.permission.READ_PHONE_STATE'
  ])
  const ok = first.granted.includes('android.permission.ACCESS_FINE_LOCATION')
          || first.granted.includes('android.permission.ACCESS_COARSE_LOCATION')
  if (!ok) {
    if (first.deniedAlways.length > 0) uni.openAppAuthorizeSetting()
    return false
  }
  if (!needBackground) return true

  // 第二步:Android 10+ 单独申请后台
  const Build = plus.android.importClass('android.os.Build')
  if (Build.VERSION.SDK_INT < 29) return true
  const second = await requestAndroidPermissions(['android.permission.ACCESS_BACKGROUND_LOCATION'])
  if (!second.granted.includes('android.permission.ACCESS_BACKGROUND_LOCATION')
      && second.deniedAlways.length > 0) {
    uni.openAppAuthorizeSetting()
  }
  return second.granted.includes('android.permission.ACCESS_BACKGROUND_LOCATION')
}

判断是否已授权用 uni.getAppAuthorizeSetting(),locationAuthorized 为 authorized 即可;config error 说明 manifest 里漏配了权限。

iOS:看状态值,不是看弹窗

uni.getAppAuthorizeSetting() 区分不了「使用期间」和「始终」,后台定位要读 CLLocationManager.authorizationStatus():

值含义后台连续定位
0尚未申请先 requestWhenInUseAuthorization,再 requestAlwaysAuthorization
2 / 1已拒绝 / 受限只能引导去设置页,系统不会再弹
3始终允许✅
4使用 App 期间允许❌ 返回 9010007
function requestIosLocation(needAlways) {
  const CLLocationManager = plus.ios.import('CLLocationManager')
  const status = CLLocationManager.authorizationStatus()
  if (status === 2 || status === 1) { uni.openAppAuthorizeSetting(); return }
  const manager = plus.ios.newObject('CLLocationManager')
  if (status === 0) plus.ios.invoke(manager, 'requestWhenInUseAuthorization')
  if (needAlways && status === 4) plus.ios.invoke(manager, 'requestAlwaysAuthorization')
  plus.ios.deleteObject(manager)
}

记住一条:iOS 只在状态为 0 时弹系统框。用户第一次拒绝了,之后代码里调多少次申请都没用,只能引导到「设置 → 隐私与安全性 → 定位服务」打开,顺便提醒开「精确位置」。

微信小程序:两个 scope

前台看 scope.userLocation,后台再看 scope.userLocationBackground。后者必须放在用户点击回调里调用 uni.authorize,放 onLoad 里调不会被受理。已拒绝时引导 uni.openSetting()。

六、单次定位与返回值

打卡场景用 getOnceLocation 拿一次就结束;对速度敏感的开屏定位用 getQuickLocation(Android 5 秒内返回)。

getOnceLocation({
  success(res) {
    console.log(res.longitude, res.latitude)
    console.log(res.address)        // "xx省xx市xx区xx路xx号"
    console.log(res.placeName)      // "xx大厦"
  },
  fail(err) { console.log(err.errCode, err.errMsg) },
  complete() {}
})

返回字段里值得注意的:

字段说明
address / province / city / district / street结构化地址,直接可用
placeName地点名称
confidence置信度,iOS 和微信端为 0
accuracy / speed / bearingiOS 端当前为 0
source定位来源,iOS 端为空字符串

一句话:跨端业务逻辑不要依赖 accuracy、confidence 这些字段,iOS 和微信拿到的恒为 0。要用精度做业务判断(比如“精度差于 500 米不算有效打卡”),只在 Android 上生效,写在三端共用的代码里迟早出事。

两个行为细节:再次发起定位会停掉上一次;微信端单次定位未返回时再调一次会被静默忽略,不进 fail——连续点击打卡按钮不会报错,但也不会有第二次回调,按钮要做防重。

七、连续定位

// 前台
startForegroundLocation({
  interval: 5000,
  success(res) { console.log(res.longitude, res.latitude, res.address) },
  fail(err) { console.log(err.errCode, err.errMsg) }
})

// 锁屏与后台继续回调
startBackgroundLocation({ interval: 5000, success(res) { /* ... */ }, fail(err) { /* ... */ } })

三端的后台要求不一样:

  • Android:允许锁屏与后台运行,Android 10+ 单独要后台权限(见第五节)

  • iOS:必须「始终」授权,状态 4 跑后台直接 9010007

  • 微信:走后台定位接口,实际回调间隔不小于 2000ms,设得再小也没用

interval 单位毫秒,默认 5000,传 0 或负数按默认处理。连续定位每次成功只调 success,不调 complete;页面卸载记得 stopLocation(),否则页面销毁后回调还在打。

八、自定义调试基座:9010002 的一半来自这里

标准基座只有 DCloud 自己的包名、证书和 SDK。wz-location 的原生库(Android 的 wayz-sdk-android-7.2.0.jar、iOS 的 wzLib.xcframework)只存在于自定义调试基座和正式包里。用标准基座跑 Android,定位必失败,错误码 9010002,文案会明确提示「未找到维智定位SDK,请制作自定义调试基座后运行」。

制作入口:HBuilderX「运行 → 运行到手机或模拟器 → 制作自定义调试基座」,Android、iOS 分开做;微信小程序不用基座。

做基座容易漏的几件事:

动作是否要重做基座
改 Vue 页面、改接口调用❌ 热更新直接进当前基座
换 SDK、改 AndroidManifest、改权限✅
改 iOS 用途描述、UIBackgroundModes、Bundle ID、证书✅
Apple 后台改了 App ID 能力✅ 且旧描述文件会失效,要先重新生成描述文件

iOS 侧准备三件套,Bundle ID 三处必须一致:Explicit App ID、带私钥的开发证书 .p12、iOS App Development 类型的 .mobileprovision。App ID 上勾 Background Modes → Location updates(不要勾 Location Push,那是定位推送扩展,这个插件用不到)。测试机要先登记 UDID,新增设备后必须编辑描述文件重新下载再打基座,只在 Devices 里保存是无效的。

另外,Mac 的 iOS 模拟器验证不了后台定位,「始终」授权和 9010007 都要在真机上确认。基座装好首次打开如果提示未受信任的开发者,去「设置 → 通用 → VPN 与设备管理」信任证书;iOS 16+ 还要打开开发者模式。

九、错误码排查表

errSubject 统一为 wz-location,七个错误码按排查优先级整理:

errCode含义先查什么
9010002定位失败① 是不是标准基座(文案会写「未找到维智定位SDK」)② AppKey 为空或填错 ③ 是不是写进了 AndroidManifest
9010001缺少定位权限用户拒绝了系统弹窗;iOS 检查用途描述有没有打进包
9010007缺少后台定位权限Android 后台权限被拒(是否和前台一起申请了);iOS 是不是「始终」授权;描述文件有没有 Location updates
9010005未同意隐私协议agreePrivacy({ agree: true }) 有没有调,或被撤销过
9010006尚未初始化initSdk 漏调,或没等成功就定位
9010004平台不支持跑到 H5、鸿蒙或其他小程序上了
9010003无法获取上下文Android 原生上下文不可用,基本只在异常环境出现

调试期建议打开日志:

setLogEnabled(true)
onSdkLog({ success(log) { console.log(log.level, log.tag, log.message) } })

Android 会把原生日志完整转发过来;微信端要「开关打开且已注册回调」才转发;iOS 的 onSdkLog 目前不向 JS 转发日志内容,iOS 排查别指望这个回调,直接看 Xcode 控制台。

十、一个能跑的打卡页

把上面串起来,Vue3 组合式写法的最小打卡页:

<template>
  <view class="page">
    <button :disabled="loading" @click="onCheckin">{{ loading ? '定位中…' : '打卡' }}</button>
    <view v-if="result" class="result">
      <text>{{ result.address }}</text>
      <text>{{ result.time }}</text>
    </view>
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { agreePrivacy, initSdk, getOnceLocation, stopLocation } from '@/uni_modules/wz-location'

const loading = ref(false)
const result = ref(null)
let ready = false

async function setup() {
  await new Promise((resolve, reject) => {
    agreePrivacy({ agree: true, success: resolve, fail: reject })
  })
  await new Promise((resolve, reject) => {
    initSdk({ appKey: '你的 AppKey', success: resolve, fail: reject })
  })
  ready = true
}

async function onCheckin() {
  if (!ready) await setup()
  if (loading.value) return          // 防重:微信端重复调用会被静默忽略
  loading.value = true

  // #ifdef APP-PLUS
  // 前后台权限判断与申请,见第五节 ensureAndroidLocation / requestIosLocation
  // #endif
  // #ifdef MP-WEIXIN
  // uni.authorize('scope.userLocation'),见第五节
  // #endif

  getOnceLocation({
    success(res) {
      result.value = { address: res.address, time: res.time }
      // 上报后端:经纬度 + 结构化地址 + 业务单据号
      uni.request({
        url: 'https://your.api/checkin',
        method: 'POST',
        data: {
          longitude: res.longitude,
          latitude: res.latitude,
          address: res.address,
          placeName: res.placeName
        }
      })
    },
    fail(err) {
      uni.showToast({ title: `定位失败 ${err.errCode}`, icon: 'none' })
    },
    complete() { loading.value = false }
  })
}

// 页面卸载兜底
import { onUnload } from '@dcloudio/uni-app'
onUnload(() => stopLocation())
</script>

注意打卡成功判据不要只看拿到坐标——address 和 placeName 才是打卡记录的核心,坐标只是辅助。这也正是用这个插件而不是裸 uni.getLocation 的原因:后者只给坐标,地址要自己再调一次逆地理。

写在最后

三端接入的复杂度不在定位本身,在各自的授权链路和打包链路:Android 的后台权限要单独申请、iOS 的授权状态只能看不能弹、微信的 requiredPrivateInfos 要逐个开通。把第二节的调用顺序和第九节的错误码表存下来,接入过程中九成的问题都能对号入座。


文中错误码、字段与平台行为均以插件集成文档为准;iOS 端部分字段(accuracy、confidence 等)当前为 0 是已知平台差异,后续版本如有更新以文档为准。