fs-extra vs graceful-fs vs memfs vs fs
Node.js 文件系统操作:原生模块与增强方案的架构选型
fs-extragraceful-fsmemfsfs类似的npm包:

Node.js 文件系统操作:原生模块与增强方案的架构选型

fs 是 Node.js 内置的核心模块,提供标准的文件系统 API,是所有文件操作的基础。fs-extra 在 fs 的基础上进行了扩展,增加了如 copy、move、remove 等实用方法,并默认支持 Promise,旨在提升开发效率。graceful-fs 专注于解决文件描述符耗尽和 EMFILE 错误,通过内部排队机制增强系统的稳定性,常作为底层依赖被其他工具隐式使用。memfs 则提供了一个完全在内存中运行的文件系统实现,接口与 fs 兼容,主要用于单元测试、模拟环境或需要极速读写且无需持久化的场景。

npm下载趋势

3 年

GitHub Stars 排名

统计详情

npm包名称
下载量
Stars
大小
Issues
发布时间
License
fs-extra229,712,0299,59059.9 kB1621 天前MIT
graceful-fs212,183,3791,30032.5 kB494 年前ISC
memfs39,967,5942,10673.7 kB5014 天前Apache-2.0
fs1,514,272164-510 年前ISC

Node.js 文件系统操作:原生模块与增强方案的架构选型

在 Node.js 生态中,文件操作是构建工具、后端服务和测试框架的基石。虽然 fs 模块提供了基础能力,但在面对复杂工程场景时,开发者往往需要在效率、稳定性和隔离性之间做出权衡。本文将深入对比 fs、fs-extra、graceful-fs 和 memfs,帮助你根据实际架构需求做出精准选择。

🏗️ 核心定位与设计哲学

这四个包虽然都处理“文件”,但解决的问题层面完全不同。

fs 是 Node.js 的内置核心模块。它的设计哲学是“最小化”和“标准化”,只提供操作系统文件 API 的直接映射。它不依赖任何外部库,是其他所有文件操作库的基石。

fs-extra 的设计目标是“开发者体验”。它在 fs 的基础上增加了大量高频使用的实用方法(如递归复制、移动文件),并强制默认支持 Promise,解决了原生 API 在异步编程中的繁琐问题。

graceful-fs 专注于“系统稳定性”。它不增加新功能,而是修补了原生 fs 在处理高并发文件打开时的缺陷,防止因文件描述符耗尽导致进程崩溃。

memfs 则是“虚拟化”的代表。它用 JavaScript 在内存中模拟了一套完整的文件系统接口,旨在解耦代码与物理磁盘,为测试和特殊运行环境提供可能。

📝 基础 API 与 Promise 支持对比

在处理简单的文件读取时,各包的差异主要体现在代码的简洁性和异步风格上。

fs 原生支持回调和 Promise 两种风格,但使用 Promise 需要显式引入 fs/promises 子模块(在较新版本中)或使用 util.promisify。

// fs: 需要显式引入 promises 子模块
const fs = require('fs/promises');

async function readConfig() {
  try {
    const data = await fs.readFile('./config.json', 'utf8');
    return JSON.parse(data);
  } catch (err) {
    console.error('读取失败', err);
  }
}

fs-extra 默认导出即包含 Promise 支持,且 API 与 fs 完全兼容,可以直接替换。

// fs-extra: 默认支持 Promise,API 更简洁
const fse = require('fs-extra');

async function readConfig() {
  // 无需额外导入,直接 await
  const data = await fse.readFile('./config.json', 'utf8');
  return JSON.parse(data);
}

graceful-fs 的 API 与 fs 完全一致,主要用于打补丁(Monkey Patching),通常不直接编写业务逻辑调用它,而是让它拦截 fs 的调用。

// graceful-fs: 通常用于全局增强
const gracefulFs = require('graceful-fs');
// 将 fs 模块替换为增强版,后续所有 require('fs') 都会自动生效
gracefulFs.globalMonkeys(); 

// 现在使用普通的 fs 也具备了容错能力
const fs = require('fs'); 

memfs 提供了与 fs 相同的接口,但需要显式实例化一个虚拟卷(Volume)。

// memfs: 需要创建虚拟卷实例
const { Volume } = require('memfs');
const vol = new Volume();

// 初始化虚拟文件
vol.fromJSON({ '/hello.txt': 'World' });

async function readVirtual() {
  // 使用 vol.promises 或直接回调
  const data = await vol.promises.readFile('/hello.txt', 'utf8');
  console.log(data); // 输出: World
}

🛠️ 高级操作:递归复制与清理

在实际工程中,递归操作目录是最常见的需求之一。原生 fs 在旧版本中对此支持不佳,而增强库则提供了原生的一站式解决方案。

