fs-extra

fs-extra 在原生 node:fs 的基础上增加了递归复制、确保目录存在、读写 JSON 等高层操作；它也可作为 fs 的替代导入。

Node.js 已原生提供 fs/promises、mkdir({ recursive: true })、cp() 和 rm()。只有需要统一、简洁的高层文件操作，或维护既有项目时，再引入 fs-extra。

安装与导入

pnpm add fs-extra

import fs from 'fs-extra'

fs-extra/esm 只导出扩展方法；若使用该入口，原生 fs 方法仍需从 node:fs 或 node:fs/promises 导入。

常用操作

import fs from 'fs-extra'

await fs.ensureDir('dist/assets')
await fs.copy('public', 'dist/public', { overwrite: true })
await fs.outputJson('dist/meta.json', { builtAt: new Date().toISOString() }, { spaces: 2 })

const exists = await fs.pathExists('dist/meta.json')
if (exists) {
  const meta = await fs.readJson('dist/meta.json')
  console.log(meta.builtAt)
}

常用扩展方法：

• ensureDir()、ensureFile()：确保目录或文件存在。
• copy()、move()、remove()：递归复制、移动和删除。
• emptyDir()：清空目录但保留目录本身。
• outputFile()、outputJson()：自动创建父目录后写入文件或 JSON。
• readJson()、writeJson()：读写 JSON。

异步方法未传回调时返回 Promise；同步版本以 Sync 结尾，失败时会阻塞事件循环并抛出异常，应只用于启动阶段或一次性脚本。

注意事项

• pathExists() 适合简单判断；“检查后再操作”不能避免并发竞态，应直接执行目标操作并处理 ENOENT、EEXIST 等错误。
• remove() 会递归删除目标路径。对用户输入路径应先校验其是否位于允许目录内。