Node.js fs 模块文件读写与 path 路径处理详解

一、为什么 fs 与 path 总是协同出现：相对路径的陷阱

初学者在使用 Node.js 的 fs 模块时，最常遇到的报错就是 ENOENT: no such file or directory。这个错误往往不是因为文件不存在，而是因为开发者直接传入了裸相对路径（例如 fs.readFile('./data.json')）。

在 Node.js 中，fs API 内部解析相对路径时的基准是 当前进程的工作目录（process.cwd()），即终端用户执行 node 命令时所在的路径，而不是当前代码文件物理所在的目录。

解决该问题的通用原则是：在读取随代码发布的模块私有资源时，永远使用模块物理位置作为锚点，配合 path 模块推导为绝对路径。

CommonJS 与 ES Module 的目录锚点获取方式

// 1. CommonJS 环境（直接使用内置全局变量）
const path = require('node:path');
const fs = require('node:fs/promises');

const filePathCJS = path.resolve(__dirname, './config.json');

// 2. ES Module (ESM) 环境
// Node.js 20.11.0+ 支持 import.meta.dirname
import path from 'node:path';
import fs from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

// 兼容全版本 ESM 的通用写法：
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const filePathESM = path.resolve(__dirname, './config.json');

二、path 模块核心路径处理方法与推导逻辑

node:path 模块提供了跨平台的路径正规化与解析工具。核心方法中最容易被混淆的是 path.join() 与 path.resolve()。

1. path.join() 与 path.resolve() 的推导差异

• path.join([...paths])：纯粹的语法级拼接。将所有传入的路径片段按当前系统的分隔符串联起来，并正规化处理其中的 .（当前层）与 ..（上一层）。如果传入的起点是相对路径，返回的结果依然是相对路径。
• path.resolve([...paths])：模拟终端连续执行 cd 的绝对路径推导。处理顺序从右向左，若处理过程中已构建出根路径，则停止左移；如果扫描完所有入参仍未出现绝对根路径，则自动以 process.cwd() 补齐为绝对路径。

2. 常用路径解析辅助工具函数

import path from 'node:path';

const sample = '/var/log/nginx/access.2026.log';

// 提取目录名
path.dirname(sample);  // 输出: '/var/log/nginx'

// 提取完整文件名
path.basename(sample); // 输出: 'access.2026.log'

// 提取文件名并去掉扩展名
path.basename(sample, '.log'); // 输出: 'access.2026'

// 提取扩展名（包含开头的点）
path.extname(sample);  // 输出: '.log'

// 一次性结构化解析
const parsed = path.parse(sample);
/* parsed 对象结构:
{
  root: '/',
  dir: '/var/log/nginx',
  base: 'access.2026.log',
  ext: '.log',
  name: 'access.2026'
}
*/

// 根据对象重新组合路径
path.format(parsed);  // 重新拼接成完整字符串

三、fs 模块文件读写的 3 种方式与选型建议

Node.js 的 fs 模块发展至今形成了三套 API 风格：传统的异步回调（Callback）、同步阻塞（Sync）以及现代基于 Promise 的 fs/promises。此外，针对大文件还提供了专用的流式（Stream）接口。

四、常见文件读写实战场景

场景一：文本与 JSON 文件的安全读取与写入

如果不指定字符编码，fs.readFile() 默认返回原始二进制 Buffer。对于文本与 JSON，应显式传入 'utf-8' 编码。对于 JSON 解析，必须包裹在 try...catch 中，防范非法格式导致整个进程异常退出。

import fs from 'node:fs/promises';
import path from 'node:path';

// 安全读取与反序列化 JSON
async function readJsonConfig(relativeFilePath) {
  const fullPath = path.resolve(__dirname, relativeFilePath);
  try {
    const rawText = await fs.readFile(fullPath, 'utf-8');
    return JSON.parse(rawText);
  } catch (error) {
    if (error.code === 'ENOENT') {
      throw new Error(`配置文件不存在: ${fullPath}`);
    }
    if (error instanceof SyntaxError) {
      throw new Error(`配置文件 JSON 格式错误: ${error.message}`);
    }
    throw error;
  }
}

// 序列化并写入 JSON 文件
async function writeJsonConfig(relativeFilePath, data) {
  const fullPath = path.resolve(__dirname, relativeFilePath);
  const jsonString = JSON.stringify(data, null, 2);
  await fs.writeFile(fullPath, jsonString, 'utf-8');
}

场景二：日志与历史数据的追加写入

若需要向已有文件末尾增加内容，可以使用 fs.appendFile()，或者在 fs.writeFile() 中配置 { flag: 'a' } 标志位。

// 向日志文件追加行
async function appendLog(logLine) {
  const logPath = path.resolve(__dirname, '../logs/app.log');
  const formatted = `[${new Date().toISOString()}] ${logLine}
`;
  await fs.appendFile(logPath, formatted, 'utf-8');
}

场景三：超大文件读写与流式（Stream）管道

当处理几百兆甚至数十吉字节（GB）的日志、音视频或数据转储时，如果使用 fs.readFile()，会将整个文件完整载入 V8 堆内存，极易触发 JavaScript heap out of memory 崩溃。

正确方式是使用 createReadStream、createWriteStream 并借助 Node.js 内置的 node:stream/promises 中的 pipeline 方法，自动调度背压（Backpressure）与异常清理。

