
小程序定位能否生效,取决于三层前置条件是否同时满足:接口权限已在管理后台开通、app.json 已声明所用定位接口、用户当场授予位置权限并已完成隐私保护指引配置。三层中任意一层缺失,wx.getLocation 都会直接返回 fail,且错误信息通常较笼统。本文按「前置条件 → 配置文件 → 坐标系 → 参数与返回 → 精度与频率 → 失败反查 → 降级方案」的顺序说明,所有字段与阈值均以微信开放文档当前口径为准,可逐项对照核验。
一、定位能力生效的三层前置条件
定位不是一个可以单独调用的接口,而是一组层层约束的权限体系。排查时先确认三层是否全部通过,再进入代码逻辑,否则容易在业务代码里反复调整却始终拿不到坐标。
| 层级 | 核验位置 | 具体要求 | 未满足时的表现 |
|---|---|---|---|
| 接口权限 | 小程序管理后台「开发—开发管理—接口设置」 | 类目审核通过后,自助开通「获取当前的地理位置、速度」接口权限 | 代码提审环节被拦截,或在真机调用时报无权限 |
| 代码声明 | app.json 的 requiredPrivateInfos | 如实列出 getLocation、openLocation 等所用定位接口 | 提交审核提示「未配置隐私接口 getLocation」,调用直接 fail |
| 用户授权 | 运行时弹窗与《小程序用户隐私保护指引》 | 用户当场允许 scope.userLocation,隐私指引中声明收集目的与范围 | errMsg 返回 auth deny,或系统层拒绝 |
补充说明:自 2022 年 7 月 14 日后发布的小程序,若使用 wx.getLocation,必须在 app.json 中声明,否则该接口无法正常使用;此前发布的小程序不受该时间点影响。接口权限的申请入口于 2022 年 3 月 31 日全量上线,并自 4 月 18 日起在代码审核环节检测是否已开通,未开通将在提审环节被拦截。
二、app.json 配置项逐项说明
配置文件中涉及位置能力的有两处:permission 用于定义授权弹窗展示给用户的用途文案,requiredPrivateInfos 用于声明实际调用的隐私接口。二者作用不同,不能互相替代。
| 配置项 | 路径 | 字段含义 | 填写要点 |
|---|---|---|---|
| 授权用途文案 | permission.scope.userLocation.desc | 首次授权弹窗中展示给用户的说明文字 | 写明具体用途与影响范围,避免笼统表述 |
| 定位接口声明 | requiredPrivateInfos 数组 | 列出代码用到的地理位置相关接口名 | 用哪个写哪个,漏写会导致调用直接失败 |
| 打开地图接口 | requiredPrivateInfos 中的 openLocation | 用于唤起内置地图查看位置 | 若同时有打开地图能力,需一并声明 |
| 持续定位接口 | requiredPrivateInfos 中的 onLocationChange | 用于高频率持续获取位置 | 仅在确有持续定位场景时声明 |
| 模糊定位接口 | requiredPrivateInfos 中的 getFuzzyLocation | 用于获取省市区级模糊位置 | 精度要求低时可改用它,开通门槛较低 |
配置完成后需重新提交审核,配置本身不会在已发布版本上即时生效。
三、坐标系:wgs84 与 gcj02 的选择
wx.getLocation 的 type 参数决定返回坐标系,默认值为 wgs84。地图相关使用的坐标格式应为 gcj02。若把 wgs84 坐标直接交给国内地图组件或逆地址解析服务,标记点会出现几十米到数百米的偏移,这类「定位不准」并非接口故障,而是坐标系未转换。

