文件系统

稳定性：2 - 稳定

node:fs 模块启用了一种基于标准 POSIX 函数建模的文件系统交互方式。

要使用基于 Promise 的 API：

import * as fs from 'node:fs/promises';

要使用回调和同步 API：

import * as fs from 'node:fs';

所有文件系统操作都有同步、回调和基于 Promise 的形式，并且都可以使用 CommonJS 语法和 ES6 模块 (ESM) 访问。

基于 Promise 的操作返回一个 promise，当异步操作完成时该 promise 会被 fulfilled。

import { unlink } from 'node:fs/promises';

try {
  await unlink('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (error) {
  console.error('there was an error:', error.message);
}

回调形式将完成回调函数作为其最后一个参数，并异步调用操作。传递给完成回调的参数取决于方法，但第一个参数始终保留给异常。如果操作成功完成，则第一个参数为 null 或 undefined。

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

当需要最大性能（在执行时间和内存分配方面）时，node:fs 模块 API 的基于回调的版本优于使用 Promise API。

同步 API 会阻塞 Node.js 事件循环和进一步的 JavaScript 执行，直到操作完成。异常会立即抛出，可以使用 try…catch 处理，也可以允许其向上冒泡。

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // 处理错误
}

fs/promises API 提供返回 promises 的异步文件系统方法。

Promise API 使用底层的 Node.js 线程池在事件循环线程之外执行文件系统操作。这些操作不同步也不是线程安全的。在对同一文件执行多个并发修改时必须小心，否则可能会发生数据损坏。

{FileHandle} 对象是数字文件描述符的对象包装器。

{FileHandle} 对象的实例由 fsPromises.open() 方法创建。

所有 {FileHandle} 对象都是 {EventEmitter}。

如果未使用 filehandle.close() 方法关闭 {FileHandle}，它将尝试自动关闭文件描述符并发出进程警告，有助于防止内存泄漏。请不要依赖此行为，因为它可能不可靠且文件可能未关闭。相反，始终显式关闭 {FileHandle}。Node.js 可能会在未来更改此行为。

当 {FileHandle} 已关闭且不再可用时，会发出 'close' 事件。

filehandle.appendFile(data, options?): void

filehandle.writeFile() 的别名。

当操作文件句柄时，模式不能更改为 fsPromises.open() 所设置的模式。因此，这等同于 filehandle.writeFile()。

filehandle.chmod(mode): void

修改文件上的权限。参见 chmod(2)。

filehandle.chown(uid, gid): void

更改文件的所有权。chown(2) 的包装器。

filehandle.close(): void

• 返回：<Promise> 成功时 fulfilled 为 undefined。

在等待句柄上的任何待处理操作完成后关闭文件句柄。

import { open } from 'node:fs/promises';

let filehandle;
try {
  filehandle = await open('thefile.txt', 'r');
} finally {
  await filehandle?.close();
}

filehandle.createReadStream(options?): void

options 可以包括 start 和 end 值，以便从文件中读取字节范围而不是整个文件。start 和 end 都包含在内并从 0 开始计数，允许的值在 [0, Number.MAX_SAFE_INTEGER] 范围内。如果省略 start 或为 undefined，filehandle.createReadStream() 将从当前文件位置顺序读取。encoding 可以是 {Buffer} 接受的任何值。

如果 {FileHandle} 指向仅支持阻塞读取的字符设备（例如键盘或声卡），则读取操作直到数据可用才会完成。这可能会阻止进程退出并且流无法自然关闭。

默认情况下，流在被销毁后会发出 'close' 事件。将 emitClose 选项设置为 false 以更改此行为。

import { open } from 'node:fs/promises';

const fd = await open('/dev/input/event0');
// 从某个字符设备创建流。
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // 这可能不会关闭流。
  // 人工标记流结束，就好像底层资源本身
  // 指示了文件结束一样，允许流关闭。
  // 这不会取消待处理的读取操作，如果存在这样的
  // 操作，进程可能仍然无法成功退出
  // 直到它完成。
  stream.push(null);
  stream.read(0);
}, 100);

如果 autoClose 为 false，则即使出现错误也不会关闭文件描述符。应用程序有责任关闭它并确保没有文件描述符泄漏。如果 autoClose 设置为 true（默认行为），则在 'error' 或 'end' 时文件描述符将自动关闭。

