Node.js 文件系统操作：fs vs fs-extra vs fs-extra-promise

在 Node.js 开发中，文件系统（File System）操作是基础但关键的能力。fs、fs-extra 和 fs-extra-promise 三个包都用于处理文件读写、目录管理等任务，但它们在 API 设计、异步支持和开发体验上有显著差异。本文将从工程实践角度深入比较三者，帮助你做出合理的技术选型。

📁 基础能力：核心 API 对比

fs 是 Node.js 内置模块，提供最原始的文件系统操作接口。它同时支持回调风格和 Promise 风格（通过 fs.promises 子模块）。

// fs: 回调风格
const fs = require('fs');
fs.readFile('file.txt', 'utf8', (err, data) => {
  if (err) throw err;
  console.log(data);
});

// fs: Promise 风格（Node.js 10+）
const { promises: fsp } = require('fs');
async function read() {
  const data = await fsp.readFile('file.txt', 'utf8');
  console.log(data);
}

fs-extra 在 fs 基础上扩展了大量实用方法（如 copy, remove, ensureDir 等），并原生支持 Promise，无需额外导入子模块。

// fs-extra: 原生 Promise 支持
const fse = require('fs-extra');
async function copyAndRead() {
  await fse.copy('src', 'dest');
  const data = await fse.readFile('dest/file.txt', 'utf8');
  console.log(data);
}

fs-extra-promise 曾经是对 fs-extra 的简单封装，为其添加 Promise 支持。但根据其 npm 页面 和 GitHub 仓库信息，该包已被官方标记为废弃（deprecated），不再维护。作者明确建议直接使用 fs-extra，因为后者已内置完整的 Promise 支持。

⚠️ 重要提示：fs-extra-promise 不应再用于新项目。继续使用它会引入不必要的依赖，并可能错过 fs-extra 的安全更新和性能改进。

🔄 异步模型：Promise 支持方式

• fs：需显式使用 fs.promises 才能获得 Promise API。若直接使用 fs.readFile 等方法，返回的是回调风格，容易导致“回调地狱”或需要手动 util.promisify。

// fs: 需要区分使用方式
const fs = require('fs');
const fsp = fs.promises; // 必须这样用才能获得 Promise

// 错误示例：fs.readFile 不返回 Promise
// const data = await fs.readFile('file.txt'); // TypeError!

• fs-extra：所有方法默认返回 Promise，同时保留回调风格（通过可选的 callback 参数）。这种设计兼顾了向后兼容性和现代开发习惯。

// fs-extra: 统一的 Promise-first API
const fse = require('fs-extra');

// Promise 风格
await fse.ensureDir('tmp');

// 也支持回调（但不推荐）
fse.ensureDir('tmp', (err) => { /*...*/ });

• fs-extra-promise：作为历史产物，其 Promise 封装已被上游吸收。使用它相当于多了一层无意义的包装，且无法享受 fs-extra 后续新增的功能（如 move、emptyDir 等）。

🛠️ 实用功能：超越基础 I/O

fs 仅提供 POSIX 标准的文件操作，而 fs-extra 添加了大量开发者日常需要的高级功能：

// fs-extra: 高级功能示例
const fse = require('fs-extra');

// 一键创建嵌套目录
await fse.ensureDir('project/src/utils');

// 安全复制整个目录
await fse.copy('old-project', 'new-project');

// 读写 JSON 无需手动 parse/stringify
await fse.writeJson('config.json', { port: 3000 });
const config = await fse.readJson('config.json');

相比之下，fs 要实现类似功能需组合多个低级操作，代码冗长且易错。例如，递归删除目录需手动遍历文件树；复制目录需递归创建目标路径并逐个复制文件。

🧪 错误处理与类型安全

• fs：错误通过回调的第一个参数或 Promise reject 传递，符合 Node.js 标准。但缺乏对常见场景的优化（如“文件不存在”需手动检查 err.code === 'ENOENT'）。

• fs-extra：继承 fs 的错误模型，但部分方法提供更友好的行为。例如 ensureDir 在目录已存在时不会报错，而 fs.mkdir 会抛出 EEXIST。

• fs-extra-promise：错误处理与 fs-extra 相同，但由于已废弃，无法获得后续改进。

此外，fs-extra 提供了完善的 TypeScript 类型定义，而 fs 作为内置模块也有良好支持。fs-extra-promise 的类型定义则可能滞后或缺失。

📦 依赖与维护性

• fs：零依赖，随 Node.js 运行时自带，版本与 Node.js 绑定。
• fs-extra：轻量级（仅依赖少数工具函数），积极维护，定期发布新版本修复问题和增加功能。
• fs-extra-promise：已废弃，最后更新于 2016 年，存在安全风险且无社区支持。

🆚 总结：如何选择？

最佳实践建议

1. 永远优先考虑 fs-extra：除非你有严格的零依赖要求，否则 fs-extra 的开发效率提升远超其微小的体积成本。
2. 避免混合使用：在一个项目中统一使用 fs-extra 或 fs.promises，不要混用回调和 Promise 风格。
3. 迁移旧代码：如果项目仍在使用 fs-extra-promise，应尽快替换为 fs-extra，只需修改 import 语句即可（API 完全兼容）。

// 迁移示例：从 fs-extra-promise 到 fs-extra
// 旧代码
// const fse = require('fs-extra-promise');

// 新代码
const fse = require('fs-extra'); // 其他代码无需改动

💡 结语

fs 是基石，fs-extra 是现代化的增强版，而 fs-extra-promise 已成为历史。对于专业前端开发者（尤其是涉及 Node.js 工具链开发时），fs-extra 应作为默认选择——它用极小的成本换取了巨大的开发体验提升和代码健壮性。记住：不要为已解决的问题重复造轮子，更不要使用已被废弃的解决方案。