| 参数值 | 坐标含义 | 适用场景 | 注意事项 |
|---|---|---|---|
| wgs84 | GPS 原始坐标 | 需要原始卫星坐标、对接部分海外服务 | 默认值;直接用于国内地图会偏移 |
| gcj02 | 可用于 wx.openLocation 的坐标 | 国内地图展示、打开位置、国内图商逆地址解析 | 官方文档明确地图相关应使用 gcj02 |
使用第三方服务做逆地址解析时,应先确认该服务默认采用的坐标系,再决定是否转换。开发者工具中的定位模拟使用 IP 定位,存在一定误差,且目前仅支持 gcj02 坐标,因此工具内的偏差不能作为真机结论。
四、wx.getLocation 参数与返回字段
确认权限与坐标系之后,按接口定义逐项核对入参与返回字段。下表字段与最低版本均取自官方接口文档,可作为代码评审的对照表。
| 入参 | 类型 | 默认值 | 说明 | 最低版本 |
|---|---|---|---|---|
| type | string | wgs84 | wgs84 返回 GPS 坐标;gcj02 返回可用于 wx.openLocation 的坐标 | — |
| altitude | boolean | false | 传 true 返回高度信息,因需较高精确度会减慢返回速度 | 1.6.0 |
| isHighAccuracy | boolean | false | 开启高精度定位,接口耗时会增加 | 2.9.0 |
| highAccuracyExpireTime | number | 无 | 高精度定位超时时间(ms),需大于 3000ms 才有效果 | 2.9.0 |
| success / fail / complete | function | 无 | 成功、失败、结束回调,complete 在成功与失败时都会执行 | — |
| 返回字段 | 类型 | 含义与取值范围 | 最低版本 |
|---|---|---|---|
| latitude | number | 纬度,范围 -90~90,负数表示南纬 | — |
| longitude | number | 经度,范围 -180~180,负数表示西经 | — |
| speed | number | 速度,单位 m/s | — |
| accuracy | number | 位置精确度,数值越小越精确,10 表示与真实位置约相差 10m | — |
| altitude | number | 高度,单位 m | 1.2.0 |
| verticalAccuracy | number | 垂直精度,单位 m,Android 无法获取时返回 0 | 1.2.0 |
| horizontalAccuracy | number | 水平精度,单位 m | 1.2.0 |
返回体上方的 accuracy 与 horizontalAccuracy 是判断结果是否可用的直接依据。当业务对位置精度有明确要求时,应在 success 回调中读取精度字段并设定阈值,而非只取经纬度后立即使用。
五、精度与频率约束
高频率调用会导致耗电,基础库 2.17.0 起 wx.getLocation 增加了调用频率限制。若业务需要持续位置变化,应使用持续定位接口 wx.onLocationChange,而不是循环调用单次定位。开启高精度定位时接口耗时增加,可用 highAccuracyExpireTime 指定超时时间;该值需设置在 3000ms 以上才会生效。altitude 参数虽可返回高度,但因需要较高精确度会拖慢整体返回速度,非必要场景保持默认关闭。
六、授权失败与定位不准的反查路径
定位失败时按「后台权限 → 代码声明 → 系统开关 → 用户授权 → 坐标与精度」的顺序逐层反查。下列 errMsg 为常见返回形态,可与日志中的实际值对照。排查时应先在真机上确认失败发生在哪一层,再针对性处理,避免在业务代码中反复重试同一失败调用。

| 现象或返回 | 常见原因 | 核验动作 |
|---|---|---|
| auth deny / auth denied | 用户拒绝位置授权 | 引导用户在小程序设置页重新开启;用途文案是否具体会影响授权率 |
| system permission denied | 手机系统定位总开关关闭,或微信无定位权限 | 检查系统设置中的定位开关与微信的定位权限 |
| 提示「未配置隐私接口 getLocation」 | app.json 或 ext.json 未声明 requiredPrivateInfos | 补齐声明并确认接口权限已开通后重新提交审核 |
| 提审被拦截,提示接口无权限 | 后台未开通该接口,或类目不符合开放范围 | 在接口设置中自助开通;核对主体类目是否在开放清单内 |
| 已授权但坐标偏移 | 坐标系选择错误或逆地址解析服务坐标系不一致 | 地图场景改用 gcj02,并核对第三方服务的默认坐标系 |
| 开发者工具定位偏差 | 工具使用 IP 定位,且仅支持 gcj02 | 以真机调试或预览结果为准 |
| 调用频繁被限制 | 基础库 2.17.0 起的频率限制 | 减少单次调用频次,改用 wx.onLocationChange 持续定位 |
当用户此前拒绝过授权,后续调用不会再次弹窗。此时应通过 wx.getSetting 判断授权状态,并在用户主动触发的操作中引导其进入 wx.openSetting 重新开启,而不是反复直接调用定位接口。
七、模糊定位作为降级方案

