Node.js 中的 fs 模块详解：文件系统操作全掌握

目录

一、前言

[二、fs 模块的引入方式](#二、fs 模块的引入方式)

[三、常用 API 分类整理](#三、常用 API 分类整理)

[1. 读取文件](#1. 读取文件)

[2. 写入文件](#2. 写入文件)

[四、使用 Promise 风格的 fs/promises](#四、使用 Promise 风格的 fs/promises)

五、实战案例：日志记录器

[六、同步 vs 异步：如何选择？](#六、同步 vs 异步：如何选择？)

七、总结

---

一、前言

在 Node.js 中，fs 模块（即 File System）是一个非常核心的模块，用于与本地文件系统进行交互。你可以通过它来读写文件、创建目录、修改文件权限等操作。

本篇博客将带你系统性地了解 fs 模块的常用方法、同步与异步差异，以及实际应用场景中的示例代码，助你轻松掌握 Node.js 文件系统操作。

二、fs 模块的引入方式

Node.js 的 fs 模块是内置模块，可以直接使用 require 引入：

const fs = require('fs');

从 Node.js v14 开始，官方也推荐使用基于 Promise 的 fs/promises：

const fs = require('fs/promises');

三、常用 API 分类整理

1. 读取文件

异步读取文件

fs.readFile('example.txt', 'utf8', (err, data) => {
  if (err) {
    console.error('读取失败:', err);
    return;
  }
  console.log('文件内容:', data);
});

同步读取文件

const data = fs.readFileSync('example.txt', 'utf8');
console.log(data);

2. 写入文件

异步写入

fs.writeFile('output.txt', 'Hello, Node.js!', (err) => {
  if (err) throw err;
  console.log('写入成功');
});

同步写入

fs.writeFileSync('output.txt', 'Hello, Node.js!');

3. 追加内容到文件末尾

fs.appendFile('log.txt', '追加的内容\n', (err) => {
  if (err) throw err;
  console.log('内容已追加');
});

4. 检查文件或目录是否存在

fs.access('example.txt', fs.constants.F_OK, (err) => {
  console.log(err ? '文件不存在' : '文件存在');
});

建议不要使用 fs.exists，已被弃用。

5. 创建和删除目录

fs.mkdir('newDir', { recursive: true }, (err) => {
  if (err) throw err;
  console.log('目录已创建');
});

fs.rmdir('newDir', (err) => {
  if (err) throw err;
  console.log('目录已删除');
});

6. 读取目录内容

fs.readdir('./', (err, files) => {
  if (err) throw err;
  console.log('当前目录下的文件:', files);
});

7. 删除文件

fs.unlink('output.txt', (err) => {
  if (err) throw err;
  console.log('文件已删除');
});

四、使用 Promise 风格的 fs/promises

如果你更倾向于使用 async/await 风格，推荐使用 fs/promises：

const fs = require('fs/promises');

async function readFileAsync() {
  try {
    const data = await fs.readFile('example.txt', 'utf8');
    console.log(data);
  } catch (err) {
    console.error('读取失败:', err);
  }
}

readFileAsync();

五、实战案例：日志记录器

我们实现一个简单的日志写入函数，每次运行程序时都记录当前时间：

const fs = require('fs');
const path = require('path');

function logMessage(message) {
  const timestamp = new Date().toISOString();
  const log = `[${timestamp}] ${message}\n`;
  const logPath = path.join(__dirname, 'app.log');

  fs.appendFile(logPath, log, (err) => {
    if (err) console.error('日志写入失败:', err);
  });
}

// 使用
logMessage('程序启动');

六、同步 vs 异步：如何选择？

使用场景	推荐方式
快速原型/脚本	同步方法
高性能生产环境	异步方法
异步流程控制	fs/promises 与 async/await

一般来说，如果你在构建 Web 服务或 CLI 工具，建议使用异步方式以避免阻塞事件循环。

七、总结

• fs 模块提供了丰富的 API 来进行文件和目录的操作；

• 同步方法简单，但会阻塞主线程；

• 异步方法性能更好，适合实际开发；

• fs/promises 让异步代码更清晰可维护；

• 掌握这些方法可以让你在 Node.js 中轻松处理各种文件操作任务。