Capacitor 4.8.0中Android 13写入Documents目录权限被拒问题

问题核心原因 #

Android 13（API 33）彻底重构了存储权限模型：废弃了READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE权限对公共目录的读写能力，原有的publicStorage权限逻辑仅适用于API 32及以下版本。直接写入Documents/Appname/目录会被系统拦截，即使授权临时权限也无效。

两种可行解决方案 #

方案一：使用MANAGE_EXTERNAL_STORAGE特殊权限（需用户手动授权） #

该权限允许应用访问所有外部存储，但Google Play对其审核严格，仅文件管理器类应用建议使用。

1. 修改AndroidManifest.xml权限声明

<!-- 仅API32及以下版本保留旧权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<!-- API33+需要的特殊权限 -->
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

2. 权限请求与文件写入代码

import { Capacitor } from '@capacitor/core';
import { Permissions, PermissionType } from '@capacitor/permissions';
import { Filesystem, Directory } from '@capacitor/filesystem';

async function requestStorageAccess() {
  if (Capacitor.getPlatform() !== 'android') return true;
  
  const androidVersion = parseInt(Capacitor.getPlatformVersion(), 10);
  if (androidVersion >= 33) {
    const status = await Permissions.check({ permission: PermissionType.ManageExternalStorage });
    if (status.state !== 'granted') {
      // 跳转到系统设置页面让用户手动授权
      await Capacitor.startActivity({
        action: 'android.settings.MANAGE_APP_ALL_FILES_ACCESS_PERMISSION',
        data: `package:${Capacitor.getAppId()}`
      });
      // 授权后需重新检查状态
      const newStatus = await Permissions.check({ permission: PermissionType.ManageExternalStorage });
      return newStatus.state === 'granted';
    }
  } else {
    const result = await Permissions.request({ permission: PermissionType.WriteExternalStorage });
    return result.state === 'granted';
  }
  return true;
}

async function writePdfToDocuments() {
  const hasAccess = await requestStorageAccess();
  if (!hasAccess) {
    console.error('存储权限未授权');
    return;
  }

  try {
    await Filesystem.writeFile({
      path: 'Documents/YourAppName/filename.pdf',
      data: YOUR_PDF_BASE64_DATA, // 替换为你的PDF base64字符串
      directory: Directory.External,
      recursive: true // 自动创建不存在的目录
    });
    console.log('文件写入成功');
  } catch (err) {
    console.error('写入失败:', err);
  }
}

方案二：使用存储访问框架（SAF，推荐） #

该方案符合Android 13隐私规范，无需特殊权限，需用户手动选择保存位置，不会触发Google Play审核问题。

import { Capacitor } from '@capacitor/core';
import { Filesystem, Directory } from '@capacitor/filesystem';

async function savePdfWithSAF() {
  if (Capacitor.getPlatform() !== 'android') return;

  try {
    // 请求用户选择Documents目录下的保存位置
    const safResult = await Filesystem.requestDirectoryAccess({
      directory: 'Documents'
    });

    if (!safResult.uri) {
      console.error('用户取消了目录选择');
      return;
    }

    // 通过SAF URI写入文件
    await Filesystem.writeFile({
      path: 'filename.pdf',
      data: YOUR_PDF_BASE64_DATA,
      directory: Directory.External,
      uri: safResult.uri,
      recursive: true
    });
    console.log('文件保存成功');
  } catch (err) {
    console.error('SAF保存失败:', err);
  }
}

关键注意事项 #

• API 33下，WRITE_EXTERNAL_STORAGE权限仅能访问应用私有外部存储，无法读写公共Documents目录。
• MANAGE_EXTERNAL_STORAGE权限需用户手动到系统设置开启，且Google Play仅允许特定类型应用使用。
• 优先选择SAF方案，既符合隐私政策，又能避免权限审核风险。

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