读取一个 100 字节长的文件的最后 10 字节的示例：

import { open } from 'node:fs/promises';

const fd = await open('sample.txt');
fd.createReadStream({ start: 90, end: 99 });

filehandle.createWriteStream(options?): void

options 还可以包括一个 start 选项，以允许在文件开头之后的某个位置写入数据，允许的值在 [0, Number.MAX_SAFE_INTEGER] 范围内。修改文件而不是替换它可能需要将 flags open 选项设置为 r+ 而不是默认的 r。encoding 可以是 {Buffer} 接受的任何值。

如果 autoClose 设置为 true（默认行为），则在 'error' 或 'finish' 时文件描述符将自动关闭。如果 autoClose 为 false，则即使出现错误也不会关闭文件描述符。应用程序有责任关闭它并确保没有文件描述符泄漏。

默认情况下，流在被销毁后会发出 'close' 事件。将 emitClose 选项设置为 false 以更改此行为。

filehandle.datasync(): void

• 返回：<Promise> 成功时 fulfilled 为 undefined。

强制所有当前排队的与文件关联的 I/O 操作进入操作系统的同步 I/O 完成状态。有关详细信息，请参阅 POSIX fdatasync(2) 文档。

与 filehandle.sync 不同，此方法不刷新修改后的元数据。

• 类型：<number> 由 {FileHandle} 对象管理的数字文件描述符。

filehandle.pull(...transforms?, options?): void

稳定性：1 - 实验性

使用 node:stream/iter pull 模型将文件内容作为异步迭代器返回。读取以 chunkSize 字节块（默认 128 KB）执行。如果提供了转换，它们将通过 stream/iter pull() 应用。

当迭代器被消费时文件句柄被锁定，当迭代完成、发生错误或消费者中断时解锁。

此函数仅在启用 --experimental-stream-iter 标志时可用。

import { open } from 'node:fs/promises';
import { text } from 'node:stream/iter';
import { compressGzip } from 'node:zlib/iter';

const fh = await open('input.txt', 'r');

// 读取为文本
console.log(await text(fh.pull({ autoClose: true })));

// 从字节 100 开始读取 1 KB
const fh2 = await open('input.txt', 'r');
console.log(await text(fh2.pull({ start: 100, limit: 1024, autoClose: true })));

// 读取并压缩
const fh3 = await open('input.txt', 'r');
const compressed = fh3.pull(compressGzip(), { autoClose: true });

filehandle.pullSync(...transforms?, options?): void

稳定性：1 - 实验性

filehandle.pull() 的同步对应物。返回一个同步迭代器，使用主线程上的同步 I/O 读取文件。读取以 chunkSize 字节块（默认 128 KB）执行。

当迭代器被消费时文件句柄被锁定。与异步 pull() 不同，此方法不支持 AbortSignal，因为所有操作都是同步的。

此函数仅在启用 --experimental-stream-iter 标志时可用。

import { open } from 'node:fs/promises';
import { textSync, pipeToSync } from 'node:stream/iter';
import { compressGzipSync, decompressGzipSync } from 'node:zlib/iter';

const fh = await open('input.txt', 'r');

// 读取为文本（同步）
console.log(textSync(fh.pullSync({ autoClose: true })));

// 同步压缩管道：file -> gzip -> file
const src = await open('input.txt', 'r');
const dst = await open('output.gz', 'w');
pipeToSync(src.pullSync(compressGzipSync(), { autoClose: true }), dst.writer({ autoClose: true }));

filehandle.read(buffer, offset, length, position): void

从文件读取数据并将其存储在给定的缓冲区中。

如果文件未并发修改，则当读取的字节数为零时到达文件末尾。

filehandle.read(options?): void

从文件读取数据并将其存储在给定的缓冲区中。

如果文件未并发修改，则当读取的字节数为零时到达文件末尾。

filehandle.read(buffer, options?): void

从文件读取数据并将其存储在给定的缓冲区中。

如果文件未并发修改，则当读取的字节数为零时到达文件末尾。

filehandle.readableWebStream(options?): void

返回一个面向字节的 ReadableStream，可用于读取文件的内容。