对精度要求不高、只需判断省市区或附近的场景,可评估使用模糊定位接口 wx.getFuzzyLocation。该接口走独立授权 scope.userFuzzyLocation,返回 Municipality 等行政区划信息,开通门槛低于精确定位,审核路径也相对简短。同城展示、附近网点、天气查询等场景通常无需申请精确定位权限。
| 对比维度 | wx.getLocation | wx.getFuzzyLocation |
|---|---|---|
| 返回内容 | 经纬度、速度、精度等 | 省、市、区等模糊位置信息 |
| 授权 scope | scope.userLocation | scope.userFuzzyLocation |
| 精度 | 米级,受 accuracy 字段约束 | 行政区划级 |
| 基础库要求 | 基础能力长期支持 | 需较新基础库版本 |
| 适用判断 | 导航、路线规划、到店核验 | 同城展示、附近网点、天气类场景 |
八、上线前自检清单
- 管理后台已开通「获取当前的地理位置、速度」接口权限,且主体类目在开放范围内。
- app.json 的 requiredPrivateInfos 已列出 getLocation 及实际使用的其他定位接口。
- permission.scope.userLocation.desc 已填写具体、可核验的用途说明。
- 《小程序用户隐私保护指引》已声明收集地理位置的目的、方式与范围。
- 地图展示与 wx.openLocation 场景统一使用 gcj02 坐标系。
- success 回调读取 accuracy 与 horizontalAccuracy,并设定业务精度阈值。
- 用户拒绝授权后,通过 getSetting 判断状态并在用户操作中引导 openSetting。
- 真机验证了系统定位关闭、用户拒绝、接口未开通三类失败路径的提示与降级。
九、常见问题
小程序定位怎么开启?
先在管理后台开通定位接口权限,再在 app.json 中声明 requiredPrivateInfos 与授权用途文案,运行至定位调用点时由用户当场授权,三步全部通过后才可获取坐标。
小程序定位权限在哪开?
用户侧在小程序右上角设置页或系统设置中开启;开发者侧在小程序管理后台「开发—开发管理—接口设置」中开通接口权限,两处含义不同。
小程序定位失败怎么办?
按后台权限、代码声明、系统开关、用户授权、坐标系五步反查。先看返回 errMsg,再对应到具体层级,避免在业务代码中盲目重试。
小程序定位授权失败怎么回事?
常见于用户拒绝授权、系统定位未开启,或 app.json 漏声明隐私接口。若此前已拒绝,后续调用不会再次弹窗,需要引导用户到设置页重新开启。
小程序获取位置失败怎么弄?
确认 wx.getLocation 的 fail 回调已实现,记录 errMsg 原文;再核对基础库版本是否支持所用参数,以及是否触发了 2.17.0 起的频率限制。
小程序坐标系怎么设置?
通过 wx.getLocation 的 type 参数设置,wgs84 为默认值,地图相关场景应设为 gcj02。接入第三方逆地址解析时还需确认对方服务的默认坐标系。
小程序坐标系是什么意思?
坐标系决定同一地理位置用哪组经纬度数值表示。不同坐标系之间若不转换,同一地点会在地图上产生固定偏移,并非定位本身失准。
小程序wx.getlocation获取经纬度不准确怎么办?
先确认使用 gcj02,再读取 accuracy 与 horizontalAccuracy 判断精度是否满足业务;必要时开启 isHighAccuracy 并设置 3000ms 以上的 highAccuracyExpireTime。开发者工具的 IP 定位误差不作为判断依据。
十、核验路径小结
定位问题的结论应以可复现的核验路径为准:查后台接口权限是否开通,查 app.json 声明是否齐全,查系统与服务层定位开关,查用户授权状态,查坐标系与精度字段,最后用真机验证失败分支。以上步骤对应的官方文档条目与管理后台位置均保持不变,可按本文表格逐项对照,形成固定的上线前核对流程。
配图说明:本文部分配图使用人工智能生成合成技术制作。





