fs-extra API 全量文档（基于 v11+）

fs-extra 是 Node.js 文件系统的增强版本，提供了异步与同步方法，覆盖了常规 fs 模块的所有功能，并添加了许多高级实用工具方法。

安装教程

使用 npm 安装：

npm install fs-extra

如果你使用的是 TypeScript，fs-extra 已经内置了类型定义，从 v9 起不再需要安装 @types/fs-extra：

✅ 无需再安装 @types/fs-extra，除非使用的是 v8 或更早版本。

使用 pnpm 安装：

pnpm add fs-extra

使用 yarn 安装：

yarn add fs-extra

以下是根据官网文档提供的 API 全量整理，包括参数说明和示例代码。

📁 Async 异步 API

1. copy(src, dest, [options])

复制文件或目录

参数	类型	说明
src	string	源路径
dest	string	目标路径
options	object	可选，支持 overwrite, errorOnExist 等

import fs from 'fs-extra';
await fs.copy('src/file.txt', 'dest/file.txt');

2. emptyDir(dir)

清空一个目录，若目录不存在则创建它

参数	类型	说明
dir	string	目录路径

await fs.emptyDir('/tmp/my-folder');

3. ensureFile(file)

确保文件存在，如不存在则创建

参数	类型	说明
file	string	文件路径

await fs.ensureFile('./logs/debug.log');

4. ensureDir(dir) / mkdirp(dir) / mkdirs(dir)

确保目录存在，如不存在则创建

参数	类型	说明
dir	string	目录路径

await fs.ensureDir('./data/output');

5. ensureLink(src, dest)

创建硬链接，若目标已存在则跳过

参数	类型	说明
src	string	源文件路径
dest	string	链接路径

await fs.ensureLink('file.txt', 'linked-file.txt');

6. ensureSymlink(src, dest, [type])

创建符号链接

参数	类型	说明
src	string	源路径
dest	string	链接路径
type	string	可选：file、dir，平台相关行为

await fs.ensureSymlink('source-dir', 'link-to-dir');

7. move(src, dest, [options])

移动文件或目录

参数	类型	说明
src	string	源路径
dest	string	目标路径
options	object	可选：overwrite、clobber

await fs.move('./temp/file.txt', './dest/file.txt');

8. outputFile(file, data)

写入文件（自动创建目录）

参数	类型	说明
file	string	文件路径
data	any	写入的数据内容

await fs.outputFile('./out/logs/debug.log', 'Debug info');

9. outputJson(file, obj, [options])

写入 JSON 文件（自动创建目录）

参数	类型	说明
file	string	文件路径
obj	object	要写入的 JSON 对象
options	object	可选：缩进、编码等

await fs.outputJson('./data/config.json', { debug: true });

10. pathExists(path)

判断路径是否存在（等价于 fs.exists）

参数	类型	说明
path	string	路径

if (await fs.pathExists('./config.json')) {
  console.log('配置文件存在');
}

11. readJson(file, [options])

读取并解析 JSON 文件

参数	类型	说明
file	string	文件路径
options	object	可选，编码等

const config = await fs.readJson('./data/config.json');

12. remove(path)

删除文件或目录（递归）

参数	类型	说明
path	string	路径

await fs.remove('./old/output');

13. writeJson(file, obj, [options])

写入 JSON 数据（不自动创建目录）

参数	类型	说明
file	string	文件路径
obj	object	要写入的 JSON 对象
options	object	可选，缩进、编码等

await fs.writeJson('./config.json', { debug: false }, { spaces: 2 });

---

🧩 Sync 同步 API（同名 + Sync 后缀）

这些方法与异步版本完全一致，只是同步执行：

fs.copySync(src, dest);
fs.emptyDirSync(dir);
fs.ensureFileSync(file);
fs.ensureDirSync(dir);
fs.ensureLinkSync(src, dest);
fs.ensureSymlinkSync(src, dest);
fs.mkdirpSync(dir);
fs.mkdirsSync(dir);
fs.moveSync(src, dest);
fs.outputFileSync(file, data);
fs.outputJsonSync(file, obj);
fs.pathExistsSync(path);
fs.readJsonSync(file);
fs.removeSync(path);
fs.writeJsonSync(file, obj);

注意：同步方法不推荐在高并发生产环境中使用，建议仅用于脚本或初始化流程中。

---