如果多次调用此方法或在 FileHandle 关闭或正在关闭后调用，将抛出错误。

import {
  open,
} from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const chunk of file.readableWebStream())
  console.log(chunk);

await file.close();

虽然 ReadableStream 会将文件读取到完成，但它不会自动关闭 FileHandle。除非 autoClose 选项设置为 true，否则用户代码仍必须调用 fileHandle.close() 方法。

filehandle.readFile(options): void

异步读取文件的全部内容。

如果 options 是字符串，则它指定 encoding。

{FileHandle} 必须支持读取。

如果在文件句柄上进行了一次或多次 filehandle.read() 调用，然后进行了 filehandle.readFile() 调用，则数据将从当前位置读取到文件末尾。它并不总是从文件开头读取。

filehandle.readLines(options?): void

创建 readline 接口并通过文件流式传输的便捷方法。有关选项，请参阅 filehandle.createReadStream()。

import { open } from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const line of file.readLines()) {
  console.log(line);
}

filehandle.readv(buffers, position?): void

从文件读取并写入 {ArrayBufferView} 数组

filehandle.stat(options?): void

filehandle.sync(): void

• 返回：<Promise> 成功时 fulfilled 为 undefined。

请求将打开的文件描述符的所有数据刷新到存储设备。具体实现取决于操作系统和设备。有关更多详细信息，请参阅 POSIX fsync(2) 文档。

filehandle.truncate(len): void

截断文件。

如果文件大于 len 字节，则文件中只保留前 len 字节。

以下示例仅保留文件的前四个字节：

import { open } from 'node:fs/promises';

let filehandle = null;
try {
  filehandle = await open('temp.txt', 'r+');
  await filehandle.truncate(4);
} finally {
  await filehandle?.close();
}

如果文件以前短于 len 字节，则它会扩展，并且扩展部分填充空字节（'\0'）：

如果 len 为负数，则将使用 0。

filehandle.utimes(atime, mtime): void

更改 {FileHandle} 引用的对象的文件系统时间戳，然后在成功时 fulfilled promise 且不带参数。

filehandle.write(buffer, offset, length?, position?): void

将 buffer 写入文件。

Promise fulfilled 为一个包含两个属性的对象：

在不等待 promise fulfilled（或 rejected）的情况下在同一文件上多次使用 filehandle.write() 是不安全的。对于这种情况，请使用 filehandle.createWriteStream()。

在 Linux 上，当文件以追加模式打开时，位置写入不起作用。内核忽略位置参数并始终将数据追加到文件末尾。

filehandle.write(buffer, options?): void

将 buffer 写入文件。

与上面的 filehandle.write 函数类似，此版本采用可选的 options 对象。如果未指定 options 对象，它将默认使用上述值。

filehandle.write(string, position?, encoding?): void

将 string 写入文件。如果 string 不是字符串，则 promise 被 rejected 并带有错误。

Promise fulfilled 为一个包含两个属性的对象：

在不等待 promise fulfilled（或 rejected）的情况下在同一文件上多次使用 filehandle.write() 是不安全的。对于这种情况，请使用 filehandle.createWriteStream()。

在 Linux 上，当文件以追加模式打开时，位置写入不起作用。内核忽略位置参数并始终将数据追加到文件末尾。

filehandle.writeFile(data, options): void

异步将数据写入文件，如果文件已存在则替换该文件。data 可以是字符串、缓冲区、<AsyncIterable> 或 {Iterable} 对象。成功时 promise fulfilled 且不带参数。

如果 options 是字符串，则它指定 encoding。

{FileHandle} 必须支持写入。

在不等待 promise fulfilled（或 rejected）的情况下在同一文件上多次使用 filehandle.writeFile() 是不安全的。

如果在文件句柄上进行了一次或多次 filehandle.write() 调用，然后进行了 filehandle.writeFile() 调用，则数据将从当前位置写入到文件末尾。它并不总是从文件开头写入。

filehandle.writev(buffers, position?): void

将 {ArrayBufferView} 数组写入文件。

Promise fulfilled 为一个包含两个属性的对象：

在不等待 promise fulfilled（或 rejected）的情况下在同一文件上多次调用 writev() 是不安全的。

在 Linux 上，当文件以追加模式打开时，位置写入不起作用。内核忽略位置参数并始终将数据追加到文件末尾。

