Ionic5 Capacitor3调用this.file.listDir读取externalRootDirectory目录返回空求助

问题根因 #

该问题并非依赖兼容导致，核心是Capacitor 3默认适配Android分区存储规则，未授予足够的外部存储访问权限时，公共目录查询结果会默认返回空。

解决步骤 #

• 步骤1：配置AndroidManifest权限
  打开android/app/src/main/AndroidManifest.xml文件，添加对应权限和配置：

  <!-- 基础外部存储读写权限 -->
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <!-- Android 11（API 30）及以上访问公共目录需要的全文件管理权限 -->
  <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
  
  <application
    <!-- Android 10适配分区存储的兼容配置 -->
    android:requestLegacyExternalStorage="true"
    ... 其他原有配置不变
  >
  

• 步骤2：安装并调用权限申请插件
  先安装Android权限管理插件：

  npm install @ionic-native/android-permissions@^5.36.0 cordova-plugin-android-permissions@^1.1.5
  

  在AppModule的providers数组中引入AndroidPermissions后，在业务代码中先申请权限再调用目录查询接口：

  import { Platform } from '@ionic/angular';
  import { AndroidPermissions } from '@ionic-native/android-permissions/ngx';
  import { File } from '@ionic-native/file/ngx';
  
  constructor(
    private platform: Platform,
    private androidPermissions: AndroidPermissions,
    private file: File
  ) {}
  
  async initDirQuery() {
    // 申请基础读取权限
    const readPermRes = await this.androidPermissions.checkPermission(
      this.androidPermissions.PERMISSION.READ_EXTERNAL_STORAGE
    );
    if (!readPermRes.hasPermission) {
      await this.androidPermissions.requestPermission(
        this.androidPermissions.PERMISSION.READ_EXTERNAL_STORAGE
      );
    }
    // Android 11及以上额外申请全文件管理权限
    if (this.platform.is('android') && Number(this.platform.version()) >= 30) {
      const managePermRes = await this.androidPermissions.checkPermission(
        this.androidPermissions.PERMISSION.MANAGE_EXTERNAL_STORAGE
      );
      if (!managePermRes.hasPermission) {
        await this.androidPermissions.requestPermission(
          this.androidPermissions.PERMISSION.MANAGE_EXTERNAL_STORAGE
        );
      }
    }
    // 权限申请完成后再查询目录
    this.queryImageDir();
  }
  
  queryImageDir() {
    let _app_EXT_Root_Dir = this.file.externalRootDirectory;
    this.file.listDir(_app_EXT_Root_Dir,"images").then( et =>{
      console.log("List Dir: " + et.length);
    });
  }
  

• 步骤3：依赖版本适配
  可将cordova-plugin-file升级到7.0.1版本，修复已知的Capacitor 3适配问题：

  npm install cordova-plugin-file@7.0.1
  

注意事项 #

• MANAGE_EXTERNAL_STORAGE属于Google Play定义的高危权限，上架应用市场时需要提交明确的使用场景说明，符合平台政策才能过审。如果业务不需要访问公共存储目录，优先使用Capacitor官方的Filesystem API操作应用沙箱内的文件，无需额外申请权限。
• iOS端遇到同类问题时，需要在Info.plist中配置NSPhotoLibraryUsageDescription权限说明，申请相册访问权限后再查询对应目录。

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