异常教程

Node.js 文件系统（手把手讲解）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

在现代 Web 开发中，Node.js 因其高效的异步非阻塞特性，成为构建高性能服务器和工具链的首选技术之一。而文件系统操作作为 Node.js 的核心能力之一，是开发者必须掌握的基础技能。无论是处理用户上传的文件、管理日志记录，还是构建文件管理工具，Node.js 文件系统模块（fs）都扮演着关键角色。本文将从基础概念到进阶实践，结合代码示例，帮助读者系统性地理解这一重要功能模块。

一、Node.js 文件系统基础概念

1.1 同步与异步操作

文件系统操作本质上是与磁盘的交互过程，而磁盘访问速度远慢于 CPU 运算。为了提升性能，Node.js 提供了两种操作模式：

  • 同步操作：执行时会阻塞代码的后续执行，直到操作完成。
  • 异步操作：通过回调函数或 Promise 实现非阻塞，允许代码在等待磁盘响应时继续执行其他任务。

比喻：同步操作如同在餐厅点餐后必须等待上菜才能继续点其他菜，而异步操作则像外卖服务——下单后可继续做其他事情，收到通知后再处理。

1.2 核心模块：fs 和 fs/promises

Node.js 的文件系统功能主要通过两个模块实现：

  • fs 模块：提供基于回调函数的 API。
  • fs/promises 模块：基于 ES6 Promise 的现代化 API，推荐在新项目中使用。
特性fs 模块fs/promises 模块
调用方式回调函数async/await 或 .then()
代码可读性较低（嵌套回调）高（避免回调地狱）
推荐使用场景兼容旧项目新项目或需异步/await 的场景

二、核心 API 详解

2.1 文件读写操作

2.1.1 读取文件

异步读取：

const fs = require('fs');  
fs.readFile('example.txt', 'utf8', (err, data) => {  
  if (err) throw err;  
  console.log(data); // 输出文件内容  
});

同步读取：

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

注意：同步操作适合小型文件或无需高频交互的场景，大规模文件处理应优先选择异步。

2.1.2 写入文件

异步写入会覆盖原有内容，若需追加内容，需指定 flag 参数：

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

// 追加模式  
fs.appendFile('output.txt', ' 附加内容', (err) => {  
  // ...  
});

2.2 目录操作

2.2.1 创建目录

创建单层目录：

fs.mkdir('newDir', (err) => {  
  if (err) throw err;  
});

递归创建多级目录（如 a/b/c）：

fs.mkdir('a/b/c', { recursive: true }, (err) => {  
  // ...  
});

2.2.2 删除目录

删除空目录：

fs.rmdir('newDir', (err) => {  
  // ...  
});

删除非空目录需配合 fs.rm 或递归删除文件：

fs.rm('a/b/c', { recursive: true, force: true }, (err) => {  
  // ...  
});

2.3 文件信息查询

获取文件或目录的元数据（如大小、修改时间）：

fs.stat('example.txt', (err, stats) => {  
  if (err) throw err;  
  console.log(stats.size);      // 文件大小（字节）  
  console.log(stats.isFile());  // 判断是否为文件  
  console.log(stats.isDirectory()); // 判断是否为目录  
});

三、进阶用法与最佳实践

3.1 流处理大文件

直接读取大文件可能导致内存溢出，此时应使用 流（Stream）：

const fs = require('fs');  
const readStream = fs.createReadStream('large_file.txt');  
readStream.on('data', (chunk) => {  
  console.log(`收到 ${chunk.length} 字节数据`);  
});  
readStream.on('end', () => {  
  console.log('文件读取完毕');  
});

流的优势：按需读取数据，避免一次性加载全部内容。

3.2 异步编程与错误处理

结合 async/await 和 fs/promises 实现更优雅的代码结构：

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

async function readAndWriteFile() {  
  try {  
    const data = await fs.readFile('input.txt', 'utf8');  
    await fs.writeFile('output.txt', data.toUpperCase());  
    console.log('文件处理完成');  
  } catch (err) {  
    console.error('操作失败:', err.message);  
  }  
}  

readAndWriteFile();

关键点：

  • 使用 try/catch 捕获异常，避免程序崩溃。
  • 通过 await 确保操作按顺序执行，提升可读性。

四、实际案例：构建简易文件管理器

4.1 需求分析

实现一个命令行工具，支持以下功能：

  1. 创建目录
  2. 递归删除目录
  3. 复制文件

4.2 实现代码

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

// 创建目录  
async function mkdirRecursive(targetPath) {  
  try {  
    await fs.mkdir(targetPath, { recursive: true });  
    console.log(`目录 ${targetPath} 创建成功`);  
  } catch (err) {  
    console.error('创建目录失败:', err.message);  
  }  
}  

// 递归删除目录  
async function rmRecursive(targetPath) {  
  try {  
    await fs.rm(targetPath, { recursive: true, force: true });  
    console.log(`目录 ${targetPath} 已删除`);  
  } catch (err) {  
    console.error('删除目录失败:', err.message);  
  }  
}  

// 复制文件  
async function copyFile(src, dest) {  
  try {  
    await fs.copyFile(src, dest);  
    console.log(`文件 ${src} 已复制到 ${dest}`);  
  } catch (err) {  
    console.error('复制文件失败:', err.message);  
  }  
}  

// 示例调用  
mkdirRecursive('test_dir');  
copyFile('source.txt', 'test_dir/destination.txt');

4.3 扩展思考

  • 可通过命令行参数（如 process.argv）实现交互式操作。
  • 添加文件类型校验或进度提示，提升用户体验。

五、总结与展望

本文系统介绍了 Node.js 文件系统 的核心概念、API 使用方法及实际应用案例。从基础的读写操作到流处理、异步编程，开发者可通过循序渐进的学习路径掌握这一关键能力。随着 Node.js 生态的持续发展，fs/promises 模块的引入和 fs-extra 等第三方库的优化，文件系统操作将更加高效和易用。

对于开发者而言，掌握文件系统不仅是技术基础，更是构建复杂应用（如静态网站生成器、日志分析工具）的必要条件。建议读者通过实践项目巩固知识，并关注 Node.js 官方文档的更新，以应对未来可能出现的新特性。

（全文约 1800 字）

最新发布

查看更多文章