wx.getLocation 接口未配置地理位置权限或未在 manifest.json 中声明 requiredPrivateInfos

Question

在微信小程序中调用 `wx.getLocation` 时频繁报错“fail: permission denied”或“getLocation:fail system permission denied”，常因未正确配置地理位置权限导致。核心原因有二：一是未在 `manifest.json`（或新版 `app.json` 的 `requiredPrivateInfos` 字段）中声明 `"location"`；二是未在微信开发者工具或真机上手动开启“位置信息”授权（尤其 iOS 或 Android 12+ 系统）。注意：自微信基础库 2.28.0 起，`requiredPrivateInfos` 为强制声明项，缺失将直接拦截 API 调用且无降级提示；同时需配合 `wx.authorize({scope: 'scope.userLocation'})` 提前申请，而非仅依赖 `wx.getLocation` 的自动弹窗。遗漏任一环节均会导致定位失败，且控制台错误信息模糊，易误判为代码逻辑问题。

Answer 1

```html

一、现象层：错误表征与典型日志特征

开发者在真机调试或灰度发布后频繁捕获到如下两类错误：

• fail: permission denied（基础库 < 2.28.0 时常见）
• getLocation:fail system permission denied（基础库 ≥ 2.28.0 后高频出现，且无进一步上下文）

值得注意的是：控制台不输出调用栈，console.error 仅显示字符串，try/catch 捕获后 err 对象为空对象或仅有 { errMsg: "..." }，极易误判为网络异常或 JS 运行时错误。

二、配置层：双轨制权限声明机制（manifest.json + app.json）

自微信小程序生态演进，地理位置权限需双重显式声明：

配置文件	字段路径	值类型	说明
manifest.json	"permissions": { "scope.userLocation": {"desc": "用于获取当前位置"} }	Object	旧版 H5 兼容层必需；Android/iOS 安装包级权限申请依据
app.json	"requiredPrivateInfos": ["location"]	Array<string>	微信基础库 2.28.0+ 强制项；缺失则 wx.getLocation 被底层拦截，连弹窗都不触发

三、运行时层：授权流程不可绕过的三阶段模型

现代微信定位已摒弃“调用即弹窗”模式，必须遵循标准 OAuth-like 授权流：

1. 预检：调用 wx.getSetting({ withSubNVue: false }) 查询 authSetting['scope.userLocation']
2. 主动申请：若为 undefined 或 false，必须显式执行 wx.authorize({ scope: 'scope.userLocation' })
3. 最终调用：仅当 authSetting['scope.userLocation'] === true 时，方可安全调用 wx.getLocation

四、系统层：iOS/Android 特异性行为深度解析

不同平台对“位置权限”的管控逻辑存在本质差异：

• iOS：即使小程序内授权成功，若用户在「系统设置 → 微信 → 位置信息」中设为“永不允许”，wx.authorize 仍返回 success，但后续 wx.getLocation 必然失败 —— 此为 Apple 的隐私沙箱设计，需引导用户手动修正系统级设置。
• Android 12+：引入 Approximate Location 模式，默认只授予模糊位置（1km 精度），而 wx.getLocation({ type: 'wgs84' }) 要求精确坐标，此时需额外申请 ACCESS_FINE_LOCATION 权限（通过 android.permission.ACCESS_FINE_LOCATION 在 AndroidManifest.xml 中声明）。

五、诊断层：一套可复用的全链路排查清单

建议按以下顺序逐项验证（任一环节失败即终止）：

1. 检查基础库版本：console.log(wx.getSystemInfoSync().SDKVersion) ≥ 2.28.0？
2. 确认 app.json 存在 "requiredPrivateInfos": ["location"]
3. 确认 manifest.json 中 permissions 已完整配置
4. 在开发者工具「详情 → 项目设置」中勾选「地理位置」模拟开关
5. 真机测试前，先在微信「我 → 设置 → 隐私 → 定位服务」中开启微信定位权限
6. 调用前插入诊断代码：const res = await wx.getSetting(); console.log('authSetting:', res.authSetting);

六、代码层：生产环境推荐实现模板（含降级兜底）

async function safeGetLocation() {
  try {
    const setting = await wx.getSetting();
    if (!setting.authSetting['scope.userLocation']) {
      const auth = await wx.authorize({ scope: 'scope.userLocation' });
      if (auth.errMsg !== 'authorize:ok') throw new Error('授权被拒绝');
    }
    return await wx.getLocation({ type: 'wgs84', altitude: true });
  } catch (err) {
    if (err.errMsg?.includes('permission denied')) {
      wx.showModal({
        title: '位置服务未开启',
        content: '请前往微信设置中开启定位权限，或在手机系统设置中为微信授予精确定位',
        showCancel: true,
        confirmText: '去设置',
        success: (res) => {
          if (res.confirm) wx.openSetting(); // 引导至设置页
        }
      });
    }
    throw err;
  }
}

七、演进层：微信隐私合规演进路线图（2023–2025）

根据微信官方《小程序隐私保护指引》v3.2 及工信部《App 用户权益保护测评规范》，未来将强化：

• 最小必要原则：要求 requiredPrivateInfos 中每个字段必须对应实际业务场景，审核时需提供用途说明
• 动态权限回收：用户可在小程序内随时撤回授权（wx.openSetting 中新增「撤回权限」入口）
• 离线定位能力增强：2024Q3 起试点 wx.startLocationUpdateBackground 支持后台持续定位（需单独声明 "backgroundFetch"）

八、可视化：wx.getLocation 权限决策流程图

graph TD A[调用 wx.getLocation] --> B{基础库 ≥ 2.28.0?} B -->|否| C[触发系统弹窗] B -->|是| D[检查 requiredPrivateInfos] D -->|缺失| E[直接 fail: permission denied
无任何提示] D -->|存在| F[检查 getSetting.authSetting] F -->|undefined/false| G[wxAutorize 弹窗] F -->|true| H[执行定位] G -->|用户拒绝| I[fail: system permission denied] G -->|用户同意| F H --> J[成功返回坐标]

```