Node.js中使用fs模块读取本地文件的代码示例
详细讲解在Node.js中如何使用内置fs模块读取本地文件,提供基于Promise的async/await、传统回调、同步读取及流式读取的完整代码示例,涵盖路径解析、字符编码处理与常见系统错误排查指南。
fs(File System)模块。针对不同使用场景,Node.js 提供了四种实现途径:基于 Promise 的异步读取(fs/promises)、传统回调函数(fs.readFile)、阻塞主线程的同步读取(fs.readFileSync),以及适用于海量数据的流式读取(fs.createReadStream)。本文提供每种读取方式的完整代码示例、执行步骤、字符编码规范与常见错误排查指南。
一、基础准备与文件读取实施步骤
在开始编写代码前,先了解操作流程。Node.js 的 fs 属于内置核心模块,无需通过 npm install 安装,直接导入即可使用。为了确保代码在任何环境下均能稳定运行,标准的文件读取流程分为创建测试文件、导入模块、构建绝对路径以及调用读取 API 四个步骤。
在项目根目录中创建一个用于测试的文本文件 sample.txt,并输入以下两行文本,文件编码确保保存为 UTF-8:
Hello Node.js!
这是本地文件读取的测试内容。
接下来在相同目录下创建执行脚本 read-demo.js,按照以下几种具体方式依次展开实现。
二、基于 Promise 与 async/await 读取文件(现代首选)
自 Node.js 14 版本起,官方正式推荐使用 node:fs/promises 子模块。该模块提供的所有 I/O 方法均返回 Promise 对象,配合 async/await 语法,能够写出既符合非阻塞异步特性、又具备类似同步代码直观逻辑的高可读性代码。
1. 完整代码示例
// 引入内置的 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. 运行命令与示例输出
在终端中进入项目目录并执行:
node read-promise.js
终端预期输出如下:
--- 文件读取成功 ---
Hello Node.js!
这是本地文件读取的测试内容。
"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. 完整代码示例
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. 完整代码示例
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);
}
fs.readFileSync,只要读取稍有耗时,所有其他客户端的网络请求均会被完全挂起。因此,同步方法仅允许用于服务启动阶段初始化配置、解析本地证书,或一次性执行的 CLI 命令行脚本,严禁放入并发业务逻辑中。
五、处理大文件:流式读取(fs.createReadStream)
上述三种方法(readFile、readFileSync、promises.readFile)都有一个共同特征:它们会将文件全量载入内存。当遇到数百兆甚至数吉字节的超大日志文件、视频或压缩包时,全量读取会导致 Node.js 内存占用暴增,甚至直接触发 V8 堆内存溢出(JavaScript heap out of memory)导致进程崩溃。
此时必须采用流式读取(Stream)。fs.createReadStream 按照固定大小的分块(默认每次 64KB)逐段从磁盘拉取数据,以极小且恒定的内存开销平稳处理任意大小的文件。
1. 基于事件监听的流式读取示例
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);
});
六、文件路径规范与常见错误排查
在实际编码中,很多文件读取失败并不是代码语法错误,而是由路径解析机制和编码理解偏差导致的。以下是三条不可忽略的关键排查点:
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 应用程序。
CVE-2026-123864 解决方案:Node.js HTTPS 重入内存泄露的原理、检测与代码级修复
2026-11-18 19:04:42
JS调用exe时处理路径空格与参数转义
2026-11-18 18:09:23
Go 后端升级 Google GenAI SDK 1.78.0 如何保留测试接口?
2026-11-18 13:31:29
JS读写文件出现中文乱码怎么办
2026-11-17 19:11:19
为什么浏览器端JavaScript不能直接连接数据库
2026-11-17 08:18:29