filehandle.writer(options?): void

稳定性：1 - 实验性

返回由此文件句柄支持的 node:stream/iter writer。

writer 支持 Symbol.asyncDispose 和 Symbol.dispose：

• await using w = fh.writer() — 如果 writer 仍然打开（未调用 end()），asyncDispose 调用 fail()。如果 end() 待处理，则等待其完成。
• using w = fh.writer() — 无条件调用 fail()。

writeSync() 和 writevSync() 方法启用 stream/iter pipeTo() 使用的 try-sync 快速路径。当 reader 的块大小与 writer 的 chunkSize 匹配时，pipeTo() 管道中的所有写入都同步完成，零 promise 开销。

此函数仅在启用 --experimental-stream-iter 标志时可用。

import { open } from 'node:fs/promises';
import { from, pipeTo } from 'node:stream/iter';
import { compressGzip } from 'node:zlib/iter';

// 异步管道
const fh = await open('output.gz', 'w');
await pipeTo(from('Hello!'), compressGzip(), fh.writer({ autoClose: true }));

// 带限制的同步管道
const src = await open('input.txt', 'r');
const dst = await open('output.txt', 'w');
const w = dst.writer({ limit: 1024 * 1024 }); // 最大 1 MB
await pipeTo(src.pull({ autoClose: true }), w);
await w.end();
await dst.close();

filehandle[Symbol.asyncDispose](): void

调用 filehandle.close() 并返回一个 promise，当文件句柄关闭时该 promise fulfilled。

fsPromises.access(path, mode?): void

测试用户对 path 指定的文件或目录的权限。mode 参数是一个可选整数，指定要执行的 accessibility 检查。mode 应为值 fs.constants.F_OK 或由任何 fs.constants.R_OK、fs.constants.W_OK 和 fs.constants.X_OK 的按位 OR 组成的掩码（例如 fs.constants.W_OK | fs.constants.R_OK）。检查 文件访问常量 以获取 mode 的可能值。

如果 accessibility 检查成功，则 promise fulfilled 且不带值。如果任何 accessibility 检查失败，则 promise 被 rejected 并带有 <Error> 对象。以下示例检查当前进程是否可以读取和写入文件 /etc/passwd。

import { access, constants } from 'node:fs/promises';

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK);
  console.log('can access');
} catch {
  console.error('cannot access');
}

在调用 fsPromises.open() 之前使用 fsPromises.access() 检查文件的 accessibility 是不推荐的。这样做会引入竞争条件，因为其他进程可能会在两次调用之间更改文件的状态。相反，用户代码应直接打开/读取/写入文件并处理如果文件不可访问时引发的错误。

fsPromises.appendFile(path, data, options?): void

异步将数据追加到文件，如果文件尚不存在则创建该文件。data 可以是字符串或 {Buffer}。

如果 options 是字符串，则它指定 encoding。

mode 选项仅影响新创建的文件。有关更多详细信息，请参阅 fs.open()。

path 可以指定为已打开用于追加的 {FileHandle}（使用 fsPromises.open()）。

fsPromises.chmod(path, mode): void

更改文件的权限。

fsPromises.chown(path, uid, gid): void

更改文件的所有权。

fsPromises.copyFile(src, dest, mode?): void

异步将 src 复制到 dest。默认情况下，如果 dest 已存在则将其覆盖。

不保证复制操作的原子性。如果在打开目标文件进行写入后发生错误，将尝试删除目标文件。

import { copyFile, constants } from 'node:fs/promises';

try {
  await copyFile('source.txt', 'destination.txt');
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
}

// 通过使用 COPYFILE_EXCL，如果 destination.txt 存在，操作将失败。
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
}

fsPromises.cp(src, dest, options?): void

异步将整个目录结构从 src 复制到 dest，包括子目录和文件。

当将目录复制到另一个目录时，不支持 globs，行为类似于 cp dir1/ dir2/。

fsPromises.glob(pattern, options?): void

import { glob } from 'node:fs/promises';

for await (const entry of glob('**/*.js'))
  console.log(entry);

fsPromises.lchmod(path, mode): void

稳定性：0 - 已弃用

更改符号链接上的权限。

此方法仅在 macOS 上实现。

