上周接了个 uni-app 小程序项目，用户反馈头像上传突然全挂，日志里定位到他自己封装的 chooseAndUploadFile 方法，报错信息翻来覆去看不出个所以然。群里有人张口就让他改基础库，他先是在开发者工具里把基础库从 3.x 切到 2.x，又在 manifest.json 里把 libVersion 改了个遍，折腾两天还是老样子。我远程看了一眼，让他去小程序后台把“用户隐私保护指引”里的相册和摄像头声明打开，五分钟恢复了。
这类问题这半年我碰到不下十次，几乎每次都是权限配置的问题，跟基础库版本真没太大关系。今天就把 chooseAndUploadFile 权限这块从头到尾拆开讲一遍，内容包括报错信息怎么看、权限体系到底分几层、后台和代码分别怎么配、以及真机实测里那些容易坑人的边界情况。
1. 上传图片报错时，为什么大家第一反应是去改基础库
先说清楚一件事：微信小程序里的“基础库”指的是微信客户端内置的一套运行环境，相当于小程序的“操作系统版本”。它决定了你代码里能不能用某个新 API、某个新组件，以及某些接口的行为规则。版本越高，能用的东西越多。
大家一遇到报错就想去改基础库，我能理解。微信开发者工具里的错误提示确实经常带着“基础库 xx.xx.xx”字样，搜索引擎上一翻，大量旧帖子教你“把基础库版本调低一点就不报了”。这些帖子在 2018、2019 年可能还管用，当时 API 不完善，很多问题确实是版本兼容导致的。但放到今天，微信官方对基础库版本有最低要求，你不可能无限降级；更重要的是，权限类报错的根因根本不在基础库版本上。
我见过一个特别典型的案例：开发者在 manifest.json 的 mp-weixin 节点里把 libVersion 改来改去，改到微信开发者工具都开始报警告了，上传图片还是失败。最后查出来是小程序后台的隐私保护指引里压根没声明“相册”和“摄像头”，导致基础库 2.32.3 以上的真机环境直接拦截了 chooseImage 调用。这跟基础库版本高一点低一点有什么关系？没有任何关系。
我整理了一张判断表，你下次遇到报错可以先对照一下：
| 报错特征 | 改基础库有用吗 | 正确做法 |
|---|---|---|
| 提示“chooseMedia is not a function”或 API 不存在 | 有用，调高版本 | 升级基础库或做 API 兼容回退 |
| 提示“privacy agreement is not declared”或 getPrivacySetting 异常 | 没用 | 小程序后台配置用户隐私保护指引 |
| 提示“auth deny”或 authorize 无响应 | 没用 | 引导用户去 openSetting 重新授权 |
| 提示“url not in domain list” | 没用 | 小程序后台配置 uploadFile 合法域名 |
| 真机报错但开发者工具正常 | 不一定 | 清理授权缓存、检查隐私弹窗逻辑 |
记住一个底层逻辑：基础库版本只决定“这个 API 存不存在”，不决定“这个权限给不给你”。权限问题是业务配置和用户操作层面的事，你调基础库调出花来也绕不过去。
2. chooseAndUploadFile 报错背后的权限层次拆解
很多人以为“权限”就是系统弹窗那个授权，其实在小程序里，上传图片这件事会撞上三层完全不同的权限，少配一层都会报错。
第一层是系统级权限。相机权限对应 scope.camera，保存图片到相册对应 scope.writePhotosAlbum，这类权限由微信统一向系统申请，你只能在代码里调用 uni.authorize 发起请求，用户拒绝之后只能通过 uni.openSetting 引导重新打开。但要注意一个反常识的点：从相册选择图片这一步本身是不需要开发者主动申请权限的。微信拉起的是系统相册选择器，选择权在用户手里，所以不存在“相册权限被拒绝”导致 chooseMedia 拉不起来的情况。真正会触发系统授权弹窗的是 sourceType 里带 camera 的情况。
第二层是隐私协议授权。这一层是 2023 年之后新增的“隐形权限”，也是这两年上传图片报错最大的来源。微信要求：如果小程序要调用收集用户信息的接口，比如 chooseMedia、chooseImage、chooseAddress、getPhoneNumber 等，必须先在小程序后台声明“用户隐私保护指引”，并且在端上让用户同意隐私协议。如果你的后台没声明，或者代码里没处理前置的隐私同意流程，基础库一旦开启隐私检查，调用 chooseImage 会直接失败，错误信息往往是“api scope is not declared in the privacy agreement”这类看起来像是报错的提示。
第三层是业务网络层限制。chooseAndUploadFile 的最后一步是 uploadFile，这一步要校验域名白名单。如果文件服务器域名没有配到 uploadFile 合法域名里，或者 HTTPS 证书有问题，会报“url not in domain list”或“request:fail”。这一层跟权限无关，但因为报错时机紧跟在选图成功之后，很多人会误以为是选图权限出了问题。
我的理解是这样的：把上传图片比作进一栋小区的大门，系统级权限是单元门钥匙，没有它你进不了单元门；隐私协议是小区门禁卡，没有它你连小区都进不去；合法域名是访客登记，没登记保安直接把你拦在门口。三道门任何一个环节卡住，最终表现都是“上传图片失败”，但原因可能完全不相关。
3. 从报错信息反推问题：我排查这类 Bug 的三步套路
遇到 chooseAndUploadFile 报错，不要慌，也不用一上来就开调试器逐行看代码。我的排查套路固定三步，基本能定位九成问题。
第一步是看报错信息属于哪一层。把常见的报错关键词记下来，遇到就能很快分类：
| 报错关键词或现象 | 大概率根因 | 首要检查项 |
|---|---|---|
| auth deny、authorize no response | 系统级权限被拒绝 | uni.getSetting 里看对应 scope 状态 |
| privacy agreement、getPrivacySetting 异常 | 隐私协议未配置或未同意 | 后台隐私保护指引声明 |
| url not in domain list | 合法域名没配置 | uploadFile 域名白名单 |
| timeout、connect fail | 网络或后端问题 | 后端日志、接口连通性 |
| fail 但不带任何提示 | 隐私拦截或系统权限极端情况 | 真机 vConsole 看完整堆栈 |
第二步是在微信开发者工具里做模拟验证。工具右侧“普通编译”模式下可以调出“模拟操作”面板，里面有“模拟授权”和“切换隐私协议”等功能，你可以快速模拟用户拒绝授权、同意授权、未同意隐私协议等场景。这里有个经验：工具里一切正常不代表真机正常，工具里能直接复现的报错反而好办，难的是“工具正常、真机报错”的情况。遇到这种情况，优先怀疑隐私协议配置和真机系统授权状态，因为工具的权限模拟和真机策略并不完全一致。
第三步是查后台配置。打开小程序管理后台，进“设置-服务内容声明-用户隐私保护指引”，逐项核对是否声明了相册、摄像头、位置等实际用到的信息。这一步太容易被忽略，因为很多时候后台配置是运营同学负责的，开发这边改完代码发版，根本没检查过后台声明是否完整。隐私指引一旦勾选保存，一般几分钟内生效，不用重新提审，但小程序要重新编译或者冷启动才能拉到最新配置。
说个复盘过的案例。有个朋友的项目，iOS 用户上传头像必现失败，Android 偶尔失败，开发者工具里怎么测都正常。我看他发来的报错截图，vConsole 里只有一句话“chooseImage:fail”。让他查后台隐私保护指引，发现“相册”确实勾了，但“摄像头”没勾。他的选择器里 sourceType 同时包含 album 和 camera，微信在最新基础库下会做整体校验，因为声明不完整直接把整个调用拦了。后台补上摄像头声明后，问题消失。
这个案例说明一个道理：报错信息不明确的时候，别在代码层面反复试，先拿着报错关键词去比对后台配置，很多时候答案不在代码里。
4. 权限修复完整实操：后台声明、manifest 配置、代码侧兼容
这一节是整篇的核心，我直接按步骤写，你照着操作就行。
4.1 小程序后台必须先补的用户隐私保护指引
打开微信公众平台，进小程序管理后台，左侧菜单“设置”，找“服务内容声明”，点开“用户隐私保护指引”。这里你会看到一批可勾选的隐私信息类型。跟上传图片相关的主要是这几项：
- “相册（仅上传功能）”或类似的相册读取选项，如果选择器允许从相册选图，必须勾。
- “摄像头”，如果 choice 的 sourceType 包含 camera，必须勾。
- 有些项目还会涉及“保存文件到相册”，对应写入相册场景，也要勾。
勾选的时候务必和实际功能一致。有次我见过一个项目偷懒把十几项全勾了，提审的时候被以“声明信息与实际采集不符”打回。另外注意，这里的声明文案是微信展示给用户看的，尽量用平实、准确的语言，别搞一堆营销词汇。
保存之后不需要重新提审，但小程序端的隐私配置有几分钟的同步延迟，建议等五分钟再测试。
4.2 manifest.json 里需要改的两处配置
第一步，确认 mp-weixin 节点里的 appid 和你在小程序后台用的是同一个，AppID 对不上，隐私配置拉取不到，其他都白搭。第二步，在 mp-weixin 节点里加上 permission 字段，用于声明位置、摄像头等系统级接口的用途说明。这里不用把所有权限都塞进去，像相册权限在微信里不需要通过这个字段声明，写了反而多余，但摄像头等建议写上，方便审核侧理解用途。
{ "mp-weixin": { "appid": "你的AppID", "setting": { "urlCheck": false }, "usingComponents": true, "permission": { "scope.camera": { "desc": "用于拍照上传图片" } }, "__usePrivacyCheck__": true } }4.3 代码侧必须处理隐私协议的前置同意
基础库版本在 2.32.3 及以上时，如果后台开启了隐私检查，调用 chooseMedia 等隐私接口前必须先取得用户同意。这里有两个方案：一是完全不管，让微信在调用隐私接口时自动弹默认的隐私授权弹窗，用户体验一般；二是在业务里先主动检测，再弹一个自定义的同意弹窗，体验更好，也更容易通过审核。
我推荐第二种。在 uni-app 里相关的 API 主要是 uni.getPrivacySetting 和 uni.requirePrivacyAuthorize。下面这段代码是我常用的隐私校验函数：
async function ensurePrivacyAgreed() { // 非微信小程序端直接放行 // #ifdef MP-WEIXIN const res = await uni.getPrivacySetting({ fail: () => ({ needAuthorization: false }) }); if (!res.needAuthorization) return true; const agreed = await new Promise((resolve) => { uni.showModal({ title: '隐私保护提示', content: `请先阅读并同意《${res.privacyContractName || '隐私保护指引'}》后再使用图片上传功能`, confirmText: '同意', cancelText: '不同意', success: (r) => resolve(!!r.confirm) }); }); if (!agreed) return false; await uni.requirePrivacyAuthorize(); return true; // #endif // #ifndef MP-WEIXIN return true; // #endif }这段代码的逻辑是：先查 needAuthorization 是否需要弹隐私协议，不需要就直接过；需要就弹一个 confirm 弹窗，用户点同意后再调用 requirePrivacyAuthorize 完成授权登记。这里有个细节：requirePrivacyAuthorize 必须在用户点击“同意”之后立即调用，如果在隐私弹窗弹出期间就提前调用，会被微信拦截。所以我把调用放在 Promise 的回调里，保证用户操作完再执行。
4.4 把选图、授权、上传封装成完整的 chooseAndUploadFile
实现这个方法的重点不是代码本身，而是流程顺序必须正确。我的顺序是这样的：先过隐私协议校验，再处理相机权限，再选图，最后上传。如果用户拒绝相机权限，要在选图前就拦截，否则用户拍完照才发现上传不了，体验很差。
async function chooseAndUploadFile(params) { const { url, count = 1, sourceType = ['album', 'camera'], name = 'file', formData = {} } = params; // 第一步：隐私协议校验 const privacyPassed = await ensurePrivacyAgreed(); if (!privacyPassed) { uni.showToast({ title: '需要同意隐私协议才能上传图片', icon: 'none' }); return null; } // 第二步：拍照场景检查相机权限 if (sourceType.includes('camera')) { try { const authRes = await uni.getSetting(); if (authRes.authSetting['scope.camera'] === false) { // 用户之前拒绝过，引导去设置页 const modalRes = await uni.showModal({ title: '提示', content: '相机权限已被拒绝，请到设置中开启后再拍照', confirmText: '去设置' }); if (modalRes.confirm) { uni.openSetting(); } return null; } await uni.authorize({ scope: 'scope.camera' }); } catch (e) { uni.showToast({ title: '相机权限获取失败', icon: 'none' }); return null; } } // 第三步：选图，推荐使用 chooseMedia let tempFilePath; try { const mediaRes = await uni.chooseMedia({ count, mediaType: ['image'], sourceType }); tempFilePath = mediaRes.tempFiles[0].tempFilePath; } catch (e) { // 用户取消选图或选择失败 return null; } // 第四步：上传 try { const uploadRes = await new Promise((resolve, reject) => { uni.uploadFile({ url, filePath: tempFilePath, name, formData, success: resolve, fail: reject }); }); return uploadRes; } catch (e) { uni.showToast({ title: '上传失败，请检查网络', icon: 'none' }); return null; } }这里特别说明一下为什么推荐 uni.chooseMedia 而不是 uni.chooseImage。微信官方从基础库 2.10.0 开始推荐 chooseMedia，它的返回结构是 tempFiles 数组，里面直接带文件路径和类型，用起来更顺手；而且 chooseImage 在隐私拦截策略上更容易触发问题。如果你的项目要兼容特别老的基础库，可以加一个版本判断，低于 2.10.0 再回退到 uni.chooseImage。
4.5 改完之后的验证清单
代码和后台配置都改完，按下面这个清单过一遍基本就稳了：
- 开发者工具里清除授权数据，重新编译，确认隐私弹窗能正常弹出。
- 点击“同意”后，选择相册图片能走到上传成功。
- 选“不同意”，确认接口被拦截，并且业务上有友好的 toast 提示。
- 真机预览，分别测试相册选图和拍照两条路径。
- 在 iOS 和 Android 各测一遍，重点看相机权限的处理。
- 后台隐私保护指引确认已经保存并生效。
5. 实测中比文档更容易踩的 5 个权限坑
代码能跑通只是第一步，真机环境里还有一堆“文档没写但实际会遇到”的坑，我挑五个最典型的说一下。
第一个坑：用户第一次拒绝相机授权之后，你再怎么调 authorize 都不会弹窗。这是微信系统授权机制决定的，应用只能发起一次系统授权申请，拒绝之后状态就固定了。所以代码里不能只依赖 authorize，要先 getSetting 看 scope.camera 的状态，如果是 false 就直接引导 openSetting。上面封装函数里我已经处理了这种情况。
第二个坑：iOS 14 之后用户可以选择“部分照片”授权，导致选图成功但后续处理临时文件时出各种诡异问题。比如读取不到某张照片的内容、上传后文件损坏等。这种情况下最稳的做法是在用户选图成功后不要立刻对大文件做压缩等耗时操作，先用相对路径上传，等上传成功后再做后续处理。如果需要引导用户设置成“所有照片”，可以在 uploadFile 失败且错误码指向文件权限时弹窗提示。
第三个坑：老项目从基础库 2.x 升到 3.x，上传图片突然全挂。很多人第一反应是降回 2.x，这是标准的错误解法。3.x 之后隐私接口校验是强制的，老项目没做隐私适配，升级自然翻车。正确做法是按上面第 4 节的内容补隐私弹窗、后台声明、检查usePrivacyCheck，而不是退版本。
第四个坑：开发工具里永远正常，真机一测就挂。这里的原因很杂，最常见的两种：一是开发者工具默认跳过了一些真机才有的检查，比如隐私弹窗的频繁调用限制；二是真机上的授权缓存没有清干净。排查方法是真机调试里开 vConsole，看完整错误堆栈，然后在“小程序设置-清理缓存-清除授权数据”里重置权限状态，再重新测。
第五个坑：uploadFile 返回 404 或者 500，控制台没有任何权限类报错。这种问题百分之百不在权限层，而是后端接口或者参数问题。常见的有：后端接口要求字段名是 file，你传了 image；后端没开启 multipart 解析；服务器没配 HTTPS 证书，微信直接拦截。遇到这种情况别在前端权限上折腾了，直接用 Postman 模拟一次 uploadFile 请求，跑通了再回来看代码。
6. 最后放一条自查清单，收藏备用
这一节就当是配套材料，遇到问题按顺序查，别跳步：
- 后台隐私保护指引是否声明了“相册”和“摄像头”。
- manifest.json 里的 AppID 是否和后台一致。
- 前端代码是否调用了 uni.getPrivacySetting 并处理了 needAuthorization。
- 用户拒绝权限后是否有 openSetting 引导。
- uploadFile 的合法域名是否已配置。
- 后端接口是否支持 multipart/form-data 上传。
- 真机测试前是否清过授权缓存。
- 打印 uploadFile 的返回体，确认是业务报错还是网络层报错。
我在实际项目里发现，只要把第 1 条和第 3 条做对，九成以上的 chooseAndUploadFile 报错都能原地消失。剩下的一成再按清单往下查，基本也能在半小时内定位。
上传图片这个功能，看起来就是选图加上传两个步骤，真正落地时涉及的权限链路其实挺长的。我的建议是不要把这些逻辑散落在页面里，封装成一个统一的工具函数，所有页面共用。这样以后不管是隐私协议更新还是权限策略调整，你只需要改一个文件，排错的时候也不用翻着十几个页面找问题。这是我踩了无数次坑之后觉得最值得做的一件事。
