Node.js / 系统课时

读取文本文件

读取文本文件

读取文本文件时,真正需要决定的是:是否允许阻塞事件循环、文件路径按哪里解析,以及结果要字符串还是 Buffer。本课用同一个文件跑通同步、回调和 Promise 三种读取方式,并给出路径、编码、错误处理和大文件场景的选择标准。

学习目标

  • 能区分 readFileSync、回调版 readFile 与 fs/promises.readFile 的执行特征。
  • 能用 utf8 和模块相对路径稳定读取文本,并识别常见文件错误。
  • 能判断什么时候应改用流,而不是一次性把整个文件读入内存。

三种读取方式如何选

三种 API 都能读取完整文件,但对事件循环的影响不同。同步读取会等文件读完才继续执行 JavaScript,因此更适合启动阶段的小配置或一次性 CLI 脚本;服务请求处理中优先使用异步 API。

方式 API 执行特征 适合场景
同步 readFileSync 当前 JavaScript 线程等待读取完成 启动时读取几 KB 配置、短脚本
回调 readFile 读取完成后调用回调 已采用 Node 回调风格的旧代码
Promise node:fs/promises 的 readFile 可直接配合 await 新项目、需要串联多个异步步骤

如果一次磁盘读取耗时 200 ms,同步版本会让同一 Node.js 进程中的其他 JavaScript 也等待这 200 ms。HTTP 服务里不要把 readFileSync 放进每次请求都会执行的处理函数。

用一个文件跑通三种读取方式

下面示例按 Node.js 18+ 的 ESM 写法编写,文件名保存为 read-text.mjs 后直接运行。为保证示例可独立执行,代码会先创建 note.txt,再按同步、回调、Promise 的顺序读取它。

js
import { readFile, readFileSync, writeFileSync } from 'node:fs';
import { readFile as readFilePromise } from 'node:fs/promises';

const file = new URL('./note.txt', import.meta.url);

// 示例自包含:先生成一个确定内容的 UTF-8 文本文件。
writeFileSync(file, '第一行\n第二行\n', 'utf8');

const syncText = readFileSync(file, 'utf8');
console.log('同步:', syncText.trim());

await new Promise((resolve, reject) => {
  readFile(file, 'utf8', (error, text) => {
    // 回调 API 必须先处理错误,再使用读取结果。
    if (error) {
      reject(error);
      return;
    }
    console.log('回调:', text.trim());
    resolve();
  });
});

// Promise API 便于用 await 明确控制异步步骤的先后顺序。
const promiseText = await readFilePromise(file, 'utf8');
console.log('Promise:', promiseText.trim());

预期输出

text
同步: 第一行
第二行
回调: 第一行
第二行
Promise: 第一行
第二行

三次结果相同,差别主要在调用方式和是否阻塞。同步版直接返回字符串;回调版通过第二个参数拿结果;Promise 版由 await 得到结果。

编码、路径与错误怎么处理

读取文本时显式传入 utf8。如果省略编码,readFile 和 readFileSync 返回的是 Buffer,适合图片、压缩包等二进制数据,但文本还要再解码。普通 JSON、Markdown、日志等 UTF-8 文件直接传 'utf8' 最清楚。

路径也要先约定基准。字符串 './note.txt' 按 process.cwd() 解析,用户从另一个目录启动 CLI 时可能出现 ENOENT;new URL('./note.txt', import.meta.url) 则始终相对当前模块,适合需要随脚本一起发布的模板和配置。

文件不存在时不要先用“检查存在,再读取”的两步逻辑,因为两步之间文件仍可能被删除。直接读取并处理异常更可靠:error.code === 'ENOENT' 表示路径不存在,EACCES 通常表示当前进程没有足够权限。对可选配置可以在 ENOENT 时使用默认值,对必需配置则应让启动失败并打印实际路径。

大文件不要一次性全部读取

readFile 会把文件整体读入内存。读取 2 KB 配置或 200 KB 模板通常很合适,但 500 MB 日志会带来数百 MB 级内存占用,转成字符串时峰值还可能继续增加。日志分析、逐行导入等场景应改用 createReadStream 或 readline。

项目里可以设置一个明确的评审阈值,例如“预计文件超过 20 MB 时必须说明为什么不用流”;这不是 Node.js 的硬限制,而是防止把不断增长的日志误写成一次性读取。同步 API 还应额外限制在启动或离线脚本阶段,避免把磁盘延迟带进在线请求。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

读取文本文件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通