企业官网建设流程全解析

1. 项目概述：一个“简单”的权限声明报错

最近在调试一个微信小程序的地图功能时，遇到了一个典型的报错：getLocation:fail the api need to be declared in the requiredPrivateInfos field in app.json。这个错误对于刚接触小程序隐私接口规范或者从旧版本迁移过来的开发者来说，可能有点懵。表面上看，它只是告诉你需要在app.json里加个配置，但背后涉及的是微信小程序平台对用户隐私保护策略的一次重要升级。如果你还在用一两年前的开发思路，这个错误几乎是必踩的坑。

简单来说，这个错误意味着你调用了需要获取用户敏感信息的接口（比如wx.getLocation获取地理位置），但没有在项目全局配置文件app.json中显式声明你需要这些权限。这不再是简单的“用户点击授权弹窗”就能解决的事情，而是要求开发者在代码层面就提前“报备”，符合平台对隐私合规的强制要求。无论是新手还是老手，理解并处理好这个配置，是让涉及地理位置、通讯录、相册等功能的微信小程序顺利上线的第一步。接下来，我会结合实操，把这个问题从里到外拆解清楚。

2. 错误根源与平台政策演变深度解析

2.1 从“运行时授权”到“声明式授权”的转变

要理解这个错误，不能只看代码，得先了解微信小程序平台的规则变化。在早期的微信小程序开发中，调用诸如wx.getLocation、wx.chooseAddress等接口，流程相对直接：在需要的时候调用 API，系统会弹出授权弹窗，用户点击“允许”或“拒绝”，开发者根据回调结果进行后续操作。这种模式可以称为“运行时授权”。

然而，随着数据安全和隐私保护成为全球焦点，各大平台都收紧了管控。微信小程序平台也随之升级了隐私接口的调用规范。核心变化在于，引入了“声明式授权”机制。这意味着，开发者必须在代码编译和提交审核阶段，就明确告知平台：“我的小程序可能会用到以下敏感接口”。这个声明的场所，就是项目根目录下的app.json文件中的requiredPrivateInfos字段。

这个设计有几个深层目的：

1. 提升透明度：让用户和平台在打开小程序前，就能大致了解其可能收集的信息类型，符合“知情同意”原则。
2. 规范开发行为：倒逼开发者在设计功能时就考虑隐私问题，避免滥用或暗中调用敏感接口。
3. 审核前置：微信审核团队可以根据你的声明，更有效地评估小程序的合规性。如果你声明了用位置，但实际功能是个计算器，审核就可能无法通过。

所以，getLocation:fail the api need to be declared in the requiredPrivateInfos field in app.json这个报错，本质是微信小程序基础库在检测到你调用getLocation时，发现你并没有在“白名单”（即requiredPrivateInfos）里登记，于是直接阻止了接口调用，连授权弹窗都不会给你弹出来。这是比用户拒绝授权更前置的一道关卡。

2.2requiredPrivateInfos字段详解与配置语法

requiredPrivateInfos是app.json中useExtendedLib同级的一个配置项，其值是一个字符串数组。数组中的每个字符串，对应一个需要声明的隐私接口的标识。

对于地理位置接口，你需要声明的标识是"getLocation"。注意，这里声明的是接口的“行为”或“权限类型”，而不是某个具体的 API 函数名，尽管它们名字相同。这意味着，只要你声明了"getLocation"，那么wx.getLocation这个 API 就获得了被调用的“资格”。

一个最基本的配置示例如下：

{ "pages": [ "pages/index/index", "pages/logs/logs" ], "window": { "backgroundTextStyle": "light", "navigationBarBackgroundColor": "#fff", "navigationBarTitleText": "Weixin", "navigationBarTextStyle": "black" }, "requiredPrivateInfos": [ "getLocation" ] }

重要注意事项：

• 数组格式：即使只声明一个接口，也必须用方括号[]包起来。
• 字符串值：数组内的每一项必须是双引号包裹的字符串，例如"getLocation"，直接写getLocation会导致配置解析错误。
• 位置：requiredPrivateInfos应该放在app.json的顶层，与pages、window等配置项平级。
• 大小写敏感：必须严格按照文档提供的字符串填写，"getlocation"或"GetLocation"都是无效的。

除了getLocation，常见的还有其他隐私接口需要声明，例如：

• "chooseAddress"：获取用户收货地址
• "chooseInvoiceTitle"：获取发票抬头
• "getWeRunData"：获取微信运动数据
• "chooseLicensePlate"：选择车牌号（适用于停车等服务）