fsPromises.lchown(path, uid, gid): void

更改符号链接上的所有权。

fsPromises.lutimes(path, atime, mtime): void

以与 fsPromises.utimes() 相同的方式更改文件的访问和修改时间，不同之处在于如果路径引用符号链接，则链接不会被解引用：相反，符号链接本身的时间戳会被更改。

fsPromises.link(existingPath, newPath): void

从 existingPath 到 newPath 创建新链接。有关更多详细信息，请参阅 POSIX link(2) 文档。

fsPromises.lstat(path, options?): void

等同于 fsPromises.stat()，除非 path 引用符号链接，在这种情况下统计的是链接本身，而不是它引用的文件。有关更多详细信息，请参阅 POSIX lstat(2) 文档。

fsPromises.mkdir(path, options?): void

异步创建目录。

可选的 options 参数可以是指定 mode（权限和粘滞位）的整数，也可以是具有 mode 属性和指示是否应创建父目录的 recursive 属性的对象。当 path 是已存在的目录时调用 fsPromises.mkdir() 仅在 recursive 为 false 时导致 rejection。

import { mkdir } from 'node:fs/promises';

try {
  const projectFolder = new URL('./test/project/', import.meta.url);
  const createDir = await mkdir(projectFolder, { recursive: true });

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}

fsPromises.mkdtemp(prefix, options?): void

创建一个唯一的临时目录。唯一的目录名是通过在提供的 prefix 末尾追加六个随机字符生成的。由于平台不一致性，避免在 prefix 中使用尾随的 X 字符。某些平台（尤其是 BSD 系列）可能会返回超过六个随机字符，并将 prefix 中尾随的 X 字符替换为随机字符。

可选的 options 参数可以是指定编码的字符串，也可以是具有 encoding 属性的对象，用于指定要使用的字符编码。

import { mkdtemp } from 'node:fs/promises';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

try {
  await mkdtemp(join(tmpdir(), 'foo-'));
} catch (err) {
  console.error(err);
}

fsPromises.mkdtemp() 方法会将六个随机选择的字符直接追加到 prefix 字符串。例如，给定目录 /tmp，如果打算 在 /tmp 内 创建临时目录，则 prefix 必须以尾随的平台特定路径分隔符（require('node:path').sep）结尾。

fsPromises.mkdtempDisposable(prefix, options?): void

生成的 Promise 持有一个异步可处置对象，其 path 属性持有创建的目录路径。当对象被处置时，如果目录仍然存在，目录及其内容将被异步移除。如果无法删除目录，处置将抛出错误。该对象具有一个异步 remove() 方法，将执行相同的任务。

此函数和结果对象上的处置函数都是异步的，因此应像 await using dir = await fsPromises.mkdtempDisposable('prefix') 那样与 await + await using 一起使用。

详细信息，请参阅 fsPromises.mkdtemp() 的文档。

可选的 options 参数可以是指定编码的字符串，也可以是具有 encoding 属性的对象，用于指定要使用的字符编码。

fsPromises.open(path, flags, mode?): void

打开一个 {FileHandle}。

Refer to the POSIX open(2) documentation for more detail. 请参阅 POSIX open(2) 文档了解更多详情。

某些字符（< > : " / \ | ? *）在 Windows 下是保留的，详见 命名文件、路径和命名空间。在 NTFS 下，如果文件名包含冒号，Node.js 将打开一个文件系统流，如 此 MSDN 页面 所述。

fsPromises.opendir(path, options?): void

异步打开一个目录以进行迭代扫描。请参阅 POSIX opendir(3) 文档了解更多详情。

创建一个 <fs.Dir>，其中包含所有用于从目录读取和清理目录的函数。

encoding 选项设置在打开目录和后续读取操作时 path 的编码。

使用异步迭代的示例：

import { opendir } from 'node:fs/promises';

try {
  const dir = await opendir('./');
  for await (const dirent of dir)
    console.log(dirent.name);
} catch (err) {
  console.error(err);
}

使用异步迭代器时，<fs.Dir> 对象将在迭代器退出后自动关闭。

fsPromises.readdir(path, options?): void

读取目录的内容。

