Node.js 文件系统：fs 模块常用 API 速查手册¶

在 Node.js 中，文件系统（File System）是处理文件读取、写入、目录管理等操作的核心模块。fs 模块提供了丰富的 API，让我们能在代码中直接操控磁盘文件。本文将整理初学者最常用的 fs API，用简单易懂的示例帮助你快速上手。

一、基础概念：同步 vs 异步¶

fs 模块的 API 分为同步和异步两种风格：
- 同步方法（如 readFileSync、writeFileSync）：代码执行会阻塞等待操作完成，类似“一步一步执行”。适合简单脚本或调试，但可能导致程序卡顿（尤其处理大文件时）。
- 异步方法（如 readFile、writeFile）：代码非阻塞，操作完成后通过回调函数或 Promise 处理结果。适合高并发场景，需处理异步流程（如错误、结果）。

二、常用 API 速查¶

1. 读取文件：fs.readFile（异步）¶

用途：异步读取文件内容。
语法：fs.readFile(path[, options], callback)
- path：文件路径（相对或绝对路径）。
- options：可选，指定编码（如 'utf8'），默认返回 Buffer（二进制数据）。
- callback：回调函数，参数为 (err, data)，err 为错误信息，data 为文件内容（字符串或 Buffer）。

示例（读取文本文件）：

const fs = require('fs');

fs.readFile('./example.txt', 'utf8', (err, data) => {
  if (err) { // 错误处理：文件不存在或权限不足时触发
    console.error('读取失败：', err);
    return;
  }
  console.log('文件内容：', data); // 成功时输出文件内容
});

同步版本：fs.readFileSync(path[, options])（直接返回内容，错误抛异常）

try {
  const data = fs.readFileSync('./example.txt', 'utf8');
  console.log('同步读取：', data);
} catch (err) {
  console.error('同步读取失败：', err);
}

2. 写入文件：fs.writeFile（异步）¶

用途：异步写入内容到文件（文件不存在时会自动创建，存在时会覆盖）。
语法：fs.writeFile(path, data[, options], callback)
- path：目标文件路径。
- data：要写入的内容（字符串或 Buffer）。
- options：编码等配置。
- callback：回调函数，参数为 (err)，无返回值时表示写入成功。

示例（写入文本内容）：

const fs = require('fs');
const content = 'Hello, Node.js!';

fs.writeFile('./output.txt', content, 'utf8', (err) => {
  if (err) {
    console.error('写入失败：', err);
    return;
  }
  console.log('文件写入成功！');
});

同步版本：fs.writeFileSync(path, data[, options])（直接返回，错误抛异常）

try {
  fs.writeFileSync('./output.txt', '同步写入的内容', 'utf8');
  console.log('同步写入成功！');
} catch (err) {
  console.error('同步写入失败：', err);
}

3. 创建目录：fs.mkdir（异步）¶

用途：创建目录（文件夹）。
语法：fs.mkdir(path[, options], callback)
- path：目录路径。
- options：可选，recursive: true 表示递归创建多层目录（如 mkdir('a/b/c') 需 recursive: true）。
- callback：回调函数，参数为 (err)。

示例（创建单级目录）：

const fs = require('fs');

// 创建单级目录（不存在父目录时会报错，需加 recursive: true）
fs.mkdir('./new-dir', (err) => {
  if (err) {
    console.error('创建失败：', err);
    return;
  }
  console.log('目录创建成功！');
});

递归创建多级目录：

// 创建嵌套目录 'a/b/c'
fs.mkdir('./a/b/c', { recursive: true }, (err) => {
  if (err) console.error(err);
  else console.log('递归目录创建成功！');
});

4. 删除文件/目录：fs.unlink（删文件）/ fs.rmdir（删目录）¶

• 删除文件：fs.unlink(path, callback)
  示例：

  fs.unlink('./output.txt', (err) => {
    if (err) console.error('删除文件失败：', err);
    else console.log('文件已删除！');
  });

• 删除空目录：fs.rmdir(path, callback)
  示例：

  fs.rmdir('./new-dir', (err) => {
    if (err) console.error('删除目录失败：', err);
    else console.log('空目录已删除！');
  });

注意：删除非空目录需用 fs.rm（Node.js 14+），并指定 recursive: true：

// 递归删除目录（包含内容）
fs.rm('./a', { recursive: true }, (err) => {
  if (err) console.error(err);
  else console.log('非空目录已删除！');
});

5. 读取目录：fs.readdir（异步）¶

用途：列出目录下的所有文件和子目录。
语法：fs.readdir(path, callback)
- path：目录路径。
- callback：回调函数，参数为 (err, files)，files 是文件/目录名称数组。

示例：

fs.readdir('./', (err, files) => {
  if (err) {
    console.error('读取目录失败：', err);
    return;
  }
  console.log('目录内容：', files); // 输出当前目录下的文件列表
});

6. 获取文件信息：fs.stat（异步）¶

用途：获取文件/目录的元数据（大小、修改时间等）。
语法：fs.stat(path, callback)
- path：文件/目录路径。
- callback：回调函数，参数为 (err, stats)，stats 是包含文件信息的对象。

常用 stats 属性：
- stats.isFile()：是否为文件（true/false）
- stats.isDirectory()：是否为目录
- stats.size：文件大小（字节）
- stats.mtime：最后修改时间

示例：

fs.stat('./example.txt', (err, stats) => {
  if (err) {
    console.error('获取信息失败：', err);
    return;
  }
  console.log('是否为目录：', stats.isDirectory());
  console.log('文件大小：', stats.size, '字节');
  console.log('最后修改时间：', stats.mtime);
});

7. 检查文件是否存在：fs.existsSync（同步）¶

用途：快速判断文件/目录是否存在（仅同步方法，异步用 fs.access 或 fs.stat）。
语法：fs.existsSync(path)
- path：路径。
- 返回值：true（存在）或 false（不存在）。

示例：

const path = './example.txt';
if (fs.existsSync(path)) {
  console.log('文件存在！');
} else {
  console.log('文件不存在！');
}

三、进阶技巧与注意事项¶

1. 路径处理：避免直接拼接字符串，用 path 模块更安全。

   const path = require('path');
   const fullPath = path.join(__dirname, 'data', 'file.txt'); // 拼接路径（__dirname 是当前文件所在目录）

2. 异步错误处理：必须在回调中检查 err，否则程序可能因未处理的错误崩溃。

3. 性能优化：大文件读写建议用流（Stream） 而非一次性加载（如 fs.createReadStream），避免内存占用过高。

4. 权限问题：文件操作需确保 Node.js 进程有对应权限（如读取/写入/执行权限）。

四、总结¶

fs 模块是 Node.js 处理文件的核心工具，掌握上述 API 可满足绝大多数基础需求。从简单的“读写文本文件”到“递归创建目录”，灵活运用同步/异步方法，并注意错误处理和路径安全，就能高效完成文件系统相关开发。

更多高级场景（如流处理、管道、文件锁等）可后续深入学习，本文为你提供快速入门的“速查手册”。