适用读者：所有 Node.js 开发者，特别是那些需要处理文件、构建工具、或开发后端服务的工程师
目标：深入理解 Node.js 文件系统的工作机制，掌握其核心 API，并能编写出高效、健壮的文件处理代码

---

1. fs 模块：Node.js 的 I/O 核心

Node.js 的 fs (File System) 模块是用于与文件系统进行交互的内置模块。无论是读取配置文件、写入日志、处理用户上传的图片，还是构建一个静态资源服务器，都离不开它。
fs 模块的设计深刻体现了 Node.js 的异步、非阻塞 I/O哲学，同时也提供了同步方法以适应特定场景。

2. 核心抉择：同步 vs. 异步

这是使用 fs 模块时最重要的一个决策点。

2.1 异步方法

• 特点：非阻塞。发起 I/O 操作后，立即返回，操作在后台完成。结果通过回调函数、Promise 或 async/await 获取。
• 优势：不会阻塞事件循环，非常适合处理网络请求等高并发场景。
• 命名：方法名通常不带后缀，如 fs.readFile()。

2.2 同步方法

• 特点：阻塞。发起 I/O 操作后，会等待操作完成才返回后续代码。
• 劣势：会完全阻塞事件循环，导致整个 Node.js 进程在此期间无法处理任何其他任务。
• 命名：方法名通常带 Sync 后缀，如 fs.readFileSync()。
  执行流程对比图：

黄金法则：

除非有绝对充分的理由（如启动时读取配置文件），否则永远不要在生产环境的 Web 服务器中使用同步 I/O 方法。

---

3. 现代用法：拥抱 fs.promises

Node.js 从 v10 开始，提供了基于 Promise 的 API，通过 require('fs').promises 访问。这使得异步文件操作可以与 async/await 完美结合，代码更加清晰、易读。

3.1 读取文件

const fs = require('fs').promises;
const path = require('path');
async function readConfig() {
  try {
    const filePath = path.join(__dirname, 'config.json');
    const data = await fs.readFile(filePath, 'utf8');
    const config = JSON.parse(data);
    console.log('Config loaded:', config);
  } catch (error) {
    console.error('Failed to read config file:', error);
  }
}
readConfig();

3.2 写入文件

const fs = require('fs').promises;
async function saveReport(report) {
  try {
    const content = JSON.stringify(report, null, 2);
    await fs.writeFile('report.json', content, 'utf8');
    console.log('Report saved successfully.');
  } catch (error) {
    console.error('Failed to save report:', error);
  }
}
saveReport({ date: new Date(), status: 'success' });

---

4. 高级实战：流式处理大文件

当处理大文件（如视频、大型日志文件）时，fs.readFile() 会尝试将整个文件读入内存。这可能导致内存溢出。流 是解决这个问题的正确方案。
流将数据分块处理，而不是一次性加载全部。

4.1 实战：高效的文件复制器

const fs = require('fs');
const readable = fs.createReadStream('large-video.mp4');
const writable = fs.createWriteStream('copy-of-large-video.mp4');
readable.on('error', (err) => {
  console.error('Read error:', err);
});
writable.on('error', (err) => {
  console.error('Write error:', err);
});
writable.on('finish', () => {
  console.log('File copied successfully!');
});
// .pipe() 是实现流式传输的精髓
readable.pipe(writable);

流的管道机制图：

---

5. 文件系统元数据与操作

除了读写文件内容，fs 模块还提供了丰富的 API 来操作文件和目录本身。

5.1 检查文件状态

const fs = require('fs').promises;
async function checkFile(filePath) {
  try {
    const stats = await fs.stat(filePath);
    console.log(`Is a file? ${stats.isFile()}`);
    console.log(`Is a directory? ${stats.isDirectory()}`);
    console.log(`Size: ${stats.size} bytes`);
    console.log(`Created: ${stats.birthtime}`);
    console.log(`Modified: ${stats.mtime}`);
  } catch (err) {
    console.error('Error checking file:', err);
  }
}
checkFile(__filename);