可选的 options 参数可以是指定编码的字符串，也可以是具有 encoding 属性的对象，用于指定用于文件名的字符编码。如果 encoding 设置为 'buffer'，返回的文件名将作为 {Buffer} 对象传递。

如果 options.withFileTypes 设置为 true，返回的数组将包含 <fs.Dirent> 对象。

import { readdir } from 'node:fs/promises';

try {
  const files = await readdir(path);
  for (const file of files)
    console.log(file);
} catch (err) {
  console.error(err);
}

fsPromises.readFile(path, options?): void

异步读取文件的全部内容。

如果未指定编码（使用 options.encoding），数据将作为 {Buffer} 对象返回。否则，数据将是字符串。

如果 options 是字符串，则它指定编码。

当 path 是目录时，fsPromises.readFile() 的行为特定于平台。在 macOS、Linux 和 Windows 上，Promise 将被拒绝并抛出错误。在 FreeBSD 上，将返回目录内容的表示。

读取位于运行代码同一目录中的 package.json 文件的示例：

import { readFile } from 'node:fs/promises';
try {
  const filePath = new URL('./package.json', import.meta.url);
  const contents = await readFile(filePath, { encoding: 'utf8' });
  console.log(contents);
} catch (err) {
  console.error(err.message);
}

可以使用 <AbortSignal> 中止正在进行的 readFile。如果请求被中止，返回的 Promise 将被 AbortError 拒绝：

import { readFile } from 'node:fs/promises';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const promise = readFile(fileName, { signal });

  // 在 Promise 结算前中止请求。
  controller.abort();

  await promise;
} catch (err) {
  // 当请求被中止时 - err 是一个 AbortError
  console.error(err);
}

中止正在进行的请求不会中止单个操作系统请求，而是中止 fs.readFile 执行的内部缓冲。

任何指定的 {FileHandle} 必须支持读取。

fsPromises.readlink(path, options?): void

读取 path 引用的符号链接的内容。请参阅 POSIX readlink(2) 文档了解更多详情。成功时 Promise 兑现为 linkString。

可选的 options 参数可以是指定编码的字符串，也可以是具有 encoding 属性的对象，用于指定用于返回的链接路径的字符编码。如果 encoding 设置为 'buffer'，返回的链接路径将作为 {Buffer} 对象传递。

fsPromises.realpath(path, options?): void

使用与 fs.realpath.native() 函数相同的语义确定 path 的实际位置。

仅支持可以转换为 UTF8 字符串的路径。

可选的 options 参数可以是指定编码的字符串，也可以是具有 encoding 属性的对象，用于指定用于路径的字符编码。如果 encoding 设置为 'buffer'，返回的路径将作为 {Buffer} 对象传递。

在 Linux 上，当 Node.js 链接到 musl libc 时，必须将 procfs 文件系统挂载到 /proc 才能使此函数工作。Glibc 没有此限制。

fsPromises.rename(oldPath, newPath): void

将 oldPath 重命名为 newPath。

fsPromises.rmdir(path, options?): void

移除由 path 标识的目录。

在文件（非目录）上使用 fsPromises.rmdir() 会导致 Promise 被拒绝，在 Windows 上抛出 ENOENT 错误， 在 POSIX 上抛出 ENOTDIR 错误。

要获得类似于 rm -rf Unix 命令的行为，请使用 fsPromises.rm() 并带有选项 { recursive: true, force: true }。

fsPromises.rm(path, options?): void

移除文件和目录（基于标准 POSIX rm 工具建模）。

fsPromises.stat(path, options?): void

fsPromises.statfs(path, options?): void

fsPromises.symlink(target, path, type?): void

创建一个符号链接。

type 参数仅在 Windows 平台上使用，可以是 'dir'、 'file' 或 'junction' 之一。如果 type 参数为 null，Node.js 将 自动检测 target 类型并使用 'file' 或 'dir'。如果 target 不存在， 将使用 'file'。Windows 联接点要求目标 路径为绝对路径。使用 'junction' 时，target 参数将 自动规范化为绝对路径。NTFS 卷上的联接点 只能指向目录。

fsPromises.truncate(path, len?): void

将 path 处的内容截断（缩短或扩展长度）为 len 字节。

fsPromises.unlink(path): void

