一、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\"/>"
]
}
}
}
三个要点:
-
ACCESS_BACKGROUND_LOCATION只在 Android 10 且targetSdkVersion >= 29时才真正生效,配低了后台定位申请不出来。 -
READ_PHONE_STATE用于辅助定位,隐私政策里要一并说明,应用市场审核会看。 -
后台定位服务由插件自己声明(
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 / bearing | iOS 端当前为 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 要逐个开通。把第二节的调用顺序和第九节的错误码表存下来,接入过程中九成的问题都能对号入座。
-
插件地址:维智定位 - DCloud 插件市场
-
更多能力(围栏、轨迹、位置验真)见 维智开放平台
文中错误码、字段与平台行为均以插件集成文档为准;iOS 端部分字段(accuracy、confidence 等)当前为 0 是已知平台差异,后续版本如有更新以文档为准。