每次新增需要这类隐私接口的功能时，都应该先来更新这个数组。

3. 完整解决流程与实操步骤

3.1 第一步：定位与确认问题

当你看到getLocation:fail the api need to be declared in the requiredPrivateInfos field in app.json这个错误时，首先需要确认两件事：

1. 错误发生的上下文：是在模拟器、真机调试，还是体验版/正式版？通常开发阶段在模拟器和真机调试时就会遇到。
2. 调用接口的代码位置：找到你项目中调用wx.getLocation的页面或组件。可能是某个按钮的点击事件，或者页面的onLoad生命周期函数中。

打开开发者工具，查看控制台（Console）的错误信息，通常它会明确指出是哪个页面的哪行代码触发了这个错误。记下这个位置。

3.2 第二步：修改app.json配置文件

1. 在微信开发者工具中，找到项目根目录下的app.json文件并打开。
2. 检查是否已存在requiredPrivateInfos字段。
   • 如果不存在：在文件中找一个合适的位置（例如在window配置项之后），添加该字段。格式参考上一节的示例。
   • 如果已存在：检查其值是否为数组，并确认数组中是否包含字符串"getLocation"。如果没有，将其添加进去。
3. 保存文件。微信开发者工具通常会监听文件变化并自动编译。

注意：修改app.json后，有时需要关闭当前小程序项目，重新打开，或者清除开发者工具缓存并重新编译，以确保新的配置完全生效。这是一个常见的坑点，如果修改后报错依旧，首先尝试这个操作。

3.3 第三步：检查基础库版本

requiredPrivateInfos机制是在特定基础库版本之后才强制要求的。虽然现在新创建的项目默认基础库版本都比较高，但如果你维护的是一个老项目，可能需要检查。

1. 在微信开发者工具中，点击右上角“详情”按钮。
2. 在“本地设置”选项卡中，查看“调试基础库”版本。
3. 确保你选择的基础库版本不低于 2.21.2（这是该机制开始逐步推广的版本）。建议始终使用官方推荐的较新版本或最新版本进行开发和测试。

如果项目用户使用的微信客户端版本过低，可能不支持此机制，但微信会做兼容处理。不过作为开发者，我们必须以符合新规的方式开发。

3.4 第四步：编写健壮的接口调用代码

配置好app.json只是拿到了“入场券”。实际的接口调用还需要处理用户授权状态。一个健壮的getLocation调用代码应该如下所示：

// 在页面的 .js 文件中 Page({ onLoad: function() { // 可以在合适的时机调用，例如按钮事件中 }, getLocationHandler: function() { const that = this; // 1. 首先检查用户是否已经授权过地理位置权限 wx.getSetting({ success(res) { // authSetting['scope.userLocation'] 表示地理位置权限 if (!res.authSetting['scope.userLocation']) { // 2. 未授权，则发起授权请求 wx.authorize({ scope: 'scope.userLocation', success() { // 用户同意授权，调用 getLocation that._getActualLocation(); }, fail(err) { // 用户拒绝授权，给出友好提示 console.error('授权失败:', err); wx.showModal({ title: '提示', content: '需要您授权地理位置信息以提供相关服务，您可以在小程序设置中重新打开授权。', showCancel: false }); } }); } else { // 3. 已授权，直接调用 getLocation that._getActualLocation(); } }, fail(err) { console.error('获取设置失败:', err); } }); }, _getActualLocation: function() { wx.getLocation({ type: 'wgs84', // 返回GPS坐标，'gcj02'返回国测局坐标 success(res) { const latitude = res.latitude; const longitude = res.longitude; const speed = res.speed; const accuracy = res.accuracy; console.log('位置获取成功:', latitude, longitude); // 这里可以将坐标用于地图显示、计算距离等 // 例如：跳转到地图页面或将坐标设置到 data 中 // that.setData({ latitude, longitude }); }, fail(err) { console.error('获取位置失败:', err); // 失败原因可能是用户拒绝、手机定位未打开、网络问题等 wx.showToast({ title: '定位失败', icon: 'none' }); } }); } })

这段代码的逻辑是：

• 先查授权状态：使用wx.getSetting检查用户是否已授权过。
• 未授权则请求授权：使用wx.authorize弹出官方授权窗口。
• 授权后或已授权则获取位置：调用wx.getLocation获取具体坐标。
• 处理各种失败情况：包括用户拒绝授权、系统定位服务关闭等。

3.5 第五步：处理用户拒绝或关闭授权后的引导

