本文详解如何使用 react-native-fs 在 android/ios 上创建卸载后仍保留的专用文件夹，重点说明系统限制、合规路径选择及安全创建逻辑，并提供可直接运行的跨平台代码示例。
本文详解如何使用 react-native-fs 在 android/ios 上创建卸载后仍保留的专用文件夹，重点说明系统限制、合规路径选择及安全创建逻辑，并提供可直接运行的跨平台代码示例。
在 React Native 应用中，开发者常希望创建一个“长期存在”的文件夹用于缓存媒体、日志或用户生成内容，并期望其在应用卸载重装后依然保留。但需明确一个关键前提：Android 系统（尤其自 Android 10+ 及 Google Play 政策强制要求）禁止应用直接写入内部存储根目录（如 /sdcard/ 或 /storage/emulated/0/）。试图绕过此限制不仅会导致 mkdir 失败（抛出 EACCES 或 EPERM 错误），更可能导致应用被 Google Play 拒绝上架。
因此，真正的持久化（uninstall-persistent）路径仅限于 Android 提供的 App-Specific External Storage 目录——即通过 getExternalFilesDir(null) 返回的路径（对应 RNFS.ExternalStorageDirectoryPath 下的子目录）。该目录位于外部存储（如 SD 卡或内置共享空间）中，虽属“外部”范畴，但实际受系统保护：数据随应用安装自动创建，且卸载时不会被清除（除非用户手动清理或勾选“同时删除应用数据”）。这是 Google 官方推荐、政策合规、兼具持久性与可用性的唯一可行方案。
以下为完整实现方案（兼容 Android 与 iOS）：
import { Platform } from 'react-native';
import RNFS from 'react-native-fs';
/**
* 创建卸载后仍保留的专用文件夹
* ✅ Android：使用 ExternalStorageDirectoryPath + app-specific 子路径（持久）
* ✅ iOS：使用 DocumentDirectoryPath（沙盒内，卸载即清，但为 iOS 唯一可行路径）
*/
const PERSISTED_FOLDER_NAME = 'MyAppData';
const getPersistentBasePath = (): string => {
if (Platform.OS === 'android') {
// 关键：使用 ExternalStorageDirectoryPath（非 DownloadDirectoryPath！）
// RNFS.ExternalStorageDirectoryPath 对应 getExternalFilesDir(null)
return RNFS.ExternalStorageDirectoryPath;
}
// iOS 沙盒无真正卸载持久化，DocumentDirectoryPath 是标准选择
return RNFS.DocumentDirectoryPath;
};
const createPersistentFolder = async (): Promise<string | null> => {
const basePath = getPersistentBasePath();
const folderPath = `${basePath}/${PERSISTED_FOLDER_NAME}`;
try {
const exists = await RNFS.exists(folderPath);
if (exists) {
console.log(`✅ 持久化文件夹已存在：${folderPath}`);
return folderPath;
}
// 创建文件夹（含递归父级，避免路径不存在报错）
await RNFS.mkdir(folderPath, { NSURLIsExcludedFromBackupKey: true });
console.log(`✅ 持久化文件夹创建成功：${folderPath}`);
return folderPath;
} catch (error) {
console.error('❌ 创建持久化文件夹失败：', error);
// 常见错误处理建议：
// - Android 10+：确保已声明 android.permission.WRITE_EXTERNAL_STORAGE（仅 targetSdk < 30 时需要）
// - Android 11+：无需额外权限，但必须使用 getExternalFilesDir 路径
// - iOS：确保 Info.plist 已配置 NSDocumentsFolderUsageDescription（如需访问文件）
return null;
}
};
// 调用示例
createPersistentFolder().then(path => {
if (path) {
// 后续可在此路径下写入文件，例如：
// RNFS.writeFile(`${path}/config.json`, JSON.stringify({ theme: 'dark' }), 'utf8');
}
});⚠️ 重要注意事项：
- 权限声明（Android）：若 targetSdkVersion < 30，需在 AndroidManifest.xml 中添加 <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />；若 ≥30，则完全不需要该权限（系统自动授予对 getExternalFilesDir 的访问权）。
- iOS 持久性说明：iOS 沙盒机制决定了 DocumentDirectoryPath 下的数据在应用卸载时必然被清除。所谓“持久化”在 iOS 上仅指应用生命周期内的可靠存储，无法突破系统沙盒约束。
- 路径验证：始终使用 RNFS.exists() 预检路径，避免重复创建或静默失败。
- 备份控制（iOS 推荐）：为防止 iCloud 备份敏感数据，在 mkdir 时传入 { NSURLIsExcludedFromBackupKey: true }（如上例），确保该目录不参与自动备份。
总结：真正的跨平台持久化文件夹，本质是遵循平台规范的路径选择——Android 用 ExternalStorageDirectoryPath，iOS 用 DocumentDirectoryPath。本方案既满足 Google Play 合规性，又最大化利用系统提供的持久能力，是生产环境推荐的最佳实践。
