Android 外部存储权限问题解决方法

理解 Android 存储权限错误：EACCES

当 Android 应用尝试访问外部存储（如 /storage/emulated/0/Download/）中的文件，但缺乏必要的权限时，就会抛出 java.io.FileNotFoundException: /path/to/file.xlsx: open failed: EACCES (Permission denied) 异常。这里的 EACCES 明确指示了“访问被拒绝”，意味着操作系统出于安全考虑，阻止了应用对指定路径的读写操作。

此问题的根源在于 Android 系统对外部存储访问权限的严格控制和不断演进的隐私策略。从 Android 6.0 (Marshmallow) 开始引入的运行时权限，到 Android 10 (Q) 和 Android 11 (R) 引入的分区存储（Scoped Storage），都对应用访问外部存储的方式提出了更高的要求。特别是分区存储，它旨在限制应用只能访问自身创建的文件或特定媒体类型的文件，除非获得特殊权限。

核心权限声明与配置

为了访问外部存储，应用需要在 AndroidManifest.xml 中声明相应的权限。根据 Android 版本的不同，所需的权限和配置也有所区别。

1. 基础外部存储权限 (Android 6.0 - Android 10): 对于 Android 6.0 (API 23) 到 Android 10 (API 29) 的设备，READ_EXTERNAL_STORAGE 和 WRITE_EXTERNAL_STORAGE 是访问外部存储的常用权限。

2. 针对 Android 10 的兼容性处理 (requestLegacyExternalStorage): 在 Android 10 (API 29) 中，Google 引入了分区存储。为了让现有应用能够平滑过渡，可以设置 android:requestLegacyExternalStorage="true" 来暂时禁用分区存储，恢复旧版存储模型。

   注意： requestLegacyExternalStorage 在 Android 11 及更高版本中不再有效。

3. 针对 Android 11 及更高版本的全文件访问权限 (MANAGE_EXTERNAL_STORAGE): 从 Android 11 (API 30) 开始，如果应用需要访问设备上的所有文件（例如文件管理器、备份工具等），则必须声明 MANAGE_EXTERNAL_STORAGE 权限。此权限被称为“所有文件访问权限”，并需要用户手动授权。

   tools:ignore="ScopedStorage" 属性用于抑制 Lint 警告，表明你清楚正在请求此特殊权限。

   完整的 Manifest 示例： 结合上述权限，一个典型的 AndroidManifest.xml 片段可能如下所示：

   请注意，minSdkVersion 和 targetSdkVersion 对权限行为有重要影响。建议将 targetSdkVersion 更新到最新稳定版本，并根据其行为调整权限处理逻辑。

运行时权限请求

仅仅在 AndroidManifest.xml 中声明权限是不够的。对于危险权限（如 READ_EXTERNAL_STORAGE 和 WRITE_EXTERNAL_STORAGE），从 Android 6.0 (API 23) 开始，应用必须在运行时向用户请求授权。

以下是请求外部存储读写权限的基本流程：

1. 检查权限是否已授予： 使用 ContextCompat.checkSelfPermission() 方法检查当前是否已获得权限。

2. 请求权限： 如果权限尚未授予，使用 ActivityCompat.requestPermissions() 方法向用户发起权限请求。

3. 处理权限请求结果： 在 onRequestPermissionsResult() 回调方法中处理用户的选择。

示例代码：

import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Build;
import android.os.Environment;
import android.provider.Settings;
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;

// ... 在你的Activity中

private static final int REQUEST_CODE_STORAGE_PERMISSION = 101;
private static final int REQUEST_CODE_MANAGE_ALL_FILES_ACCESS = 102;

/**
 * 检查并请求存储权限。
 * 如果是 Android 11+ 且需要所有文件访问，会引导用户到设置页面。
 */
private void checkStoragePermissions() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { // Android 11 (API 30) 及更高版本
        if (Environment.isExternalStorageManager()) {
            // 已获得所有文件访问权限
            performFileOperation();
        } else {
            // 请求所有文件访问权限
            requestManageAllFilesAccess();
        }
    } else { // Android 10 (API 29) 及以下版本
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.READ_EXTERNAL_STORAGE)
                == PackageManager.PERMISSION_GRANTED &&
            ContextCompat.checkSelfPermission(this, Manifest.permission.WRITE_EXTERNAL_STORAGE)
                == PackageManager.PERMISSION_GRANTED) {
            // 已获得读写权限
            performFileOperation();
        } else {
            // 请求读写权限
            ActivityCompat.requestPermissions(this,
                    new String[]{Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.WRITE_EXTERNAL_STORAGE},
                    REQUEST_CODE_STORAGE_PERMISSION);
        }
    }
}