用户可能首次拒绝授权，或者后期在手机系统设置或小程序设置中关闭了权限。你的代码需要处理这种场景，并引导用户重新打开授权。

一种常见的做法是，在wx.authorize失败或wx.getLocation因权限问题失败时，提示用户去“设置”页面手动开启。但请注意，微信小程序不允许直接以编程方式跳转到系统设置页。我们可以引导用户前往小程序自身的设置页：

// 在授权失败或获取位置因权限失败时的回调中 wx.showModal({ title: '需要位置权限', content: '请在接下来的界面中打开位置信息授权。', confirmText: '去设置', success(res) { if (res.confirm) { // 引导用户打开小程序设置页 wx.openSetting({ success(settingRes) { // 用户从设置页返回，可以再次检查授权状态 console.log('用户从设置页返回', settingRes.authSetting); if (settingRes.authSetting['scope.userLocation']) { // 用户已打开授权，可以重新获取位置 that._getActualLocation(); } } }); } } });

注意：频繁引导用户去设置可能会引起反感，请根据实际功能必要性合理设计引导逻辑。

4. 进阶：隐私协议与getLocation的关联

在排查网络资料时，你可能还看到了另一个相关报错：getlocation:fail api scope is not declared in the privacy agreement。这个错误是另一个维度的要求，它与《微信小程序隐私保护指引》有关。

从2023年下半年开始，微信要求所有涉及收集用户个人信息的小程序，必须配置并展示隐私协议。开发者需要在微信小程序管理后台的【设置】->【服务内容声明】->【用户隐私保护指引】中，详细填写收集和使用的信息类型、目的等。

requiredPrivateInfos和隐私协议的关系：

• requiredPrivateInfos：是开发侧的代码声明，告诉微信基础库“我要用这些接口”。
• 隐私协议：是运营侧的合规文档，告诉用户“我为什么要用、怎么用你的信息”。

两者必须匹配。如果你在app.json中声明了"getLocation"，但在管理后台的隐私保护指引中没有声明收集“位置信息”，那么在某些版本的基础库或特定条件下，即使requiredPrivateInfos配置正确，调用接口时仍可能失败，并提示与隐私协议相关的错误。

实操心得：

1. 开发测试阶段，requiredPrivateInfos是必须配置的，否则代码层面直接报错。
2. 准备提审上线前，务必登录小程序管理后台，完善用户隐私保护指引，确保其中包含了你所声明的所有隐私信息类型（如位置、地址等）。
3. 在代码中，在首次调用隐私接口前，使用wx.requirePrivacyAuthorize接口来异步等待用户同意隐私协议，这已成为新的最佳实践。流程变为：同意隐私协议 -> 检查具体权限授权 -> 调用接口。

一个整合了隐私协议检查的更完整调用逻辑伪代码如下：

// 假设已引入隐私协议相关逻辑 Page({ onLoad() { // 检查并处理隐私协议 this.checkPrivacyAndAuth(); }, async checkPrivacyAndAuth() { // 1. 处理隐私协议（如果需要） if (需要显示隐私协议) { try { await wx.requirePrivacyAuthorize(); // 等待用户同意隐私协议 } catch (e) { console.log('用户未同意隐私协议'); return; } } // 2. 处理具体的地理位置授权（即之前的 getSetting/authorize 逻辑） this.checkAndRequestLocationAuth(); }, // ... 后续的 checkAndRequestLocationAuth 和 _getActualLocation 方法同上 })

5. 常见问题排查与避坑指南

即使按照上述步骤操作，你可能还是会遇到一些问题。下面是一些常见场景和解决方案：

5.1 问题一：配置已修改，但报错依旧

• 可能原因1：缓存未更新。微信开发者工具或手机微信客户端存在缓存。
  • 解决方案：在开发者工具中，点击工具栏的【清缓存】->【全部清除】，然后重新编译。在真机上，删除小程序，重新扫码进入。
• 可能原因2：app.json格式错误。例如缺少逗号、括号不匹配、字符串引号错误等，导致整个配置文件解析失败。
  • 解决方案：仔细检查app.json的 JSON 格式。可以使用在线的 JSON 校验工具，或者开发者工具本身也会有语法错误提示（文件标签页上会有红点）。
• 可能原因3：代码中接口名拼写错误。虽然报错指向配置，但有时可能是调用 API 的代码有误。
  • 解决方案：检查调用wx.getLocation的代码，确保函数名拼写正确。

5.2 问题二：在真机调试正常，但上传体验版或审核后报错