fs 在 Node.js 14.14+ 引入了 recursive: true 选项用于 mkdir 和 rm,但在 copyFile 上依然不支持递归复制目录,需要手动遍历实现。

// fs: 递归删除已支持,但复制目录仍需手动递归
const fs = require('fs/promises');

// 递归删除
await fs.rm('./dist', { recursive: true, force: true });

// 复制目录:原生无单行方法,需自行编写递归逻辑或使用 cp (Node 16.7+)
// await fs.cp('./src', './dist', { recursive: true }); // 仅限非常新的版本

fs-extra 早在多年前就提供了 copy、move 和 remove 方法,完美支持递归,且语义清晰。

// fs-extra: 一行代码完成递归复制和清理
const fse = require('fs-extra');

// 递归复制整个目录,自动创建目标文件夹
await fse.copy('./src/assets', './dist/assets');

// 递归删除目录
await fse.remove('./temp');

// 移动文件(跨分区也能处理)
await fse.move('./old_log.txt', './archive/log.txt');

graceful-fs 不提供高级操作方法,它依赖底层的 fs。如果原生 fs 不支持递归复制,它也不支持。它的价值在于执行这些耗时操作时不会因打开文件过多而崩溃。

memfs 支持类似的高级操作,但仅限于其虚拟卷内部。这对于测试复杂的文件生成逻辑非常有用。

// memfs: 在内存中模拟递归操作
const { Volume } = require('memfs');
const vol = new Volume();

vol.fromJSON({
  '/src/a.js': 'code A',
  '/src/b.js': 'code B'
});

// 在内存中递归复制
await vol.promises.cp('/src', '/dist', { recursive: true });

// 验证结果
console.log(vol.toJSON()); 
// 输出: { '/src/a.js': 'code A', ... '/dist/a.js': 'code A' ... }

🚦 稳定性与容错机制

当应用需要同时处理数千个文件时,操作系统的文件描述符限制(ulimit)会成为瓶颈。这是 graceful-fs 存在的唯一理由,也是它与其它包最大的区别。

fs 在遇到 EMFILE(打开文件太多)错误时会直接抛出异常,导致进程终止。开发者必须手动实现重试队列逻辑,这非常复杂且容易出错。

// fs: 遇到高并发直接崩溃
// 假设同时打开 1025 个文件,而限制是 1024
const promises = files.map(f => fs.readFile(f));
// Promise.all(promises) 可能会因为 EMFILE 错误而整体 Reject

graceful-fs 内部维护了一个队列。当遇到 EMFILE 错误时,它不会立即报错,而是将请求挂起,等待其他文件关闭后再自动重试。这对上层代码完全透明。

// graceful-fs: 自动排队,平滑处理高并发
const gracefulFs = require('graceful-fs');
// 激活全局补丁
gracefulFs.globalMonkeys();

const fs = require('fs');
// 即使 files 数组有一万个文件,也不会崩溃,只会变慢
const promises = files.map(f => fs.readFile(f));
await Promise.all(promises); 

fs-extra 本身不处理 EMFILE,但它官方推荐并经常将 graceful-fs 作为依赖。如果你使用较新版本的 fs-extra,它可能已经自动集成了这种稳定性保障,但显式依赖 graceful-fs 仍是大型工具的最佳实践。

memfs 运行在内存中,完全不受操作系统文件描述符限制的影响。它可以轻松创建百万级文件用于压力测试,这是物理文件系统无法做到的。

// memfs: 无系统限制,适合极端压力测试
const { Volume } = require('memfs');
const vol = new Volume();