5.2 目录操作

const fs = require('fs').promises;
const path = require('path');
async function manageDirectory() {
  const dirPath = path.join(__dirname, 'new-directory');
  try {
    // 创建目录
    await fs.mkdir(dirPath, { recursive: true });
    console.log('Directory created.');
    // 读取目录内容
    const files = await fs.readdir(__dirname);
    console.log('Files in current dir:', files);
    // 删除目录
    await fs.rmdir(dirPath);
    console.log('Directory removed.');
  } catch (err) {
    console.error('Directory operation failed:', err);
  }
}
manageDirectory();

---

6. 实战：构建一个简单的静态文件服务器

结合 http 和 fs 模块，我们可以轻松创建一个静态文件服务器。

const http = require('http');
const fs = require('fs').promises;
const path = require('path');
const publicDir = path.join(__dirname, 'public');
const server = http.createServer(async (req, res) => {
  // 安全处理：防止路径遍历攻击
  const filePath = path.join(publicDir, req.url === '/' ? 'index.html' : req.url);
  
  try {
    const data = await fs.readFile(filePath);
    const ext = path.extname(filePath);
    const contentType = getContentType(ext);
    res.writeHead(200, { 'Content-Type': contentType });
    res.end(data);
  } catch (error) {
    // 如果文件不存在，返回 404
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('404 Not Found');
  }
});
function getContentType(ext) {
  const types = {
    '.html': 'text/html',
    '.css': 'text/css',
    '.js': 'application/javascript',
    '.png': 'image/png',
    '.jpg': 'image/jpeg',
  };
  return types[ext] || 'application/octet-stream';
}
server.listen(3000, () => {
  console.log('Static server running on http://localhost:3000');
});

---

7. 总结与最佳实践

7.1 关键概念回顾

• 异步 I/O 是 Node.js 的核心，应优先使用。
• fs.promises 与 async/await 是现代 Node.js 的最佳实践。
• 流 是处理大文件、避免内存溢出的不二法门。
• fs.stat() 用于获取文件元数据，fs.mkdir()/fs.readdir() 用于目录操作。
• 路径安全：始终使用 path.join() 来构建路径，防止路径遍历攻击。

7.2 fs 模块使用最佳实践清单

• ✅ 默认使用 fs.promises：让你的异步代码更简洁。
• ✅ 处理大文件必用流：用 createReadStream 和 createWriteStream + .pipe()。
• ✅ 谨慎使用同步方法：只在启动脚本或命令行工具中使用。
• ✅ 处理错误：所有文件操作都可能失败（如权限不足、文件不存在），必须用 try/catch 或回调的错误参数来处理。
• ✅ 使用 path.join()：构建跨平台兼容的路径，并确保安全性。

7.3 进阶学习路径

1. fs.watch() 和 fs.watchFile()：学习如何监听文件或目录的变化，用于实现热重载或自动构建。
2. Worker Threads：对于 CPU 密集型的文件处理（如图片压缩），可以结合 Worker Threads 来避免阻塞主线程。
3. 文件锁：在多进程环境中，学习如何使用 proper-lockfile 等库来确保对文件的并发访问是安全的。
4. 探索底层：了解 fs 模块是如何通过 libuv 与操作系统的文件系统 API 交互的。

7.4 资源推荐

• Node.js 官方文档：File System
• Node.js 官方文档：Path
• 书籍：Node.js Design Patterns (Chapter on Caching and Time-based Events)
  最终建议：文件系统是几乎所有后端应用的基石。从简单的配置读取到复杂的媒体处理，fs 模块提供了你所需要的一切工具。掌握它，意味着你能够构建出功能更强大、性能更卓越的应用。记住，选择正确的 I/O 模式（同步/异步/流）是区分新手和专家的关键标志。