Node.js中使用fs模块读取本地文件的代码示例

作者:墨池

时间:2026-11-19

浏览:365

详细讲解在Node.js中如何使用内置fs模块读取本地文件,提供基于Promise的async/await、传统回调、同步读取及流式读取的完整代码示例,涵盖路径解析、字符编码处理与常见系统错误排查指南。

文章目录
Node.js中使用fs模块读取本地文件的代码示例
图 0:Node.js 文件系统 (fs) 模块本地文件读取总体架构图
在 Node.js 中读取本地文件,核心依赖内置的 fs(File System)模块。针对不同使用场景,Node.js 提供了四种实现途径:基于 Promise 的异步读取(fs/promises)、传统回调函数(fs.readFile)、阻塞主线程的同步读取(fs.readFileSync),以及适用于海量数据的流式读取(fs.createReadStream)。本文提供每种读取方式的完整代码示例、执行步骤、字符编码规范与常见错误排查指南。

一、基础准备与文件读取实施步骤

在开始编写代码前,先了解操作流程。Node.js 的 fs 属于内置核心模块,无需通过 npm install 安装,直接导入即可使用。为了确保代码在任何环境下均能稳定运行,标准的文件读取流程分为创建测试文件、导入模块、构建绝对路径以及调用读取 API 四个步骤。

Node.js中使用fs模块读取本地文件的代码示例
图 1:Node.js 本地文件读取标准实施四步流程图

在项目根目录中创建一个用于测试的文本文件 sample.txt,并输入以下两行文本,文件编码确保保存为 UTF-8:

sample.txt (测试数据文件)plaintext
Hello Node.js!
这是本地文件读取的测试内容。

接下来在相同目录下创建执行脚本 read-demo.js,按照以下几种具体方式依次展开实现。

二、基于 Promise 与 async/await 读取文件(现代首选)

自 Node.js 14 版本起,官方正式推荐使用 node:fs/promises 子模块。该模块提供的所有 I/O 方法均返回 Promise 对象,配合 async/await 语法,能够写出既符合非阻塞异步特性、又具备类似同步代码直观逻辑的高可读性代码。

1. 完整代码示例

read-promise.js (CommonJS 规范)javascript
// 引入内置的 fs/promises 与 path 模块
const fs = require('node:fs/promises');
const path = require('node:path');

async function readLocalFile() {
  try {
    // 使用 path.join 构造绝对路径,避免依赖命令行工作目录
    const filePath = path.join(__dirname, 'sample.txt');

    // 显式指定 'utf-8' 编码,直接返回字符串
    const content = await fs.readFile(filePath, 'utf-8');

    console.log('--- 文件读取成功 ---');
    console.log(content);
  } catch (err) {
    // 捕获可能出现的 ENOENT (文件不存在) 等异常
    console.error('读取文件失败,错误原因:', err.message);
  }
}

readLocalFile();

2. 运行命令与示例输出

在终端中进入项目目录并执行:

终端命令bash
node read-promise.js

终端预期输出如下:

示例输出结果stdout
--- 文件读取成功 ---
Hello Node.js!
这是本地文件读取的测试内容。
ES Module 语法支持:如果项目配置为 "type": "module",可以通过 import fs from 'node:fs/promises'; 导入。由于 ES Module 中不存在全局变量 __dirname,需要借助 new URL('.', import.meta.url).pathname 获得当前目录绝对路径。

三、使用传统回调函数读取文件(fs.readFile)

在维护老旧项目或无需引入 async 函数的简单场景下,可以使用经典的 fs.readFile。该方法遵循 Node.js 标志性的“错误优先回调”(Error-first callback)规范,即回调函数的第一个参数永远是错误对象 err,第二个参数是读取成功的数据。

1. 完整代码示例

read-callback.jsjavascript
const fs = require('node:fs');
const path = require('node:path');

const filePath = path.join(__dirname, 'sample.txt');

// 传递第三个参数为回调函数
fs.readFile(filePath, 'utf-8', (err, data) => {
  if (err) {
    console.error('读取文件发生错误:', err.message);
    return;
  }

  console.log('--- 回调读取完成 ---');
  console.log(data);
});

与 Promise 方式相同,该方法在底层的磁盘 I/O 阶段完全由 libuv 线程池接管,不会阻塞 Node.js 主事件循环。但在需要连续读取多个关联文件时,多层嵌套回调极易诱发“回调地狱”(Callback Hell),因此现代项目中新功能优先选用 Promise 方案。

四、使用同步方法读取文件(fs.readFileSync)

fs.readFileSync 会强制暂停 Node.js 的主线程执行,直接向操作系统发起系统调用并同步等待返回结果。在文件内容被全部读取到内存之前,后续的任何 JavaScript 代码都不会被执行。

1. 完整代码示例

read-sync.jsjavascript
const fs = require('node:fs');
const path = require('node:path');

const filePath = path.join(__dirname, 'sample.txt');