/**
 * 请求 MANAGE_EXTERNAL_STORAGE 权限 (Android 11+)
 */
private void requestManageAllFilesAccess() {
    try {
        android.content.Intent intent = new android.content.Intent(Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION);
        intent.setData(android.net.Uri.parse("package:" + getPackageName()));
        startActivityForResult(intent, REQUEST_CODE_MANAGE_ALL_FILES_ACCESS);
    } catch (Exception e) {
        // 如果无法启动特定应用设置页面，则尝试启动所有文件访问设置页面
        android.content.Intent intent = new android.content.Intent(Settings.ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION);
        startActivityForResult(intent, REQUEST_CODE_MANAGE_ALL_FILES_ACCESS);
    }
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    if (requestCode == REQUEST_CODE_STORAGE_PERMISSION) {
        if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            // 权限已授予
            performFileOperation();
        } else {
            // 权限被拒绝，可以提示用户或禁用相关功能
            android.widget.Toast.makeText(this, "存储权限被拒绝，无法访问文件。", android.widget.Toast.LENGTH_SHORT).show();
        }
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, android.content.Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == REQUEST_CODE_MANAGE_ALL_FILES_ACCESS) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
            if (Environment.isExternalStorageManager()) {
                // 再次检查权限，确保用户已授权
                performFileOperation();
            } else {
                android.widget.Toast.makeText(this, "所有文件访问权限被拒绝，无法访问文件。", android.widget.Toast.LENGTH_SHORT).show();
            }
        }
    }
}

/**
 * 实际执行文件操作的方法
 */
private void performFileOperation() {
    String filePath = Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS).getAbsolutePath() + "/Joueurs.xlsx";
    java.io.File fileName = new java.io.File(filePath);

    if (!fileName.exists()) {
        android.widget.Toast.makeText(this, "文件不存在: " + filePath, android.widget.Toast.LENGTH_LONG).show();
        return;
    }

    try {
        if (!fileName.canRead()) {
            // 尝试设置文件可读（在某些情况下可能有效，但权限不足时仍会失败）
            fileName.setReadable(true);
        }

        java.io.FileInputStream fileJoueur = new java.io.FileInputStream(fileName);
        org.apache.poi.xssf.usermodel.XSSFWorkbook myWorkBook = new org.apache.poi.xssf.usermodel.XSSFWorkbook(fileJoueur);
        org.apache.poi.xssf.usermodel.XSSFSheet mySheet = myWorkBook.getSheetAt(0);
        // ... 继续处理 Excel 文件
        android.widget.Toast.makeText(this, "成功读取Excel文件！", android.widget.Toast.LENGTH_SHORT).show();
        fileJoueur.close();
        myWorkBook.close();
    } catch (java.io.FileNotFoundException e) {
        android.util.Log.e("FileAccess", "文件未找到或权限不足: " + e.getMessage(), e);
        android.widget.Toast.makeText(this, "文件未找到或权限不足: " + e.getMessage(), android.widget.Toast.LENGTH_LONG).show();
    } catch (java.io.IOException e) {
        android.util.Log.e("FileAccess", "文件读取错误: " + e.getMessage(), e);
        android.widget.Toast.makeText(this, "文件读取错误: " + e.getMessage(), android.widget.Toast.LENGTH_LONG).show();
    }
}

// 在你的按钮点击事件中调用
// BoutonLicencies.setOnClickListener(v -> checkStoragePermissions());

处理 Android 11 及更高版本的文件访问

对于 Android 11 (API 30) 及更高版本，分区存储是默认行为。这意味着即使声明了 READ_EXTERNAL_STORAGE 和 WRITE_EXTERNAL_STORAGE，应用也只能访问：

• 应用私有目录 (Context.getExternalFilesDir(), Context.getExternalCacheDir())。
• 通过 MediaStore API 访问的媒体文件（图片、视频、音频），且仅限于应用自身创建的或用户明确授予访问权限的。
• 通过 Storage Access Framework (SAF) 选择的文件。

如果应用确实需要访问外部存储中的任意文件（例如用户下载的 Excel 文件），则 MANAGE_EXTERNAL_STORAGE 权限是目前最直接的解决方案。然而，获取此权限需要用户手动导航到设置页面进行授权，并且 Google Play 对使用此权限的应用有严格的审查政策。

推荐方案：使用 Storage Access Framework (SAF) 或 MediaStore API

在大多数情况下，为了遵循 Android 的最佳实践和用户隐私原则，推荐使用 SAF 或 MediaStore API 来访问文件，而不是请求广范围的存储权限。

