# @exodus/react-native-fs 中文文档 规范地址：https://npmcn.com/package/%40exodus/react-native-fs/ 版本：2\.23\.0-exodus\.0 npm 元数据更新时间：2026-10-06T21:02:43.224Z 中文译文更新时间：2026-11-14T03:56:58.555Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40exodus/react-native-fs 原文对照：https://npmcn.com/package/%40exodus/react-native-fs/?lang=original 项目主页：https://github.com/itinance/react-native-fs#readme 源码仓库：https://github.com/itinance/react-native-fs ## 关键信息（来自 npm 元数据） - 包体积（解压后）：109 kB，18 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：react ^16\.2\.0，prop-types ^15\.6\.0，react-native \>=0\.51\.0 \<1\.0\.0 - 首次发布：2019-09-06T06:46:52.085Z - 最新版本发布：2026-04-27T15:17:08.197Z - 近 30 天下载量：16167（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：13（近 12 个月 2 个） ## 中文简介 反应本地文件系统访问 ## 安装 ```sh npm install @exodus/react-native-fs ``` 也可以使用：`pnpm add @exodus/react-native-fs`、`yarn add @exodus/react-native-fs`、`bun add @exodus/react-native-fs` ## README # 反应-内生-fs 反应本地文件系统访问 ## 重要性 对于RN < 0.57和/或Gradle < 3, 您在@2. 11.17版本中安装了反应- native-fs! 对于 RN 0.57 和/或 Gradle 3 您在 QQ @ 2.13.2 版本中安装反应-原生-fs ! ## 更改日志 查看更改日志 [这里](https://github.com/itinance/react-native-fs/blob/master/CHANGELOG.md)。 。 。 . ## 用法(iOS) 首先,您需要安装反应-内生- fs : ``` npm install react-native-fs --save ``` **说明:** 如果您的反应本地版本是 < 0.40 安装此标记: ``` npm install react-native-fs@2.0.1-rc.2 --save ``` 正如@a-koka所指出,您应该更新您的软件包。json 到 `"react-native-fs": "2.0.1-rc.2"` (没有瓦片) ### 自动添加反应- 内在链接 在命令行, 在您的工程文件夹中, 键入 : `react-native link react-native-fs` 没问题! 不需要担心手动将库添加到您的项目中. ### 加入可口可乐池 使用从 Podfile 到已安装模块的路径, 将 RNFS room 添加到您的 Podfile 中的应用 pocket 列表中 :\\\\\\ ``` pod 'RNFS', :path => '../node_modules/react-native-fs' ``` 如常安装吊舱 : ``` pod install ``` ### 在 XCode 中手动添加 在 XCode 中, 在工程导航器中, 右键点击 Library QQ 添加文件到 \[您的工程名\] 转到节点 % 1 反应- native- fs 并添加.xcodeproj 文件 在 XCode 中,在工程导航器中,选择您的项目. 添加数据 `lib*.a` 从RNFS项目到您的项目“构建阶段 + 链接二进制与图书馆”。 单击您在工程导航器中添加的. xcodeproj 文件, 并进入构建设置标签 。 确保“ 全部” 被切换( 而不是“ 基本” ) 。 查找信头搜索路径,并确保其中包含两者 `$(SRCROOT)/../react-native/React` 财务报告和审定财务报表 `$(SRCROOT)/../../React` - 把两者都标为递归性. 运行您的工程( Cmd+R) ## 用法 (Android) (英语) Android支持目前仅限于 `DocumentDirectory`。这张地图到应用程序 `files` 目录. 修改以下文件: - `android/settings.gradle` ```gradle ... include ':react-native-fs' project(':react-native-fs').projectDir = new File(settingsDir, '../node_modules/react-native-fs/android') ``` - `android/app/build.gradle` ```gradle ... dependencies { ... compile project(':react-native-fs') } ``` - 注册模块(主要活动.java) - 对于0.1.9.0以下的反应(使用) `cat ./node_modules/react-native/package.json | grep version`(中文(简体) ) ```java import com.rnfs.RNFSPackage; // <--- import public class MainActivity extends Activity implements DefaultHardwareBackBtnHandler { ...... @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); mReactRootView = new ReactRootView(this); mReactInstanceManager = ReactInstanceManager.builder() .setApplication(getApplication()) .setBundleAssetName("index.android.bundle") .setJSMainModuleName("index.android") .addPackage(new MainReactPackage()) .addPackage(new RNFSPackage()) // <------- add package .setUseDeveloperSupport(BuildConfig.DEBUG) .setInitialLifecycleState(LifecycleState.RESUMED) .build(); mReactRootView.startReactApplication(mReactInstanceManager, "ExampleRN", null); setContentView(mReactRootView); } ...... } ``` - 反应-内在0.19.0及以上 ```java import com.rnfs.RNFSPackage; // <------- add package public class MainActivity extends ReactActivity { // ... @Override protected List getPackages() { return Arrays.asList( new MainReactPackage(), // <---- add comma new RNFSPackage() // <---------- add package ); } ``` - 反应-原生性0.29.0和更高(见MainApplication.java) ```java import com.rnfs.RNFSPackage; // <------- add package public class MainApplication extends Application implements ReactApplication { // ... @Override protected List getPackages() { return Arrays.asList( new MainReactPackage(), // <---- add comma new RNFSPackage() // <---------- add package ); } ``` ## 用法(窗户) ### 自动添加反应- 内在链接 这个 `link` 命令还用于添加对Windows的本地依赖: `react-native link react-native-fs` ### 在视觉工作室手动添加 执行指令 ["链接图书馆"](https://github.com/Microsoft/react-native-windows/blob/master/docs/LinkingLibrariesWindows.md) 关于反应-内存-窗口的文档 GitHub repo。 为将项目添加到Visual Studio解决方案文件中的第一步,项目的路径应该是: `../node_modules/react-native-fs/windows/RNFS/RNFS.csproj`。 。 。 . ## 实例 ### 基础 ```javascript // require the module var RNFS = require('react-native-fs'); // get a list of files and directories in the main bundle RNFS.readDir(RNFS.MainBundlePath) // On Android, use "RNFS.DocumentDirectoryPath" (MainBundlePath is not defined) .then((result) => { console.log('GOT RESULT', result); // stat the first file return Promise.all([RNFS.stat(result[0].path), result[0].path]); }) .then((statResult) => { if (statResult[0].isFile()) { // if we have a file, read it return RNFS.readFile(statResult[1], 'utf8'); } return 'no file'; }) .then((contents) => { // log the file contents console.log(contents); }) .catch((err) => { console.log(err.message, err.code); }); ``` ### 文件创建 ```javascript // require the module var RNFS = require('react-native-fs'); // create a path you want to write to // :warning: on iOS, you cannot write into `RNFS.MainBundlePath`, // but `RNFS.DocumentDirectoryPath` exists on both platforms and is writable var path = RNFS.DocumentDirectoryPath + '/test.txt'; // write the file RNFS.writeFile(path, 'Lorem ipsum dolor sit amet', 'utf8') .then((success) => { console.log('FILE WRITTEN!'); }) .catch((err) => { console.log(err.message); }); ``` ### 文件删除 ```javascript // create a path you want to delete var path = RNFS.DocumentDirectoryPath + '/test.txt'; return RNFS.unlink(path) .then(() => { console.log('FILE DELETED'); }) // `unlink` will throw an error, if the item to unlink does not exist .catch((err) => { console.log(err.message); }); ``` ## API 密码 ### 常数 下列常数可在 `RNFS` 导出 : - `MainBundlePath` (单位:千美元)`String`) 主捆绑目录的绝对路径(Android上没有) - `CachesDirectoryPath` (单位:千美元)`String`缓存目录的绝对路径 - `ExternalCachesDirectoryPath` (单位:千美元)`String`外部缓存目录的绝对路径(仅限机器人) - `DocumentDirectoryPath` (单位:千美元)`String`文档目录的绝对路径 - `DownloadDirectoryPath` (单位:千美元)`String`) 下载目录的绝对路径(仅限于Android) - `TemporaryDirectoryPath` (单位:千美元)`String`) 临时目录的绝对路径(返回Android上的 Caching-Directory) - `LibraryDirectoryPath` (单位:千美元)`String`NSLibrary Directory的绝对路径(仅iOS) - `ExternalDirectoryPath` (单位:千美元)`String`) 外部文件的绝对路径,共享目录(仅限机器人) - `ExternalStorageDirectoryPath` (单位:千美元)`String`) 外部存储的绝对路径,共享目录(仅限机器人) 重要: 当使用 `ExternalStorageDirectoryPath` 需要请求权限(在Android上)在外部存储器上读取并写入,这里有一个实例: \[反应原生外科医生\] ([https://facebook.github.io/resact-native/docs/permissionsandroid 互联网档案馆的存檔,存档日期2014-12-22](https://facebook.github.io/react-native/docs/permissionsandroid)(中文(简体) ) ### `readDir(dirpath: string): Promise` 读取内容 `path`这一定是一条绝对的道路。 使用上述路径常数来形成一个可用的文件路径. 返回的许诺以具有以下属性的一系列对象解决: ``` type ReadDirItem = { ctime: date; // The creation date of the file (iOS only) mtime: date; // The last modified date of the file name: string; // The name of the item path: string; // The absolute path to the item size: string; // Size in bytes isFile: () => boolean; // Is the file just a file? isDirectory: () => boolean; // Is the file a directory? }; ``` ### `readDirAssets(dirpath: string): Promise` 读取内容 `dirpath` 在 Android 应用程序的资产文件夹中. `dirpath` 是文件的相对路径 从根 `assets` 文件夹. 返回的许诺以具有以下属性的一系列对象解决: ``` type ReadDirItem = { name: string; // The name of the item path: string; // The absolute path to the item size: string; // Size in bytes. // Note that the size of files compressed during the creation of the APK (such as JSON files) cannot be determined. // `size` will be set to -1 in this case. isFile: () => boolean; // Is the file just a file? isDirectory: () => boolean; // Is the file a directory? }; ``` 注意:仅限Android. ### `readdir(dirpath: string): Promise` 节点.js 样式版本 `readDir` 仅返回姓名。 注意小写 `d`。 。 。 . ### `stat(filepath: string): Promise` 将项目固定在 `filepath`如果 `filepath` 链接到虚拟文件,例如Android Content URI `originalPath` 可用于找到指向文件路径. 承诺以具有以下属性的对象解决: ``` type StatResult = { path: // The same as filepath argument ctime: date; // The creation date of the file mtime: date; // The last modified date of the file size: string; // Size in bytes mode: number; // UNIX file mode originalFilepath: string; // ANDROID: In case of content uri this is the pointed file path, otherwise is the same as path isFile: () => boolean; // Is the file just a file? isDirectory: () => boolean; // Is the file a directory? }; ``` ### `readFile(filepath: string, encoding?: string): Promise` 读取文件 : `path` 并返回内容. `encoding` 可以成为其中之一 `utf8` (违约), `ascii`, (中文(简体) ), `base64`启用 `base64` 用于读取二进制文件. 注意: 如果您正在读取大文件, 您将会接受相当的性能命中 ### `read(filepath: string, length = 0, position = 0, encodingOrOptions?: any): Promise` 读取 `length` 从给定的字节 `position` 文件编号 `path` 返回内容. `encoding` 可以成为其中之一 `utf8` (违约), `ascii`, (中文(简体) ), `base64`启用 `base64` 用于读取二进制文件. 注意:使用这种方法逐块读取大文件片段可能对性能有用. ### `readFileAssets(filepath:string, encoding?: string): Promise` 读取文件 : `path` android app中的资产文件夹和返回内容. `encoding` 可以成为其中之一 `utf8` (违约), `ascii`, (中文(简体) ), `base64`启用 `base64` 用于读取二进制文件. `filepath` 是文件的相对路径 从根 `assets` 文件夹. 注意:仅限Android. ### `readFileRes(filename:string, encoding?: string): Promise` 读取名为文件的文件 `filename` android app的再文件夹和返回内容. `res/drawable` 用作图像文件的父文件夹, `res/raw` 为了其他一切. `encoding` 可以成为其中之一 `utf8` (违约), `ascii`, (中文(简体) ), `base64`启用 `base64` 用于读取二进制文件. 注意:仅限Android. ### `writeFile(filepath: string, contents: string, encoding?: string): Promise` 写 `contents` 改为 `filepath`。 。 。 . `encoding` 可以成为其中之一 `utf8` (违约), `ascii`, (中文(简体) ), `base64`。 。 。 . `options` 可选择地取一个指定文件属性的对象,如模式等. ### `appendFile(filepath: string, contents: string, encoding?: string): Promise` 附录 `contents` 改为 `filepath`。 。 。 . `encoding` 可以成为其中之一 `utf8` (违约), `ascii`, (中文(简体) ), `base64`。 。 。 . ### `write(filepath: string, contents: string, position?: number, encoding?: string): Promise` 写 `contents` 改为 `filepath` 在给定的随机访问位置。 何时 `position` 实值 `undefined` 或者说 `-1` 内容附于文件末尾. `encoding` 可以成为其中之一 `utf8` (违约), `ascii`, (中文(简体) ), `base64`。 。 。 . ### `moveFile(filepath: string, destPath: string): Promise` 移动位于 `filepath` 改为 `destPath`。这比读取并重写文件数据更能表现,因为移动是本土进行的,数据不必被复制或跨越桥. ### `copyFile(filepath: string, destPath: string): Promise` 复制位于 `filepath` 改为 `destPath`。 。 。 . 注意: 在 Android 副本上File 将覆盖 `destPath` 如果它已经存在。 在 iOS 上, 如果文件已经存在, 则会出现错误 . ### `copyFileAssets(filepath: string, destPath: string): Promise` 复制文件到 `filepath` 在Android应用程序的资产文件夹中复制到给定的 `destPath` 路径. 注意:仅限Android. 如果已存在, 将会覆盖 destPath . ### `copyFileRes(filename: string, destPath: string): Promise` 复制名为文件的文件 `filename` 在Android应用程序的再文件夹中复制到给定的 `destPath` 路径. `res/drawable` 用作图像文件的源父文件夹, `res/raw` 为了其他一切. 注意:仅限Android. 如果已存在, 将会覆盖 destPath . ### `copyAssetsFileIOS(imageUri: string, destPath: string, width: number, height: number, scale : number = 1.0, compression : number = 1.0, resizeMode : string = 'contain' ): Promise` iOS-只:从相机-滚动复制一个文件,它被前缀为"资产-library://asset/asset.JPG?" 前往特定目的地 必要时将从iCloud下载原件. 如果宽度和高度大于0,图像会调整为特定的大小和特定的压缩速率. 如果比例低于1,则图像将根据比例因素(从0.0到1.0之间)进行缩放 改型模型也被考虑. _视频支持:_ 人们也可以使用这种方法从特定大小的视频中创建缩略图Nail. 目前无法具体确定具体立场,由监督办决定 拇指,你会得到. 要从资产图书馆复制一盘视频并保存为mp4-文件,请参考复制AssetsVideoIOS. 详情: [https://developer.apple.com/ reference/photos/phimagemanager/1616964-requestimageforasset 页面存档备份,存于互联网档案馆](https://developer.apple.com/reference/photos/phimagemanager/1616964-requestimageforasset) 承诺一旦成功,将返回文件的最终去向,如DestPath参数所定义的那样. ### 复制 Assets VideoIOS( videoUri: 字符串, destPath: 字符串): 承诺 iOS-只:复制来自资产-图书馆的视频,其前缀为"资产-library://asset/asset.MOV?" 前往特定目的地. ### `unlink(filepath: string): Promise` 取消链接项 : `filepath`。如果项目不存在,则会丢出一个错误. 还递归删除目录( Linux 等工作) `rm -rf`) (中文(简体) ). ### `exists(filepath: string): Promise` 检查项目是否存在于 `filepath`。如果物品不存在,则返回虚假. ### `existsAssets(filepath: string): Promise` 请检查access-date=中的日期值 (帮助) Android 资产文件夹中是否有此项目 . `filepath` 是资产文件夹根的相对路径。 如果物品不存在,则返回虚假. 注意:仅限Android. ### `existsRes(filename: string): Promise` 请检查Android 重新文件夹中是否有命名的项目 `filename` 已存在. `res/drawable` 用作图像文件的父文件夹, `res/raw` 为了其他一切 如果物品不存在,则返回虚假. 注意:仅限Android. ### `hash(filepath: string, algorithm: string): Promise` 读取文件 : `path` 并返回由 `algorithm`,这可以是其中之一 `md5`, (中文(简体) ), `sha1`, (中文(简体) ), `sha224`, (中文(简体) ), `sha256`, (中文(简体) ), `sha384`, (中文(简体) ), `sha512`。 。 。 . ### `touch(filepath: string, mtime?: Date, ctime?: Date): Promise` 设置修改时间戳 `mtime` 和创建时间戳 `ctime` 文件编号 `filepath`设置 `ctime` 仅支持在iOS上,而roid总是设置两个时间戳到 `mtime`。 。 。 . ### `mkdir(filepath: string, options?: MkdirOptions): Promise` ``` type MkdirOptions = { NSURLIsExcludedFromBackupKey?: boolean; // iOS only }; ``` 创建目录于 `filepath`。自动创建父母,如果已经存在,则不丢(像 Linux 这样的工作) `mkdir -p`) (中文(简体) ). (仅IOS): `NSURLIsExcludedFromBackupKey` 属性可以提供,以在iOS平台上设置此属性. 苹果会 _拒绝_ 用于存储没有此属性的离线缓存数据的应用程序 . ### `getFSInfo(): Promise` 返回具有以下属性的对象: ``` type FSInfoResult = { totalSpace: number; // The total amount of storage space on the device (in bytes). freeSpace: number; // The amount of available storage space on the device (in bytes). }; ``` ### (仅限机器人) `scanFile(path: string): Promise` 使用 [媒体扫描器](https://developer.android.com/reference/android/media/MediaScannerConnection)。 。 。 . ### (仅限机器人) `getAllExternalFilesDirs(): Promise` 返回所有共享/外部存储设备上应用程序专用目录的绝对路径的数组,应用程序可以放置它拥有的持久性文件. ### (仅iOS) `pathForGroup(groupIdentifier: string): Promise` `groupIdentifier` (单位:千美元)`string`来自 _com.apple.security. 应用程序组_ 权利清单. 返回所有应用的共享目录的绝对路径,其安全组标识符相同. 此目录可用于在同一开发者的应用程序之间共享文件. 无效的组标识符将导致拒绝 . 更多信息改为: [将 App 添加到 App 组](https://developer.apple.com/library/content/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW19) 节. ## 测试/ Demo 应用程序 测试应用来淡化模块的使用. 可用于测试和发展该模块: [https://github.com/cjdell/ react-native-fs-test 页面存档备份,存于互联网档案馆](https://github.com/cjdell/react-native-fs-test) ## 常见问题 ### @exodus/react-native-fs 是什么？ 反应本地文件系统访问 ### 如何安装 @exodus/react-native-fs？ 在项目目录运行 npm install @exodus/react-native-fs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16\.2\.0）、prop-types（^15\.6\.0）、react-native（\>=0\.51\.0 \<1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @exodus/react-native-fs 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @exodus/react-native-fs 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @exodus/react-native-fs 可以商用吗？ @exodus/react-native-fs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @exodus/react-native-fs 的下载量有多少？ 根据 npm 官方下载统计，@exodus/react-native-fs 在 2026/10/14 – 2026/11/12 这 30 天内被下载 16,167 次，日均约 539 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @exodus/react-native-fs 还在维护吗？ 最新版本 2\.23\.0-exodus\.0 发布于 2026/04/27（6 个月前）；至今共发布 13 个版本，其中过去 12 个月发布了 2 个；首次发布于 2019/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。