必须用plus.android.requestpermissions申请安卓存储权限,且manifest.json须显式声明android.permission.write_external_storage,否则静默失败;uni.authorize在app端对存储权限无效。
uni-app 申请安卓存储权限不能只调 uni.authorize,必须用 plus.android.requestpermissions,且 manifest.json 里必须提前声明 android.permission.write_external_storage,否则白忙一场。
manifest.json 必须显式声明存储权限
安卓 6.0+ 要求「声明 + 运行时申请」双到位。只在代码里调 plus.android.requestPermissions,但 manifest.json 没配,打包后根本不会弹窗,也不会报错,静默失败。
- 可视化配置:HBuilderX 中打开
manifest.json→ 切到「App权限配置」→「Android权限配置」→ 勾选「读写外部存储」 - 代码配置:在
manifest.json的"app-plus".distribute.android.permissions数组中加入:"android.permission.WRITE_EXTERNAL_STORAGE" - 注意:Android 10+(API 29)起,该权限对访问公共目录作用已大幅削弱,但它仍是触发系统弹窗、引导用户授权的必要前提
运行时必须用 plus.android.requestPermissions
uni.authorize({ scope: 'scope.writePhotosAlbum' }) 是小程序逻辑,在 App 端完全不生效。安卓原生存储权限(如读写 SD 卡)只能走 plus.android.requestPermissions。
- 单权限申请示例:
plus.android.requestPermissions( ['android.permission.WRITE_EXTERNAL_STORAGE'], (result) => { if (result.granted.length > 0) { console.log('授权成功'); } else if (result.deniedPresent.length > 0) { console.log('用户本次拒绝'); } else if (result.deniedAlways.length > 0) { console.log('用户勾选了“不再询问”'); } }, (err) => console.error('申请出错', err) ); - 多个权限可一次性申请,比如相机+存储:
['android.permission.CAMERA', 'android.permission.WRITE_EXTERNAL_STORAGE'] - 回调里的
deniedAlways表示“永久拒绝”,此时必须跳转设置页,不能再反复调用requestPermissions
用户拒绝后怎么补救?
一旦用户点“拒绝”并勾选“不再询问”,plus.android.requestPermissions 就再也不会弹窗,直接进回调且 deniedAlways.length > 0。这时候唯一合法路径是唤起系统设置页。
- 先用
uni.showModal提示用途,例如:“需要访问相册和文件,用于上传头像和保存记录”——这是合规硬性要求,缺说明会被应用市场拒审 - 再调
plus.android.openSetting()打开本应用设置页(iOS/Android 均支持) - 注意:如果
manifest.json没声明权限,openSetting页面里压根不显示对应开关,用户无从开启
Android 10+ 存储路径和权限的实际影响
即使你拿到了 WRITE_EXTERNAL_STORAGE,在 Android 10+ 上也不能随便往 /storage/emulated/0/ 写文件了。系统强制执行分区存储(Scoped Storage)。
- 推荐优先使用应用私有目录:
_doc、_downloads、_pictures等,路径由uni.getEnvInfo().platform === 'android'+plus.io.resolveLocalFileSystemURL获取,无需权限 - 若真需访问公共媒体文件(如用户相册照片),应改用
uni.chooseImage或uni.chooseMedia,它们内部已适配 MediaStore API - 强行用旧路径 + 权限,在 Android 11+ 可能被系统拦截,返回
IOError或空列表
最容易被忽略的是:权限声明、运行时申请、用途说明、降级路径(私有目录)这四点缺一不可。少一个,轻则功能失效,重则过不了安卓上架审核。











