fs/promises:异步文件操作与 API 选择
🎯 引言
学完这篇文章,你能使用 await 组织文件操作顺序,并处理异步读取失败。
🧱 选择文件 API:异步处理日常任务
node:fs/promises 提供返回 Promise 的文件操作,适合使用你熟悉的 await 组织读取和写入。文件操作等待期间,Node.js 可以处理其他就绪任务;这与 readFileSync 等同步方法让当前 JavaScript 一直等待不同。
| API 来源 | 结果如何交付 | 使用建议 |
|---|---|---|
node:fs/promises 的 readFile | Promise 成功值是文件内容 | 日常异步文件操作使用 |
node:fs 的 readFileSync | 直接返回文件内容 | 短脚本或启动时读取小配置 |
node:fs 的 readFile | 通过回调交付错误或内容 | 维护使用回调的已有代码 |
这些方法都读取整个文件,异步方法也不会自动减少文件内容占用的内存。需要逐块读取大文件时,使用后面的 Stream。
🛠 写入完成后,才读取新内容
操作存在前后依赖时,每一步需要等待前一步完成。单独保存为 write-read.mjs:
import { writeFile, readFile } from 'node:fs/promises'
await writeFile('promise-note.txt', 'new content', 'utf8')
const text = await readFile('promise-note.txt', 'utf8')
console.log(text)
运行后输出 new content。writeFile 的 Promise 成功值是 undefined,这里等待的是“写入完成”,不是取得文件内容;下一行才读取字符串。
如果去掉写入前的 await,读取可能在写入完成前发生,结果就不可靠。两行代码在文件中的先后顺序,不等于两个异步操作的完成顺序。
🪤 文件操作失败时怎样处理
文件读取失败时,在当前任务中捕获错误,并报告任务失败。单独保存为 read-required.mjs,使用一个不存在的 missing.txt 验证:
import { readFile } from 'node:fs/promises'
try {
const text = await readFile('missing.txt', 'utf8')
console.log(text)
} catch (error) {
if (error.code === 'ENOENT') {
console.error('缺少必需文件 missing.txt,请检查路径')
} else {
console.error('读取失败:', error.code)
}
process.exitCode = 1
}
运行后输出 缺少必需文件 missing.txt,请检查路径,并以退出码 1 结束。process.exitCode 用来把失败交给启动脚本的终端,具体用法见后面的 process 篇。读取成功时才会输出文件内容,不要在失败之后仍然继续处理不存在的数据。
error.code 用于区分原因:ENOENT 表示路径不存在,EACCES 表示权限不足。按错误码判断,不要依赖可能随环境变化的错误文字,也不要把所有失败都提示成“文件不存在”。
⚖️ 什么时候可以同时读取
两个互不依赖的小文件,可以同时开始读取,让等待时间重叠。是否适合这样做,先看两项任务是否需要彼此的结果;比如“写入后读取”就不满足这个条件。
例如同时读取两份独立配置:先在同一目录准备 app.txt(内容为 app)和 user.txt(内容为 user),单独运行下面的 read-two.mjs:
import { readFile } from 'node:fs/promises'
const [app, user] = await Promise.all([
readFile('app.txt', 'utf8'),
readFile('user.txt', 'utf8')
])
console.log(app, user)
输出 app user。两个读取同时发起,结果顺序仍对应传入顺序,不取决于哪个文件先读完。如果任一读取失败,这次等待会抛出错误;需要反馈失败时,按上一节在任务外层添加 try/catch。
但同一文件的连续写入要按顺序等待;数量很多的文件任务也不能无限同时启动,会增加内存与文件资源压力。先把依赖关系写正确,再根据实际需求控制并发数量。
❓ 知识问答
Q1:异步 readFile 会分块返回内容吗?
不会,它仍然在读完后返回整个文件;分块处理要使用流。
Q2:把同步方法放进 async 函数就非阻塞了吗?
没有,同步方法执行期间仍会阻塞当前 JavaScript。
Q3:同一文件连续写入,能同时启动吗?
应等待前一次写入完成,再执行下一次;否则完成顺序不确定,文件内容也可能不符合预期。
🧪 小练习
在写入与读取之间加入 appendFile,追加一行文字,并等待追加完成。运行后确认读到的是原内容和追加内容;appendFile 的参数用法见前一篇文件操作。
// 请在这里编写代码
🎉 现在可以用自己的例子验证这些用法啦!