import fs from 'node:fs';
import { pipeline } from 'node:stream/promises';
import path from 'node:path';
import zlib from 'node:zlib';

// 示例：流式读取 5GB 日志并实时 gzip 压缩写入新文件
async function compressLargeFile(sourcePath, destZipPath) {
  const sourceStream = fs.createReadStream(sourcePath);
  const gzipStream = zlib.createGzip();
  const destStream = fs.createWriteStream(destZipPath);

  // pipeline 会自动监听 error 并销毁底层所有 stream 句柄，杜绝句柄泄露
  await pipeline(sourceStream, gzipStream, destStream);
  console.log('大文件流式压缩归档完毕，内存恒定保持在 30MB 以内');
}

五、目录操作与文件存在性检查

1. 递归创建多级目录

在写入文件前，必须确保目标文件所在的父目录已经存在。过去开发者习惯先用正则层层判断创建，而在现代 Node.js 中，只需传递 { recursive: true }：

import fs from 'node:fs/promises';
import path from 'node:path';

async function safeWriteFile(targetPath, data) {
  // 提取父级目录路径
  const parentDir = path.dirname(targetPath);

  // 递归确保父目录结构完整（目录已存在时不会抛错，天然幂等）
  await fs.mkdir(parentDir, { recursive: true });

  await fs.writeFile(targetPath, data, 'utf-8');
}

2. 遍历目录内容

使用 fs.readdir() 时，建议开启 { withFileTypes: true }。该选项会返回 Dirent 对象数组，免去再次对每个文件调用 fs.stat() 造成的二次 I/O 开销。

async function listDirectory(dirPath) {
  const entries = await fs.readdir(dirPath, { withFileTypes: true });
  
  for (const entry of entries) {
    if (entry.isDirectory()) {
      console.log(`[目录] ${entry.name}`);
    } else if (entry.isFile()) {
      console.log(`[文件] ${entry.name}`);
    }
  }
}

3. 文件存在性检查的最佳实践

早期 Node.js 提供了 fs.exists()，现已被废弃。原因在于它会引发 TOCTOU（Time-of-check to time-of-use，检查时到使用时竞态条件）：在检查文件存在与实际发起读写之间，另一个并发进程可能已经将文件删除或修改，导致后续操作依然失败。

• 如果你即将对文件进行读写：不要预先检查存在性，直接执行读写，并在 try...catch 中捕获 ENOENT 错误（遵循 Python 的 EAFP 原则：“请求原谅比请求许可更容易”）。
• 仅用来探测文件是否可读或是否存在：使用 fs.promises.access()，配合 fs.constants.F_OK（是否存在）或 fs.constants.R_OK（是否可读）。

import fs from 'node:fs/promises';
import { constants } from 'node:fs';

// 纯探测文件是否存在
async function checkExists(filePath) {
  try {
    await fs.access(filePath, constants.F_OK);
    return true;
  } catch {
    return false;
  }
}

六、生产环境避坑指南与常见错误处理

1. 路径遍历安全漏洞（Path Traversal 防御）

当接口允许用户传入文件名以下载或查看时，攻击者可能传入 ../../../../etc/passwd 越权读取系统机密。必须校验解析后的绝对路径是否超出预期根目录：

function getSafePath(baseDirectory, userInput) {
  // 1. 将用户输入基于安全根目录解析为规范化绝对路径
  const safeTarget = path.resolve(baseDirectory, userInput);

  // 2. 检查解析结果是否依然以根目录为前缀
  if (!safeTarget.startsWith(baseDirectory)) {
    throw new Error('非法访问：检测到越权路径逃逸行为！');
  }

  return safeTarget;
}

2. 并发写入与原子替换（Atomic Write Pattern）

直接向同一文件写入内容时，如果写入过程遭遇断电、服务崩溃或未捕获异常退出，目标文件将被截断，只剩下一半内容导致损坏。

生产环境中对于重要配置或状态数据，推荐使用原子写入模式：先写入带有临时后缀的文件（如 .tmp），在确保完整落盘后再调用 fs.rename()。POSIX 与多数主流文件系统保证了 rename 操作的原子性，即使写入中途崩溃，原有文件依然完好无损。

async function atomicWriteFile(targetPath, content) {
  const tempPath = `${targetPath}.tmp.${Date.now()}`;
  try {
    await fs.writeFile(tempPath, content, 'utf-8');
    await fs.rename(tempPath, targetPath); // 原子替换
  } catch (err) {
    await fs.unlink(tempPath).catch(() => {}); // 清理临时文件
    throw err;
  }
}

3. 常见系统错误码速查

七、总结

Node.js 的文件读写与路径处理是一套高度成熟且严谨的体系：

• 路径锚定先行：切忌直接使用裸相对路径。在模块内始终使用 path.resolve(__dirname, ...) 或 import.meta.dirname 锁定物理相对位置。
• 模式优选异步：在业务主流程中全面使用 node:fs/promises，利用 async/await 配合 try...catch 实现清晰优雅的异常流；同步方法仅用于冷启动加载。
• 大文件托付 Stream：对大于 10MB 或无法预估体积的数据集，始终通过 pipeline 串联只读流与可写流，让背压控制保障系统内存平稳。
• 防御与健壮性：目录创建统一加 { recursive: true }，文件存在性直接读写捕获 ENOENT，外部入参严格验证 startsWith 规避越权逃逸。