Node.js fs/promises：用 async/await 操作文件系统

fs/promises 是 Node fs 模块基于 Promise 的版本。它的函数（readFile、writeFile、readdir、stat、mkdir、rm、rename 等）不接收回调，而是返回一个 Promise，所以你可以 await 它们，并用 try/catch 捕获错误。用 require('fs/promises') 或 import fs from 'fs/promises' 导入它。

import fs from 'fs/promises';

await fs.writeFile('todo.txt', 'write docs\n');
await fs.appendFile('todo.txt', 'ship it\n');

const text = await fs.readFile('todo.txt', 'utf8');
console.log(text.split('\n').filter(Boolean));

它会打印 [ 'write docs', 'ship it' ]：每个 await 都会等一个操作完成后才运行下一行，所以追加总是发生在第一次写入之后。在 ES 模块中，await 可以直接写在顶层；在 CommonJS 中，要把代码包在一个 async 函数里。

最常用的函数

函数名和回调 API 一样，只是去掉了回调。readFile 和 writeFile 页面详细介绍了这两个函数。

用 readdir 和 stat 列出文件夹

readdir 只返回名称。对每个名称调用 stat 可以得到它的大小，或区分文件和文件夹；也可以传入 { withFileTypes: true }，直接得到已经知道自身类型的条目。

import fs from 'fs/promises';

// Setup: a folder with two files and a subfolder
await fs.mkdir('project/src', { recursive: true });
await fs.writeFile('project/README.md', '# Demo');
await fs.writeFile('project/notes.txt', 'abc');

const names = await fs.readdir('project');
console.log(names);

for (const name of names) {
    const info = await fs.stat('project/' + name);
    console.log(name, info.isDirectory() ? 'folder' : info.size + ' bytes');
}

const entries = await fs.readdir('project', { withFileTypes: true });
console.log(entries.filter((e) => e.isFile()).map((e) => e.name));

循环会打印 README.md 6 bytes、notes.txt 3 bytes 和 src folder。对不存在的路径，stat 会以 ENOENT reject，所以当你还需要文件详情时，它可以顺便用来快速检查文件是否存在。

重命名、移动和删除

rename 既能重命名文件，也能移动文件（在同一个磁盘内）。rm 用来删除；删除有内容的文件夹需要 recursive: true，而 force: true 能让它在路径已经不存在时不报错。

import fs from 'fs/promises';

// Setup
await fs.mkdir('blog/drafts', { recursive: true });
await fs.writeFile('blog/drafts/post.md', 'hello');

await fs.mkdir('blog/published', { recursive: true });
await fs.rename('blog/drafts/post.md', 'blog/published/first-post.md');
console.log(await fs.readdir('blog/drafts'), await fs.readdir('blog/published'));

await fs.rm('blog/drafts', { recursive: true });
await fs.rm('blog/drafts', { recursive: true, force: true }); // already gone: no error
console.log(await fs.readdir('blog'));

文件从 drafts 移到了 published，并换了新名字；rm 之后，blog 文件夹里只剩下 published。把第二个 rm 中的 force: true 删掉，它就会以 ENOENT reject。

用 try/catch 处理错误

操作失败时，它的 Promise 会 reject。配合 await，这个 rejection 会变成一个异常，你可以像捕获其他异常一样捕获它。错误的 code 会告诉你出了什么问题。

import fs from 'fs/promises';

async function loadUsers() {
    try {
        const text = await fs.readFile('users.json', 'utf8');
        return JSON.parse(text);
    } catch (err) {
        if (err.code === 'ENOENT') return [];
        throw err;
    }
}

console.log(await loadUsers());

// Setup: create the file, then load again
await fs.writeFile('users.json', '[{"name":"Ada"}]');
console.log((await loadUsers())[0].name);

第一次调用找不到文件，返回 []；第二次打印 Ada。需要了解的错误码：ENOENT（文件不存在）、EEXIST（已经存在）、EISDIR（需要文件的地方是一个文件夹）、ENOTEMPTY（文件夹里还有内容）和 EACCES（没有权限）。

一个既没有 await 也没有 .catch() 的 Promise，失败时会变成未处理的 rejection，Node 会报错退出。每个调用都要 await，或者把它的 Promise 返回给会 await 它的调用者。

用 Promise.all 同时读取多个文件

在 for 循环中使用 await，文件会一个接一个地读取。如果这些读取互不依赖，就同时启动它们，再用 Promise.all 只等待一次：磁盘会同时处理它们。

import fs from 'fs/promises';

// Setup: three small files
await fs.writeFile('a.txt', 'alpha');
await fs.writeFile('b.txt', 'beta');
await fs.writeFile('c.txt', 'gamma');

const files = ['a.txt', 'b.txt', 'c.txt'];
const contents = await Promise.all(files.map((f) => fs.readFile(f, 'utf8')));

console.log(contents);
console.log(contents.join('').length);

Promise.all 会保持输入数组的顺序，所以无论哪个读取先完成，结果都是 [ 'alpha', 'beta', 'gamma' ]，拼接后的长度是 14。把数组中的 'b.txt' 改成 'x.txt'，整个 await 就会以 ENOENT reject。

如果你需要每个结果，即使某些读取失败也要，就用 Promise.allSettled；两者在 Promise 页面 中都有介绍。

常见错误

把两个模块搞混。 require('fs').readFile 需要一个回调；require('fs/promises').readFile 返回一个 Promise。不传回调就调用回调版本，会抛出 The "cb" argument must be of type function。

忘记写 await。 const text = fs.readFile(...) 得到的是一个待定的 Promise，text.split 会抛出 text.split is not a function。

并行写入同一个文件。 用 Promise.all 对同一个路径执行多次写入，可能让文件内容混在一起。这类操作要按顺序执行。