React Native Android/iOS外部存储权限配置及Android11+权限请求失败排查

核心问题分析 #

Android 11（API 30）及以上版本对外部存储权限做了严格限制：

• MANAGE_EXTERNAL_STORAGE 属于特殊权限，无法通过PermissionsAndroid.request直接弹出授权对话框，必须引导用户跳转到应用设置页面手动开启
• WRITE_EXTERNAL_STORAGE 在API 30+中仅对应用私有目录和媒体文件生效，无法访问其他公共目录

修复步骤 #

1. 修正AndroidManifest.xml配置 #

移除android:required="true"（该属性仅用于Google Play权限声明，不影响权限生效），补充READ_EXTERNAL_STORAGE以适配部分场景：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

    <application
        android:name=".MainApplication"
        android:label="@string/app_name"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:allowBackup="false"
        android:theme="@style/AppTheme"
        android:supportsRtl="true">
        <activity
            android:name=".MainActivity"
            android:label="@string/app_name"
            android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
            android:launchMode="singleTask"
            android:windowSoftInputMode="adjustResize"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

2. 重写权限请求逻辑 #

针对API 30+，先检查权限状态，未授权则引导用户到应用设置页面手动开启：

import { Platform, Linking, PermissionsAndroid } from 'react-native';

const requestStoragePermission = async () => {
    try {
        if (Platform.OS === 'android') {
            if (Platform.Version >= 30) {
                // 检查是否已获取MANAGE_EXTERNAL_STORAGE权限
                const hasPermission = await PermissionsAndroid.check(
                    PermissionsAndroid.PERMISSIONS.MANAGE_EXTERNAL_STORAGE
                );
                if (hasPermission) {
                    console.log('存储权限已授权');
                    return true;
                }
                // 引导用户跳转到应用设置页面
                const canOpenSettings = await Linking.canOpenURL('app-settings:');
                if (canOpenSettings) {
                    await Linking.openSettings();
                    // 返回后再次检查权限状态
                    const afterCheck = await PermissionsAndroid.check(
                        PermissionsAndroid.PERMISSIONS.MANAGE_EXTERNAL_STORAGE
                    );
                    return afterCheck;
                }
                return false;
            } else {
                // API 29及以下请求WRITE_EXTERNAL_STORAGE
                const granted = await PermissionsAndroid.request(
                    PermissionsAndroid.PERMISSIONS.WRITE_EXTERNAL_STORAGE,
                    {
                        title: '存储权限申请',
                        message: '应用需要访问存储以下载文件',
                        buttonNeutral: '稍后再说',
                        buttonNegative: '取消',
                        buttonPositive: '确定',
                    },
                );
                return granted === PermissionsAndroid.RESULTS.GRANTED;
            }
        }
        return true;
    } catch (err) {
        console.warn('权限请求失败: ', err);
        return false;
    }
};

3. 优先使用应用私有目录 #

如果无需访问公共目录，推荐使用应用私有路径（无需特殊权限）：

• 通过react-native-fs的DocumentDirectoryPath或ExternalDirectoryPath获取路径

iOS的外部存储权限分两种场景配置：

1. 访问相册/媒体文件 #

在Info.plist中添加权限描述：

<!-- 读取相册权限说明 -->
<key>NSPhotoLibraryUsageDescription</key>
<string>应用需要访问相册以保存或读取下载的文件</string>
<!-- 写入相册权限说明（iOS 11+ 可选） -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>应用需要将下载的文件保存到相册</string>

2. 让应用文件在"文件"应用中可见 #

若需要用户通过系统"文件"应用访问应用内文件，在Info.plist中添加以下配置：

<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>

开启后，应用的Documents目录会在"文件"应用中显示，用户可直接访问和管理文件。

iOS权限请求逻辑（基于react-native-permissions） #

import { Platform } from 'react-native';
import { check, request, PERMISSIONS, RESULTS } from 'react-native-permissions';

const requestiOSStoragePermission = async () => {
    if (Platform.OS !== 'ios') return true;
    
    // 检查相册权限状态
    const status = await check(PERMISSIONS.IOS.PHOTO_LIBRARY);
    if (status === RESULTS.GRANTED) return true;
    
    // 请求权限
    const result = await request(PERMISSIONS.IOS.PHOTO_LIBRARY);
    return result === RESULTS.GRANTED;
};

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