• Storage Access Framework (SAF): SAF 允许用户通过系统文件选择器授予应用对特定文件或目录的临时访问权限，而无需应用拥有全局存储权限。这是访问用户下载目录中特定文件的推荐方式。

  // 启动文件选择器
  private static final int PICK_EXCEL_FILE_REQUEST = 1;
  
  private void openFilePicker() {
      android.content.Intent intent = new android.content.Intent(android.content.Intent.ACTION_OPEN_DOCUMENT);
      intent.addCategory(android.content.Intent.CATEGORY_OPENABLE);
      intent.setType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); // for .xlsx
      // intent.setType("application/vnd.ms-excel"); // for .xls
      startActivityForResult(intent, PICK_EXCEL_FILE_REQUEST);
  }
  
  @Override
  protected void onActivityResult(int requestCode, int resultCode, android.content.Intent data) {
      super.onActivityResult(requestCode, resultCode, data);
      if (requestCode == PICK_EXCEL_FILE_REQUEST && resultCode == RESULT_OK) {
          if (data != null) {
              android.net.Uri uri = data.getData();
              try {
                  // 使用 ContentResolver 获取文件输入流
                  java.io.InputStream inputStream = getContentResolver().openInputStream(uri);
                  org.apache.poi.xssf.usermodel.XSSFWorkbook myWorkBook = new org.apache.poi.xssf.usermodel.XSSFWorkbook(inputStream);
                  org.apache.poi.xssf.usermodel.XSSFSheet mySheet = myWorkBook.getSheetAt(0);
                  // ... 处理 Excel 文件
                  android.widget.Toast.makeText(this, "成功通过SAF读取Excel文件！", android.widget.Toast.LENGTH_SHORT).show();
                  inputStream.close();
                  myWorkBook.close();
              } catch (java.io.FileNotFoundException e) {
                  android.util.Log.e("SAF_FileAccess", "文件未找到: " + e.getMessage(), e);
                  android.widget.Toast.makeText(this, "文件未找到或无法打开: " + e.getMessage(), android.widget.Toast.LENGTH_LONG).show();
              } catch (java.io.IOException e) {
                  android.util.Log.e("SAF_FileAccess", "文件读取错误: " + e.getMessage(), e);
                  android.widget.Toast.makeText(this, "文件读取错误: " + e.getMessage(), android.widget.Toast.LENGTH_LONG).show();
              }
          }
      }
  }
  // 在你的按钮点击事件中调用
  // BoutonLicencies.setOnClickListener(v -> openFilePicker());

• MediaStore API: 适用于访问图片、视频、音频等媒体文件。它提供了一种结构化的方式来查询和操作这些文件，而无需直接的文件路径访问。对于 Excel 文件，SAF 是更合适的选择。

代码实践与注意事项

1. 文件路径的正确获取： 避免硬编码 /storage/emulated/0/Download/ 这样的路径。应使用 Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS) 来获取下载目录的标准路径，这更具兼容性。

2. 权限检查与错误处理： 在进行任何文件操作之前，务必检查是否已获得所需权限。捕获 FileNotFoundException 和 IOException 以优雅地处理文件不存在、权限不足或读写错误的情况。

3. 针对特定设备（如 Galaxy S21）的兼容性考虑： 某些设备制造商可能会对 Android 系统进行定制，导致权限设置界面或行为略有不同。例如，Galaxy S21 运行 Android 11 或更高版本时，如果应用未正确处理分区存储和 MANAGE_EXTERNAL_STORAGE 权限，用户可能无法在设置中找到“所有文件”的权限选项，或者即使找到了也无法正常工作。在这种情况下，确保 targetSdkVersion 匹配设备版本，并正确实现 MANAGE_EXTERNAL_STORAGE 的请求流程至关重要。

4. 更新 targetSdkVersion 的重要性： 将 targetSdkVersion 更新到最新版本，可以确保应用的行为与最新 Android 系统的安全和隐私特性保持一致。虽然这可能需要修改代码以适应新的行为，但从长远来看，这有助于提高应用的兼容性和安全性。

总结

解决 Android FileNotFoundException: EACCES 错误的关键在于深入理解 Android 存储权限模型的演变，并根据应用的 targetSdkVersion 和所需的访问级别，正确声明和请求权限。对于 Android 11 及更高版本，优先考虑使用 Storage Access Framework (SAF) 进行文件访问，以符合分区存储的最佳实践。如果确实需要广泛的文件访问权限，则应正确实现 MANAGE_EXTERNAL_STORAGE 的请求流程，并准备好应对 Google Play 的审核要求。通过细致的权限管理和错误处理，可以确保应用在不同 Android 版本和设备上稳定、安全地访问外部文件。