如果 path 指的是符号链接，则移除该链接而不影响 该链接所指的文件或目录。如果 path 指的是非 符号链接的文件路径，则删除该文件。请参阅 POSIX unlink(2) 文档了解更多详情。

fsPromises.utimes(path, atime, mtime): void

更改由 path 引用的对象的文件系统时间戳。

atime 和 mtime 参数遵循以下规则：

• 值可以是代表 Unix 纪元时间的数字、Date，或 数字字符串如 '123456789.0'。
• 如果值无法转换为数字，或是 NaN、Infinity 或 -Infinity，将抛出 Error。

fsPromises.watch(filename, options?): void

返回一个异步迭代器，监视 filename 上的更改，其中 filename 可以是文件或目录。

const { watch } = require('node:fs/promises');

const ac = new AbortController();
const { signal } = ac;
setTimeout(() => ac.abort(), 10000);

(async () => {
  try {
    const watcher = watch(__filename, { signal });
    for await (const event of watcher)
      console.log(event);
  } catch (err) {
    if (err.name === 'AbortError')
      return;
    throw err;
  }
})();

在大多数平台上，每当目录中出现或消失文件名时，都会发出 'rename'。

fs.watch() 的所有 注意事项 也适用于 fsPromises.watch()。

fsPromises.writeFile(file, data, options?): void

异步将数据写入文件，如果文件已存在则替换它。 data 可以是字符串、缓冲区、<AsyncIterable> 或 {Iterable} 对象。

如果 data 是缓冲区，则忽略 encoding 选项。

如果 options 是字符串，则它指定编码。

mode 选项仅影响新创建的文件。参见 fs.open() 了解更多详情。

任何指定的 {FileHandle} 必须支持写入。

在不等待 Promise 结算的情况下多次在同一文件上使用 fsPromises.writeFile() 是不安全的。

类似于 fsPromises.readFile - fsPromises.writeFile 是一个便捷 方法，内部执行多次 write 调用以写入传递给它的缓冲区。对于性能敏感的代码，考虑使用 fs.createWriteStream() 或 filehandle.createWriteStream()。

可以使用 <AbortSignal> 取消 fsPromises.writeFile()。 取消是“尽力而为”，可能仍会有少量数据 被写入。

import { writeFile } from 'node:fs/promises';
import { Buffer } from 'node:buffer';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const data = new Uint8Array(Buffer.from('Hello Node.js'));
  const promise = writeFile('message.txt', data, { signal });

  // 在 Promise 结算前中止请求。
  controller.abort();

  await promise;
} catch (err) {
  // 当请求被中止时 - err 是一个 AbortError
  console.error(err);
}

中止正在进行的请求不会中止单个操作系统 请求，而是中止 fs.writeFile 执行的内部缓冲。

• 类型：<Object>

返回一个包含文件系统操作常用常量的对象。该对象与 fs.constants 相同。参见 FS 常量 了解更多详情。

回调 API 异步执行所有操作，不会阻塞事件循环，然后在完成或出错时调用回调函数。

回调 API 使用底层的 Node.js 线程池在事件循环线程之外执行文件系统操作。这些操作不是同步的，也不是线程安全的。在对同一文件或数据进行多次并发修改时必须小心，否则可能会导致数据损坏。

fs.access(path, mode?, callback): void

测试用户对 path 指定的文件或目录的权限。mode 参数是一个可选的整数，指定要执行的访问检查。mode 应该是值 fs.constants.F_OK 或由 fs.constants.R_OK、fs.constants.W_OK 和 fs.constants.X_OK 中任意一个按位 OR 组成的掩码（例如 fs.constants.W_OK | fs.constants.R_OK）。检查 文件访问常量 以获取 mode 的可能值。

最后一个参数 callback 是一个回调函数，使用可能的错误参数调用。如果任何访问检查失败，错误参数将是一个 Error 对象。以下示例检查 package.json 是否存在，以及是否可读或可写。

import { access, constants } from 'node:fs';

const file = 'package.json';

// 检查文件是否存在于当前目录中。
access(file, constants.F_OK, (err) => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
});

// 检查文件是否可读。
access(file, constants.R_OK, (err) => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`);
});

// 检查文件是否可写。
access(file, constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
});

// 检查文件是否可读且可写。
access(file, constants.R_OK | constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
});