Capacitor 4在Android 13（API33）中FileSystem写入权限异常问题

问题详情 #

使用Capacitor 4的FileSystem功能下载图片时，Android 12及以下版本运行正常，但在目标API为33的Android 13设备上触发权限错误。

已配置的AndroidManifest.xml权限：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" android:minSdkVersion="33" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" android:minSdkVersion="33" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" android:minSdkVersion="33" />

执行以下代码时抛出错误：

await Filesystem.writeFile({
     path: fileName + '.jpeg',
     data: base64Data,
     directory: Directory.Documents
});

错误提示：Error: Missing the following permission in AndroidManifest.xml android.permission.WRITE_EXTERNAL_STORAGE

问题原因 #

Android 13（API 33）对存储权限机制做了重大调整：

• WRITE_EXTERNAL_STORAGE权限被废弃，API 33及以上版本的应用无法再获取该权限
• Capacitor 4的FileSystem插件权限校验逻辑仍会检查该权限，导致API 33设备触发错误
• 公共Documents目录属于非媒体公共存储区域，Android 13下写入该目录需要特殊权限

解决方法 #

方法一：修正权限配置（针对公共Documents目录场景） #

将WRITE_EXTERNAL_STORAGE和READ_EXTERNAL_STORAGE权限限定在API 32及以下版本，同时添加Android 13所需的文件管理权限：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" android:minSdkVersion="33" />
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" android:minSdkVersion="33" />

方法二：改用应用私有存储目录（推荐） #

如果无需将文件暴露到公共目录，改用Capacitor的Directory.Data（对应应用私有存储区），无需申请任何外部存储权限：

await Filesystem.writeFile({
     path: fileName + '.jpeg',
     data: base64Data,
     directory: Directory.Data
});

方法三：动态申请文件管理权限（针对公共目录场景） #

若必须使用公共Documents目录，需在代码中动态请求MANAGE_EXTERNAL_STORAGE权限：

import { Permissions } from '@capacitor/permissions';

const permissionResult = await Permissions.request({
  permissions: ['manageExternalStorage']
});

if (permissionResult.manageExternalStorage !== 'granted') {
  console.log('请前往应用设置开启文件管理权限');
} else {
  await Filesystem.writeFile({
     path: fileName + '.jpeg',
     data: base64Data,
     directory: Directory.Documents
  });
}

内容的提问来源于stack exchange，提问作者Miumicream