// 瞬间创建 10 万个文件,不会触发 EMFILE
for (let i = 0; i < 100000; i++) {
  vol.writeFileSync(`/file-${i}.txt', 'data');
}

🧪 测试与隔离场景

在单元测试中,读写真实磁盘会导致测试变慢、产生副作用(需要清理垃圾文件)以及难以模拟错误情况。

fs, fs-extra, 和 graceful-fs 默认都操作真实磁盘。在测试中使用它们需要配合 tmp 库创建临时目录,并在 afterEach 中清理,流程繁琐且有风险。

// 传统测试:需要手动清理
const fs = require('fs-extra');
const tmp = require('tmp');

const dir = tmp.dirSync();
try {
  await fs.writeFile(dir.name + '/test.txt', 'hello');
  // ... 测试逻辑
} finally {
  dir.removeCallback(); // 必须确保清理
}

memfs 彻底解决了这个问题。它提供一个完全隔离的环境,测试结束后内存自动释放,无需清理。还可以轻松模拟“磁盘已满”等罕见错误。

// memfs: 纯净的测试环境
const { Volume } = require('memfs');
const { createFsFromVolume } = require('memfs');

const vol = new Volume();
const fs = createFsFromVolume(vol);

// 模拟文件系统错误
vol.throwError = () => { throw new Error('ENOSPC: no space left on device'); };

// 测试逻辑完全隔离,不影响本地磁盘
await fs.promises.writeFile('/app/data.json', '{"id": 1}');
const content = await fs.promises.readFile('/app/data.json', 'utf8');
expect(content).toBe('{"id": 1}');

// 测试结束,vol 丢弃即可,无残留

📊 选型总结

特性fs (原生)fs-extragraceful-fsmemfs
主要用途基础文件操作高效开发、工具链高并发稳定性测试、模拟、内存盘
Promise 支持需引入子模块默认支持同原生支持 (via vol.promises)
递归复制/移动有限支持 (依赖版本)完美支持依赖底层实现支持
EMFILE 容错❌ 无⚠️ 依赖是否捆绑✅ 核心功能✅ 无此限制
磁盘 IO✅ 真实磁盘✅ 真实磁盘✅ 真实磁盘❌ 纯内存
典型场景简单脚本、极致精简CLI 工具、构建脚本打包工具、爬虫单元测试、沙箱

💡 架构师建议

在现代 Node.js 开发中,fs-extra 几乎应该成为默认选择。它消除了原生 API 的许多痛点,带来的微小依赖成本远低于其提升的开发效率和代码可读性。对于大多数业务后端和工具库,直接使用 fs-extra 是最稳妥的方案。

然而,如果你正在开发像 Webpack、Vite 或 Gulp 这样的构建工具,或者需要处理海量文件的数据管道,请务必显式引入 graceful-fs 并确保它被正确应用(通常通过 globalMonkeys 或作为底层依赖)。在这种场景下,稳定性高于一切,EMFILE 错误是生产环境的隐形杀手。

最后,不要在你的生产业务代码中直接使用 memfs 来替代真实存储,除非你明确知道自己在构建一个纯内存的应用(如 Redis 替代品)。它的核心价值在于测试。将 memfs 引入你的测试套件,可以显著加快测试运行速度,并让你能够自信地模拟各种极端的文件系统错误,这是操作真实磁盘无法比拟的优势。

如何选择: fs-extra vs graceful-fs vs memfs vs fs

  • fs-extra:

    如果你的项目涉及大量的文件复制、移动、递归删除或 JSON 文件读写,fs-extra 是最佳选择。它完美替代了 fs,提供了更人性化的 API 和原生的 Promise 支持,能显著减少样板代码。它是构建工具、CLI 工具和后端服务中的事实标准,特别适合需要快速开发且对少量额外依赖不敏感的场景。

  • graceful-fs:

    当你开发的是可能同时处理成千上万个文件的工具(如打包工具、爬虫或大规模数据处理脚本)时,必须考虑引入 graceful-fs。它主要用于防止因打开文件过多导致的 EMFILE 崩溃。通常你不需要直接调用它的 API,而是通过 require('graceful-fs').globalMonkeys() 或直接让其他库(如 fs-extra)依赖它来在底层自动生效,以确保应用在极端负载下的鲁棒性。

  • memfs:

    当你在编写单元测试、需要模拟文件系统行为,或者开发一个完全在内存中运行的高性能临时数据处理服务时,选择 memfs。它允许你在不触碰真实磁盘的情况下测试文件逻辑,极大地加快了测试速度并避免了清理临时文件的麻烦。它也常用于浏览器环境模拟 Node.js API,或在 CI/CD 流程中创建隔离的沙箱环境。

  • fs:

    当你只需要最基础的文件读写功能,且希望保持项目零依赖时,选择原生的 fs 模块。它适合对包体积敏感的生产环境,或者当你需要严格控制异步/回调风格而不需要 Promise 封装的场景。注意,原生 fs 不包含高级工具方法(如递归删除),实现复杂逻辑时需编写更多样板代码。

fs-extra的README

Node.js: fs-extra

fs-extra adds file system methods that aren't included in the native fs module and adds promise support to the fs methods. It also uses graceful-fs to prevent EMFILE errors. It should be a drop in replacement for fs.

npm Package License build status downloads per month JavaScript Style Guide

Why?

I got tired of including mkdirp, rimraf, and ncp in most of my projects.

Installation

npm install fs-extra

Usage

CommonJS

fs-extra is a drop in replacement for native fs. All methods in fs are attached to fs-extra. All fs methods return promises if the callback isn't passed.

You don't ever need to include the original fs module again:

const fs = require('fs') // this is no longer necessary

you can now do this:

const fs = require('fs-extra')

or if you prefer to make it clear that you're using fs-extra and not fs, you may want to name your fs variable fse like so:

const fse = require('fs-extra')

you can also keep both, but it's redundant:

const fs = require('fs')
const fse = require('fs-extra')

NOTE: The deprecated constants fs.F_OK, fs.R_OK, fs.W_OK, & fs.X_OK are not exported on Node.js v24.0.0+; please use their fs.constants equivalents.

ESM

There is also an fs-extra/esm import, that supports both default and named exports. However, note that fs methods are not included in fs-extra/esm; you still need to import fs and/or fs/promises separately:

import { readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { outputFile, outputFileSync } from 'fs-extra/esm'

Default exports are supported:

import fs from 'fs'
import fse from 'fs-extra/esm'
// fse.readFileSync is not a function; must use fs.readFileSync

but you probably want to just use regular fs-extra instead of fs-extra/esm for default exports:

import fs from 'fs-extra'
// both fs and fs-extra methods are defined

Sync vs Async vs Async/Await

Most methods are async by default. All async methods will return a promise if the callback isn't passed.

Sync methods on the other hand will throw if an error occurs.

Also Async/Await will throw an error if one occurs.

Example:

const fs = require('fs-extra')

// Async with promises:
fs.copy('/tmp/myfile', '/tmp/mynewfile')
  .then(() => console.log('success!'))
  .catch(err => console.error(err))

// Async with callbacks:
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
  if (err) return console.error(err)
  console.log('success!')
})

// Sync:
try {
  fs.copySync('/tmp/myfile', '/tmp/mynewfile')
  console.log('success!')
} catch (err) {
  console.error(err)
}

// Async/Await:
async function copyFiles () {
  try {
    await fs.copy('/tmp/myfile', '/tmp/mynewfile')
    console.log('success!')
  } catch (err) {
    console.error(err)
  }
}

copyFiles()

Methods

Async

Sync

NOTE: You can still use the native Node.js methods. They are promisified and copied over to fs-extra. See notes on fs.read(), fs.write(), & fs.writev()

What happened to walk() and walkSync()?

They were removed from fs-extra in v2.0.0. If you need the functionality, walk and walkSync are available as separate packages, klaw and klaw-sync.

Third Party

CLI

fse-cli allows you to run fs-extra from a console or from npm scripts.

TypeScript

If you like TypeScript, you can use fs-extra with it: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/fs-extra

File / Directory Watching

If you want to watch for changes to files or directories, then you should use chokidar.

Obtain Filesystem (Devices, Partitions) Information

fs-filesystem allows you to read the state of the filesystem of the host on which it is run. It returns information about both the devices and the partitions (volumes) of the system.

Misc.

Hacking on fs-extra

Wanna hack on fs-extra? Great! Your help is needed! fs-extra is one of the most depended upon Node.js packages. This project uses JavaScript Standard Style - if the name or style choices bother you, you're gonna have to get over it :) If standard is good enough for npm, it's good enough for fs-extra.

js-standard-style

What's needed?

  • First, take a look at existing issues. Those are probably going to be where the priority lies.
  • More tests for edge cases. Specifically on different platforms. There can never be enough tests.
  • Improve test coverage.

Note: If you make any big changes, you should definitely file an issue for discussion first.

Running the Test Suite

fs-extra contains hundreds of tests.

  • npm run lint: runs the linter (standard)
  • npm run unit: runs the unit tests
  • npm run unit-esm: runs tests for fs-extra/esm exports
  • npm test: runs the linter and all tests

When running unit tests, set the environment variable CROSS_DEVICE_PATH to the absolute path of an empty directory on another device (like a thumb drive) to enable cross-device move tests.

Windows

If you run the tests on the Windows and receive a lot of symbolic link EPERM permission errors, it's because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7 However, I didn't have much luck doing this.

Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows. I open the Node.js command prompt and run as Administrator. I then map the network drive running the following command:

net use z: "\\vmware-host\Shared Folders"

I can then navigate to my fs-extra directory and run the tests.

Naming

I put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:

First, I believe that in as many cases as possible, the Node.js naming schemes should be chosen. However, there are problems with the Node.js own naming schemes.

For example, fs.readFile() and fs.readdir(): the F is capitalized in File and the d is not capitalized in dir. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: fs.mkdir(), fs.rmdir(), fs.chown(), etc.

We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: cp, cp -r, mkdir -p, and rm -rf?

My perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too.

So, if you want to remove a file or a directory regardless of whether it has contents, just call fs.remove(path). If you want to copy a file or a directory whether it has contents, just call fs.copy(source, destination). If you want to create a directory regardless of whether its parent directories exist, just call fs.mkdirs(path) or fs.mkdirp(path).

Credit

fs-extra wouldn't be possible without using the modules from the following authors:

License

Licensed under MIT

Copyright (c) 2011-2024 JP Richardson