• 可能原因1：体验版/正式版使用的基础库版本与开发版不同。
  • 解决方案：在小程序管理后台，可以设置“最低基础库版本”。确保你设置的基础库版本支持requiredPrivateInfos机制（>=2.21.2）。同时，提醒体验用户将微信更新到最新版本。
• 可能原因2：隐私协议未配置或配置不完整。
  • 解决方案：登录小程序管理后台，检查【用户隐私保护指引】是否已填写并发布，且内容涵盖了“位置信息”等你声明的权限。

5.3 问题三：用户授权了，但getLocation返回失败

• 可能原因1：手机系统定位服务（GPS）未开启。
  • 解决方案：提示用户打开手机的“位置信息”或“定位服务”。可以通过wx.getSystemSetting或wx.openSetting引导，但无法直接跳转系统设置，只能文字提示。
• 可能原因2：网络问题或超时。
  • 解决方案：wx.getLocation可以设置timeout参数（单位 ms，默认 30秒）。在室内或信号差的地方，可以适当延长超时时间，并做好加载状态提示和失败重试机制。
• 可能原因3：类型（type）不匹配。
  • 解决方案：wx.getLocation的type参数默认为'wgs84'（国际标准 GPS 坐标）。如果你使用的第三方地图 SDK（如腾讯地图、百度地图）需要特定的坐标系（如'gcj02'国测局坐标），请确保传入正确的type。传错会导致坐标偏移巨大。

5.4 问题四：如何兼容旧版本微信

对于requiredPrivateInfos这种较新的特性，需要考虑使用旧版本微信的用户。好消息是，微信基础库通常有良好的向后兼容性。

• 策略：你的代码逻辑（检查授权 -> 请求授权 -> 调用接口）是通用的。requiredPrivateInfos配置在低版本基础库中会被忽略，但接口调用本身仍需要用户授权。因此，配置了它不会导致低版本出错，只是在高版本中多了强制声明这一步。
• 注意：低版本用户不会遇到requiredPrivateInfos报错，但如果你的代码逻辑依赖高版本 API（如wx.requirePrivacyAuthorize），则需要做兼容判断，可以使用wx.canIUse或判断基础库版本wx.getSystemInfoSync().SDKVersion。

5.5 一个完整的避坑检查清单

在发布涉及getLocation功能的小程序前，建议按此清单自查：

6. 扩展：其他相关隐私接口配置

getLocation只是众多需要声明的隐私接口之一。随着小程序功能复杂化，你可能会用到更多。下表列举了部分常见接口及其在requiredPrivateInfos中对应的声明值：

重要原则：按需声明，最小化声明。只声明你小程序确实需要使用的接口。过度声明不仅会增加用户的隐私顾虑，也可能在小程序审核时带来不必要的麻烦，审核员会质疑你为何声明了未使用的敏感权限。

7. 实战案例：为一个“周边商家查找”小程序配置定位

假设我们正在开发一个“周边美食搜索”小程序，核心功能是获取用户位置，显示附近的餐厅。

1. 规划：我们需要wx.getLocation获取坐标，然后用自己的服务器或第三方地图服务查询周边商家。因此，只需要声明getLocation。
2. 配置app.json：

   { "pages": ["pages/index/index"], "window": {...}, "requiredPrivateInfos": ["getLocation"], "permission": { "scope.userLocation": { "desc": "用于展示您周边的美食商家" } } }

   注意，这里还添加了permission字段，用于自定义授权窗口的提示信息，提升用户体验。
3. 编写页面逻辑：在pages/index/index.js中，编写类似第3.4节的完整授权和定位代码。
4. 处理坐标：在getLocation的success回调中，将获取到的latitude和longitude发送给自己的后端接口，或调用腾讯位置服务等API进行逆地址解析和周边搜索。
5. 隐私协议：在提交审核前，在管理后台的隐私保护指引中，明确说明“为了向您推荐周边美食商家，我们会收集您的地理位置信息，该信息仅用于本地计算和展示，不会存储或用于其他用途”。
6. 测试：在真机上全程测试，包括首次使用（弹出隐私协议提示、授权弹窗）、拒绝授权后引导、关闭系统定位后提示等所有分支流程。

通过这个案例，你可以看到从配置、编码到合规上线的完整闭环。处理getLocation:fail the api need to be declared in the requiredPrivateInfos field in app.json这个报错，远不止加一行配置那么简单，它串联起了小程序开发中权限管理、用户体验和隐私合规这三个关键环节。理解其背后的逻辑，才能写出更健壮、更合规的代码。