try {
  // 同步执行:直接获取返回值,若出错则抛出异常
  const data = fs.readFileSync(filePath, 'utf-8');
  console.log('--- 同步读取结果 ---');
  console.log(data);
} catch (err) {
  console.error('同步读取失败:', err.message);
}
Node.js中使用fs模块读取本地文件的代码示例
图 2:同步阻塞模式 (readFileSync) 与异步非阻塞模式底层运行原理对比
性能警告与适用边界:同步方法会冻结事件循环,若在 Web 服务器(如 Express、Koa、Fastify)的请求处理函数中调用 fs.readFileSync,只要读取稍有耗时,所有其他客户端的网络请求均会被完全挂起。因此,同步方法仅允许用于服务启动阶段初始化配置、解析本地证书,或一次性执行的 CLI 命令行脚本,严禁放入并发业务逻辑中。

五、处理大文件:流式读取(fs.createReadStream)

上述三种方法(readFile、readFileSync、promises.readFile)都有一个共同特征:它们会将文件全量载入内存。当遇到数百兆甚至数吉字节的超大日志文件、视频或压缩包时,全量读取会导致 Node.js 内存占用暴增,甚至直接触发 V8 堆内存溢出(JavaScript heap out of memory)导致进程崩溃。

此时必须采用流式读取(Stream)。fs.createReadStream 按照固定大小的分块(默认每次 64KB)逐段从磁盘拉取数据,以极小且恒定的内存开销平稳处理任意大小的文件。

1. 基于事件监听的流式读取示例

read-stream.jsjavascript
const fs = require('node:fs');
const path = require('node:path');

const filePath = path.join(__dirname, 'sample.txt');

// 创建可读流,可配置 highWaterMark 调整每次读取分块字节数
const readStream = fs.createReadStream(filePath, {
  encoding: 'utf-8',
  highWaterMark: 16 * 1024 // 每次读取 16KB 分块
});

let totalChunks = 0;

// 监听 data 事件:每当一块数据就绪时触发
readStream.on('data', (chunk) => {
  totalChunks++;
  console.log(`[接收分块 ${totalChunks}] 长度: ${chunk.length} 字符`);
  console.log(chunk);
});

// 监听 end 事件:文件全部读取完毕
readStream.on('end', () => {
  console.log('--- 流式传输全部完成,文件读取结束 ---');
});

// 监听 error 事件:捕获读取中途的磁盘或权限错误
readStream.on('error', (err) => {
  console.error('流式读取异常:', err.message);
});
Node.js中使用fs模块读取本地文件的代码示例
图 3:Node.js 本地文件四种读取方式技术选型与多维对比矩阵

六、文件路径规范与常见错误排查

在实际编码中,很多文件读取失败并不是代码语法错误,而是由路径解析机制和编码理解偏差导致的。以下是三条不可忽略的关键排查点:

Node.js中使用fs模块读取本地文件的代码示例
图 4:Node.js 本地文件读取安全规范与常见异常排查指南

1. 路径陷阱:为什么不能直接写相对路径?

在 Node.js 中,如果传递相对路径(如 fs.readFile('./sample.txt')),Node.js 会将该相对路径与当前运行命令的工作目录(即 process.cwd())进行拼接,而不是与当前 JS 脚本所在的物理目录拼接。

这意味着:如果你在根目录执行 node src/utils/reader.js,相对路径 ./sample.txt 会在根目录下查找,导致抛出 ENOENT 错误。标准做法是始终使用 path.join(__dirname, '文件名') 构造可靠的绝对路径。

2. 字符编码:Buffer 与 String 的差异

如果在调用 fs.readFile(filePath) 时省略编码参数,Node.js 默认将文件视为二进制数据,返回一个原始的 Buffer 实例(在控制台打印呈现为十六进制序列 <Buffer 48 65 6c 6c 6f...>)。若需要获取可读文本,必须指定 'utf-8' 编码,或者手动调用 buffer.toString('utf-8') 完成解码。

3. 核心系统错误代码速查

  • ENOENT (Error NO ENTry):最常见的错误,表示给定的文件路径不存在。排查方式:打印 filePath 检查拼写,确认文件是否存在于该物理路径。
  • EACCES (Error ACCESs):权限拒绝错误,表示运行 Node.js 进程的操作系统用户对该文件没有读权限(Read Permission)。排查方式:在 Linux/macOS 下使用 chmod +r 赋予读取权限。
  • EISDIR (Error Is a DIRectory):试图以文件形式读取一个文件夹。排查方式:检查路径末端是否遗漏了文件名。
  • EMFILE (Error Too Many Open Files):进程打开的文件描述符超过了系统上限,通常由于在循环中过快并发打开大量文件且未及时关闭引起。排查方式:引入异步并发池控制读取频率,或使用流式管道。

七、四种读取方式总结对照

读取方式 调用特征 主线程阻塞 内存占用模式 最推荐使用场景
fs/promises.readFile Promise / async-await 否 (libuv 线程池) 全量载入内存 绝大多数后端日常业务、读取 JSON 配置及模板
fs.readFile Error-first 回调 否 (libuv 线程池) 全量载入内存 旧工程兼容维护、单一异步任务
fs.readFileSync 直接返回值 完全阻塞进程 全量载入内存 服务冷启动时加载初始配置、一次性 CLI 脚本
fs.createReadStream Stream / 事件驱动 否 (流式拉取) 分块恒定低占用 超大日志文件、视频音频流、网络传输直通管道

掌握以上四种文件读取方式,在处理本地文本、数据解析及高并发场景时便能准确权衡性能与内存开销,编写出健壮、可靠的 Node.js 应用程序。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章