Cordova升级到10及Android SDK 30后外部文件系统读取失效如何解决

1. 适配权限配置变更 #

Android 11（API 30）强制开启分区存储规则，Cordova Android 10.x版本默认适配了该特性，原有旧版权限配置会直接失效，需要做如下修改：

• 先在AndroidManifest.xml中添加适配API 30的权限声明：

  <!-- 适配API 32及以下的媒体读取权限 -->
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
  <!-- 如需读取整个外部存储的任意文件需要添加该权限，Google Play上架需额外说明使用场景 -->
  <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
  

• 在项目根目录的config.xml中，android平台配置段添加如下参数，关闭Cordova默认的分区存储强制隔离逻辑：

  <preference name="AndroidPersistentFileLocation" value="Compatibility" />
  <preference name="AndroidExtraFilesystems" value="files,files-external,documents,sdcard,cache,cache-external,assets,root" />
  

2. 调整运行时权限申请逻辑 #

API 30下原有READ_EXTERNAL_STORAGE权限申请仅对API 29及以下版本生效，API 30+的权限申请需要分场景处理：

• 仅需要读取公共媒体文件（照片、视频、音频、下载文件）：正常申请READ_EXTERNAL_STORAGE权限即可正常访问
• 需要读取整个外部存储的任意文件：需要引导用户跳转到系统设置页手动开启「所有文件访问权限」，原生侧调用示例如下：

  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
      if (!Environment.isExternalStorageManager()) {
          Intent intent = new Intent(Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION);
          intent.setData(Uri.parse("package:" + getPackageName()));
          startActivityForResult(intent, 1001);
      }
  }
  

如果使用官方cordova-plugin-file插件，直接升级到6.0.2及以上版本即可默认适配上述权限逻辑。

3. 修正文件路径写法 #

Cordova 10修改了外部文件的路径解析规则，原有硬编码的file:///sdcard/、file:///storage/emulated/0/类路径会直接失效，必须通过cordova-plugin-file提供的官方路径常量拼接目标路径：

• 外部存储根目录对应常量：cordova.file.externalRootDirectory
• 公共下载目录对应路径：cordova.file.externalRootDirectory + 'Download/'
• 应用专属外部存储目录对应常量：cordova.file.externalApplicationStorageDirectory

4. 常见问题排查 #

• 确认cordova-plugin-file版本 ≥ 6.0.0，低于该版本不兼容Cordova Android 10+
• 确认要访问的文件不在其他应用的专属目录下，分区存储规则下禁止直接读取其他应用专属目录的文件
• 不要使用任何第三方废弃的文件操作插件，优先使用官方维护的cordova-plugin-file处理文件逻辑

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