Node.js v26.0.0 文档

文件系统#

node:fs 模块提供了以符合标准 POSIX 函数的方式与文件系统进行交互的能力。

使用基于 Promise 的 API

import * as fs from 'node:fs/promises';
const fs = require('node:fs/promises');
copy

使用回调和同步 API

import * as fs from 'node:fs';
const fs = require('node:fs');
copy

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

Promise 示例#

基于 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);
}
const { unlink } = require('node:fs/promises');

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

回调示例#

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

import { unlink } from 'node:fs';

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

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

当需要最大性能（在执行时间和内存分配方面）时，基于回调的 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) {
  // handle the error
}
const { unlinkSync } = require('node:fs');

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}
copy

Promises API#

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

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

类：FileHandle#

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

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

所有 <FileHandle> 对象都是 <EventEmitter>。

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

事件：'close'#

当 <FileHandle> 已关闭且无法再使用时，会发出 'close' 事件。

filehandle.appendFile(data[, options])#

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> 默认值： 'utf8'
  • signal <AbortSignal> | <undefined> 允许中止正在进行的 writeFile。默认值： undefined
• 返回：<Promise> 成功时以 undefined 兑现。

filehandle.writeFile() 的别名。

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

filehandle.chmod(mode)#

• mode <integer> 文件模式位掩码。
• 返回：<Promise> 成功时以 undefined 兑现。

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

filehandle.chown(uid, gid)#

• uid <integer> 文件的新所有者用户 ID。
• gid <integer> 文件的新所属组 ID。
• 返回：<Promise> 成功时以 undefined 兑现。

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

filehandle.close()#

• 返回：<Promise> 成功时以 undefined 兑现。

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

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

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

filehandle.createReadStream([options])#

• options <Object>
• encoding <string> 默认值： null
• autoClose <boolean> 默认值： true
• emitClose <boolean> 默认值： true
• start <integer>
• end <integer> 默认值： Infinity
• highWaterMark <integer> 默认值： 64 * 1024
• signal <AbortSignal> | <undefined> 默认值： undefined

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');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100);
copy

如果 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 });
copy

filehandle.createWriteStream([options])#

• options <Object>
• encoding <string> 默认值： 'utf8'
• autoClose <boolean> 默认值： true
• emitClose <boolean> 默认值： true
• start <integer>
• highWaterMark <number> 默认值： 16384
• flush <boolean> 如果为 true，底层文件描述符在关闭前会被刷新。默认值： false。

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

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

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

filehandle.datasync()#

• 返回：<Promise> 成功时以 undefined 兑现。

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

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

filehandle.fd#

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

filehandle.pull([...transforms][, options])#

• ...transforms <Function> | <Object> 可选的转换操作，通过 stream/iter pull() 应用。
• options <Object>
• signal <AbortSignal>
• autoClose <boolean> 在流结束时关闭文件句柄。默认值： false。
• start <number> 开始读取的字节偏移量。指定时，读取使用显式定位（pread 语义）。默认值： 当前文件位置。
• limit <number> 迭代器结束前读取的最大字节数。读取在传递了 limit 字节或到达 EOF 时停止，以先发生者为准。默认值： 读取直到 EOF。
• chunkSize <number> 为每次读取操作分配的缓冲区大小（以字节为单位）。默认值： 131072 (128 KB)。

使用 node:stream/iter 拉取模型以异步可迭代对象的形式返回文件内容。读取以 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');

// Read as text
console.log(await text(fh.pull({ autoClose: true })));

// Read 1 KB starting at byte 100
const fh2 = await open('input.txt', 'r');
console.log(await text(fh2.pull({ start: 100, limit: 1024, autoClose: true })));

// Read with compression
const fh3 = await open('input.txt', 'r');
const compressed = fh3.pull(compressGzip(), { autoClose: true });
const { open } = require('node:fs/promises');
const { text } = require('node:stream/iter');
const { compressGzip } = require('node:zlib/iter');

async function run() {
  const fh = await open('input.txt', 'r');

  // Read as text
  console.log(await text(fh.pull({ autoClose: true })));

  // Read 1 KB starting at byte 100
  const fh2 = await open('input.txt', 'r');
  console.log(await text(fh2.pull({ start: 100, limit: 1024, autoClose: true })));

  // Read with compression
  const fh3 = await open('input.txt', 'r');
  const compressed = fh3.pull(compressGzip(), { autoClose: true });
}

run().catch(console.error);
copy

filehandle.pullSync([...transforms][, options])#

• ...transforms <Function> | <Object> 可选的转换操作，通过 stream/iter pullSync() 应用。
• options <Object>
• autoClose <boolean> 在流结束时关闭文件句柄。默认值： false。
• start <number> 开始读取的字节偏移量。指定时，读取使用显式定位。默认值： 当前文件位置。
• limit <number> 迭代器结束前读取的最大字节数。默认值： 读取直到 EOF。
• chunkSize <number> 为每次读取操作分配的缓冲区大小（以字节为单位）。默认值： 131072 (128 KB)。

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');

// Read as text (sync)
console.log(textSync(fh.pullSync({ autoClose: true })));

// Sync compress pipeline: 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 }));
const { open } = require('node:fs/promises');
const { textSync, pipeToSync } = require('node:stream/iter');
const { compressGzipSync, decompressGzipSync } = require('node:zlib/iter');

async function run() {
  const fh = await open('input.txt', 'r');

  // Read as text (sync)
  console.log(textSync(fh.pullSync({ autoClose: true })));

  // Sync compress pipeline: 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 }),
  );
}

run().catch(console.error);
copy

filehandle.read(buffer, offset, length, position)#

• buffer <Buffer> | <TypedArray> | <DataView> 一个将被读取的文件数据填充的缓冲区。
• offset <integer> 缓冲区中开始填充的位置。默认值： 0
• length <integer> 要读取的字节数。默认值： buffer.byteLength - offset
• position <integer> | <bigint> | <null> 从文件开始读取数据的位置。如果为 null 或 -1，则从当前文件位置读取数据，并更新该位置。如果 position 是非负整数，则当前文件位置保持不变。默认值： null
• 返回：<Promise> 成功时以一个包含两个属性的对象兑现
  • bytesRead <integer> 读取的字节数
  • buffer <Buffer> | <TypedArray> | <DataView> 对传入的 buffer 参数的引用。

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

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

filehandle.read([options])#

• options <Object>
• buffer <Buffer> | <TypedArray> | <DataView> 一个将被读取的文件数据填充的缓冲区。默认值： Buffer.alloc(16384)
• offset <integer> 缓冲区中开始填充的位置。默认值： 0
• length <integer> 要读取的字节数。默认值： buffer.byteLength - offset
• position <integer> | <bigint> | <null> 从文件开始读取数据的位置。如果为 null 或 -1，则从当前文件位置读取数据，并更新该位置。如果 position 是非负整数，则当前文件位置保持不变。默认值： null

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

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

filehandle.read(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> 一个将被读取的文件数据填充的缓冲区。
• options <Object>
• offset <integer> 缓冲区中开始填充的位置。默认值： 0
• length <integer> 要读取的字节数。默认值： buffer.byteLength - offset
• position <integer> | <bigint> | <null> 从文件开始读取数据的位置。如果为 null 或 -1，则从当前文件位置读取数据，并更新该位置。如果 position 是非负整数，则当前文件位置保持不变。默认值： null

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

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

filehandle.readableWebStream([options])#

• options <Object>
• autoClose <boolean> 当为 true 时，导致 <FileHandle> 在流关闭时关闭。默认值： false

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();
const {
  open,
} = require('node:fs/promises');

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

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

  await file.close();
})();
copy

filehandle.readFile(options)#

• options <Object> | <string>
  • encoding <string> | <null> 默认值： null
  • signal <AbortSignal> 允许中止正在进行的 readFile
• 返回：<Promise> 成功读取时以文件内容兑现。如果未指定编码（使用 options.encoding），则数据作为 <Buffer> 对象返回。否则，数据将是字符串。

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

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

<FileHandle> 必须支持读取。

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

filehandle.readLines([options])#

• options <Object>
• encoding <string> 默认值： null
• autoClose <boolean> 默认值： true
• emitClose <boolean> 默认值： true
• start <integer>
• end <integer> 默认值： Infinity
• highWaterMark <integer> 默认值： 64 * 1024

用于创建 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);
}
const { open } = require('node:fs/promises');

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

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

filehandle.readv(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> 应从中读取数据的距文件开头的偏移量。如果 position 不是 number，则数据将从当前位置读取。默认值： null
• 返回：<Promise> 成功时以包含两个属性的对象兑现
  • bytesRead <integer> 读取的字节数
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> 包含对 buffers 输入引用的属性。

从文件读取并写入到 <ArrayBufferView> 数组中

filehandle.stat([options])#

• options <Object>
• bigint <boolean> 返回的 <fs.Stats> 对象中的数值是否应为 bigint。默认值： false。

filehandle.sync()#

• 返回：<Promise> 成功时以 undefined 兑现。

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

filehandle.truncate(len)#

• len <integer> 默认值： 0
• 返回：<Promise> 成功时以 undefined 兑现。

截断文件。

如果文件大于 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();
}
copy

如果文件以前短于 len 字节，则它会被扩展，扩展的部分会填充空字节 ('\0')

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

filehandle.utimes(atime, mtime)#

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 返回：<Promise>

更改由 <FileHandle> 引用的对象的文件系统时间戳，并在成功后以无参数的 promise 兑现。

filehandle.write(buffer, offset[, length[, position]])#

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> buffer 内要写入数据开始的位置。
• length <integer> 要从 buffer 写入的字节数。默认值： buffer.byteLength - offset
• position <integer> | <null> 距文件开头的偏移量，应在此处写入来自 buffer 的数据。如果 position 不是 number，则数据将在当前位置写入。详细信息请参考 POSIX pwrite(2) 文档。默认值： null
• 返回：<Promise>

将 buffer 写入文件。

promise 兑现时会返回一个包含两个属性的对象

• bytesWritten <integer> 写入的字节数
• buffer <Buffer> | <TypedArray> | <DataView> 对写入的 buffer 的引用。

在未等待 promise 兑现（或拒绝）之前，在同一个文件上多次使用 filehandle.write() 是不安全的。对于这种情况，请使用 filehandle.createWriteStream()。

在 Linux 上，当文件以追加模式打开时，定位写入无法工作。内核会忽略位置参数，始终将数据追加到文件末尾。

filehandle.write(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView>
• options <Object>
• offset <integer> 默认值： 0
• length <integer> 默认值： buffer.byteLength - offset
• position <integer> | <null> 默认值： null

将 buffer 写入文件。

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

filehandle.write(string[, position[, encoding]])#

• string <string>
• position <integer> | <null> 距文件开头的偏移量，应在此处写入来自 string 的数据。如果 position 不是 number，则数据将在当前位置写入。详细信息请参考 POSIX pwrite(2) 文档。默认值： null
• encoding <string> 预期的字符串编码。默认值： 'utf8'
• 返回：<Promise>

将 string 写入文件。如果 string 不是字符串，promise 将会被拒绝并抛出错误。

promise 兑现时会返回一个包含两个属性的对象

• bytesWritten <integer> 写入的字节数
• buffer <string> 对写入的 string 的引用。

在未等待 promise 兑现（或拒绝）之前，在同一个文件上多次使用 filehandle.write() 是不安全的。对于这种情况，请使用 filehandle.createWriteStream()。

在 Linux 上，当文件以追加模式打开时，定位写入无法工作。内核会忽略位置参数，始终将数据追加到文件末尾。

filehandle.writeFile(data, options)#

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> 当 data 为字符串时预期的字符编码。默认值： 'utf8'
  • signal <AbortSignal> | <undefined> 允许中止正在进行的 writeFile。默认值： undefined
• 返回：<Promise>

异步将数据写入文件，如果文件已存在则替换它。data 可以是字符串、缓冲区、<AsyncIterable> 或 <Iterable> 对象。成功时以无参数的 promise 兑现。

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

<FileHandle> 必须支持写入。

在未等待 promise 兑现（或拒绝）之前，在同一个文件上多次使用 filehandle.writeFile() 是不安全的。

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

filehandle.writev(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> 距文件开头的偏移量，应在此处写入来自 buffers 的数据。如果 position 不是 number，则数据将在当前位置写入。默认值： null
• 返回：<Promise>

将 <ArrayBufferView> 数组写入文件。

promise 兑现时会返回一个包含两个属性的对象

• bytesWritten <integer> 写入的字节数
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> 对 buffers 输入的引用。

在未等待 promise 兑现（或拒绝）之前，在同一个文件上多次调用 writev() 是不安全的。

在 Linux 上，当文件以追加模式打开时，定位写入无法工作。内核会忽略位置参数，始终将数据追加到文件末尾。

filehandle.writer([options])#

• options <Object>
• autoClose <boolean> 在写入器结束或失败时关闭文件句柄。默认值： false。
• start <number> 开始写入的字节偏移量。指定时，写入使用显式定位。默认值： 当前文件位置。
• limit <number> 写入器将接受的最大字节数。超过限制的异步写入 (write(), writev()) 将被拒绝并返回 ERR_OUT_OF_RANGE。同步写入 (writeSync(), writevSync()) 将返回 false。默认值： 无限制。
• chunkSize <number> 同步写入操作的最大块大小（以字节为单位）。大于此阈值的写入将回退到异步 I/O。将其设置为匹配读取器的 chunkSize 以获得最佳 pipeTo() 性能。默认值： 131072 (128 KB)。

返回一个由该文件句柄支持的 node:stream/iter 写入器。

该写入器支持 Symbol.asyncDispose 和 Symbol.dispose

• await using w = fh.writer() — 如果写入器仍打开（未调用 end()），asyncDispose 将调用 fail()。如果 end() 正在挂起，它将等待它完成。
• using w = fh.writer() — 无条件调用 fail()。

writeSync() 和 writevSync() 方法启用了 stream/iter pipeTo() 使用的同步尝试快速路径。当读取器的块大小与写入器的 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';

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

// Sync pipeline with limit
const src = await open('input.txt', 'r');
const dst = await open('output.txt', 'w');
const w = dst.writer({ limit: 1024 * 1024 }); // Max 1 MB
await pipeTo(src.pull({ autoClose: true }), w);
await w.end();
await dst.close();
const { open } = require('node:fs/promises');
const { from, pipeTo } = require('node:stream/iter');
const { compressGzip } = require('node:zlib/iter');

async function run() {
  // Async pipeline
  const fh = await open('output.gz', 'w');
  await pipeTo(from('Hello!'), compressGzip(), fh.writer({ autoClose: true }));

  // Sync pipeline with limit
  const src = await open('input.txt', 'r');
  const dst = await open('output.txt', 'w');
  const w = dst.writer({ limit: 1024 * 1024 }); // Max 1 MB
  await pipeTo(src.pull({ autoClose: true }), w);
  await w.end();
  await dst.close();
}

run().catch(console.error);
copy

filehandle[Symbol.asyncDispose]()#

调用 filehandle.close() 并返回一个在文件句柄关闭时兑现的 promise。

fsPromises.access(path[, mode])#

• path <string> | <Buffer> | <URL>
• mode <integer> 默认值： fs.constants.F_OK
• 返回：<Promise> 成功时以 undefined 兑现。

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

如果可访问性检查成功，则 promise 以无值兑现。如果任何可访问性检查失败，则 promise 以 <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');
}
copy

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

fsPromises.appendFile(path, data[, options])#

• path <string> | <Buffer> | <URL> | <FileHandle> 文件名或 <FileHandle>
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> 默认值： 'utf8'
  • mode <integer> 默认值： 0o666
  • flag <string> 参见 文件系统 flags 的支持。默认值： 'a'。
  • flush <boolean> 如果为 true，底层文件描述符在关闭前会被刷新。默认值： false。
• 返回：<Promise> 成功时以 undefined 兑现。

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

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

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

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

fsPromises.chmod(path, mode)#

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• 返回：<Promise> 成功时以 undefined 兑现。

更改文件的权限。

fsPromises.chown(path, uid, gid)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 返回：<Promise> 成功时以 undefined 兑现。

更改文件的所有权。

fsPromises.copyFile(src, dest[, mode])#

• src <string> | <Buffer> | <URL> 要复制的源文件名
• dest <string> | <Buffer> | <URL> 复制操作的目标文件名
• mode <integer> 指定复制操作行为的可选修饰符。可以创建由两个或多个值的按位或组成的掩码（例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）。默认值： 0。
  • fs.constants.COPYFILE_EXCL：如果 dest 已存在，则复制操作将失败。
  • fs.constants.COPYFILE_FICLONE：复制操作将尝试创建写时复制 (copy-on-write) 再链接 (reflink)。如果平台不支持写时复制，则使用回退复制机制。
  • fs.constants.COPYFILE_FICLONE_FORCE：复制操作将尝试创建写时复制再链接。如果平台不支持写时复制，则操作将失败。
• 返回：<Promise> 成功时以 undefined 兑现。

异步将 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');
}

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
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');
}
copy

fsPromises.cp(src, dest[, options])#

• src <string> | <URL> 要复制的源路径。
• dest <string> | <URL> 要复制到的目标路径。
• options <Object>
• dereference <boolean> 取消引用符号链接。默认值： false。
• errorOnExist <boolean> 当 force 为 false 且目标存在时，抛出错误。默认值： false。
• filter <Function> 用于过滤复制的文件/目录的函数。返回 true 以复制项目，返回 false 以忽略它。忽略目录时，其所有内容也将被跳过。也可以返回解析为 true 或 false 的 Promise。默认值： undefined。
  • src <string> 要复制的源路径。
  • dest <string> 要复制到的目标路径。
  • 返回：<boolean> | <Promise> 可强制转换为 boolean 的值或以此类值兑现的 Promise。
• force <boolean> 覆盖现有文件或目录。如果您将其设置为 false 且目标存在，复制操作将忽略错误。使用 errorOnExist 选项更改此行为。默认值： true。
• mode <integer> 复制操作的修饰符。默认值： 0。参见 fsPromises.copyFile() 的 mode 标志。
• preserveTimestamps <boolean> 当为 true 时，将保留来自 src 的时间戳。默认值： false。
• recursive <boolean> 递归复制目录。默认值： false
• verbatimSymlinks <boolean> 当为 true 时，将跳过符号链接的路径解析。默认值： false

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

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

fsPromises.glob(pattern[, options])#

• pattern <string> | <string[]>
• options <Object>
• cwd <string> | <URL> 当前工作目录。默认值： process.cwd()
• exclude <Function> | <string[]> 用于过滤掉文件/目录的函数或要排除的 glob 模式列表。如果提供了函数，则返回 true 以排除该项目，返回 false 以包含它。默认值： undefined。如果提供了字符串数组，则每个字符串都应是指定要排除路径的 glob 模式。注意：不支持否定模式（例如 '!foo.js'）。
• withFileTypes <boolean> 如果 glob 应将路径作为 Dirent 返回，则为 true，否则为 false。默认值： false。

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

for await (const entry of glob('**/*.js'))
  console.log(entry);
const { glob } = require('node:fs/promises');

(async () => {
  for await (const entry of glob('**/*.js'))
    console.log(entry);
})();
copy

fsPromises.lchmod(path, mode)#

• path <string> | <Buffer> | <URL>
• mode <integer>
• 返回：<Promise> 成功时以 undefined 兑现。

更改符号链接的权限。

此方法仅在 macOS 上实现。

fsPromises.lchown(path, uid, gid)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 返回：<Promise> 成功时以 undefined 兑现。

更改符号链接的所有权。

fsPromises.lutimes(path, atime, mtime)#

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 返回：<Promise> 成功时以 undefined 兑现。

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

fsPromises.link(existingPath, newPath)#

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 返回：<Promise> 成功时以 undefined 兑现。

创建从 existingPath 到 newPath 的新链接。详细信息请参考 POSIX link(2) 文档。

fsPromises.lstat(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
• bigint <boolean> 返回的 <fs.Stats> 对象中的数值是否应为 bigint。默认值： false。

等同于 fsPromises.stat()，除非 path 指向的是符号链接，这种情况下将对链接本身进行 stat 操作，而不是它所指向的文件。详细信息请参考 POSIX lstat(2) 文档。

fsPromises.mkdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 默认值: false
  • mode <string> | <integer> Windows 不支持。详见文件模式。 默认值: 0o777。
• 返回: <Promise> 成功时，如果 recursive 为 false，则兑现为 undefined；如果 recursive 为 true，则兑现为创建的第一个目录路径。

异步创建目录。

可选的 options 参数可以是一个整数，用于指定 mode（权限和粘滞位），或者是一个包含 mode 属性和 recursive 属性的对象，用于指示是否应创建父目录。当 path 是一个已存在的目录时，仅当 recursive 为 false 时，调用 fsPromises.mkdir() 才会导致拒绝。

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);
}
const { mkdir } = require('node:fs/promises');
const { join } = require('node:path');

async function makeDirectory() {
  const projectFolder = join(__dirname, 'test', 'project');
  const dirCreation = await mkdir(projectFolder, { recursive: true });

  console.log(dirCreation);
  return dirCreation;
}

makeDirectory().catch(console.error);
copy

fsPromises.mkdtemp(prefix[, options])#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值： 'utf8'
• 返回: <Promise> 兑现为包含新创建的临时目录文件系统路径的字符串。

创建一个唯一的临时目录。通过在提供的 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);
}
copy

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

fsPromises.mkdtempDisposable(prefix[, options])#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值： 'utf8'
• 返回: <Promise> 兑现为异步可处置（async-disposable）对象的 Promise。
  • path <string> 所创建目录的路径。
  • remove <AsyncFunction> 删除所创建目录的函数。
  • [Symbol.asyncDispose] <AsyncFunction> 与 remove 相同。

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

此函数及结果对象上的处置函数均为异步的，因此应与 await + await using 一起使用，例如：await using dir = await fsPromises.mkdtempDisposable('prefix')。

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

可选的 options 参数可以是一个指定编码的字符串，或者一个包含 encoding 属性的对象，用于指定使用的字符编码。

fsPromises.open(path, flags[, mode])#

• path <string> | <Buffer> | <URL>
• flags <string> | <number> 详见文件系统 flags 支持。 默认值: 'r'。
• mode <string> | <integer> 如果创建了文件，则设置文件模式（权限和粘滞位）。详见文件模式。 默认值: 0o666（可读可写）
• 返回: <Promise> 兑现为一个 <FileHandle> 对象。

打开一个 <FileHandle>。

详细信息请参考 POSIX open(2) 文档。

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

fsPromises.opendir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
• encoding <string> | <null> 默认值： 'utf8'
• bufferSize <number> 从目录读取时在内部缓冲的目录条目数。值越大，性能越好，但内存消耗也越高。 默认值: 32
• recursive <boolean> 解析出的 Dir 将是一个包含所有子文件和目录的 <AsyncIterable>。 默认值: false

异步打开一个用于迭代扫描的目录。详细信息请参考 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);
}
copy

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

fsPromises.readdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值： 'utf8'
  • withFileTypes <boolean> 默认值: false
  • recursive <boolean> 如果为 true，则递归读取目录内容。在递归模式下，它将列出所有文件、子文件和目录。 默认值: false。
• 返回: <Promise> 兑现为一个目录中文件名的数组，不包括 '.' 和 '..'。

读取目录的内容。

可选的 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);
}
copy

fsPromises.readFile(path[, options])#

• path <string> | <Buffer> | <URL> | <FileHandle> 文件名或 FileHandle
• options <Object> | <string>
  • encoding <string> | <null> 默认值： null
  • flag <string> 详见文件系统 flags 支持。 默认值: 'r'。
  • signal <AbortSignal> 允许中止正在进行的 readFile
• 返回: <Promise> 兑现为文件的内容。

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

如果未指定编码（使用 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);
}
const { readFile } = require('node:fs/promises');
const { resolve } = require('node:path');
async function logFile() {
  try {
    const filePath = resolve('./package.json');
    const contents = await readFile(filePath, { encoding: 'utf8' });
    console.log(contents);
  } catch (err) {
    console.error(err.message);
  }
}
logFile();
copy

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

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

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

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
}
copy

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

任何指定的 <FileHandle> 都必须支持读取。

fsPromises.readlink(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值： 'utf8'
• 返回: <Promise> 成功时兑现为 linkString。

读取由 path 引用的符号链接的内容。详细信息请参考 POSIX readlink(2) 文档。成功时，Promise 会以 linkString 兑现。

可选的 options 参数可以是一个指定编码的字符串，或者一个包含 encoding 属性的对象，用于指定返回的链接路径所使用的字符编码。如果 encoding 设置为 'buffer'，则返回的链接路径将作为 <Buffer> 对象传递。

fsPromises.realpath(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值： 'utf8'
• 返回: <Promise> 成功时兑现为解析后的路径。

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

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

可选的 options 参数可以是一个指定编码的字符串，或者一个包含 encoding 属性的对象，用于指定路径所使用的字符编码。如果 encoding 设置为 'buffer'，则返回的路径将作为 <Buffer> 对象传递。

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

fsPromises.rename(oldPath, newPath)#

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 返回：<Promise> 成功时以 undefined 兑现。

将 oldPath 重命名为 newPath。

fsPromises.rmdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object> 目前没有暴露任何选项。过去有 recursive、maxBusyTries 和 emfileWait 的选项，但它们已被弃用并移除。为了向后兼容，仍然接受 options 参数，但它不会被使用。
• 返回：<Promise> 成功时以 undefined 兑现。

移除由 path 标识的目录。

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

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

fsPromises.rm(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
• force <boolean> 如果为 true，则在 path 不存在时忽略异常。 默认值: false。
• maxRetries <integer> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 错误，Node.js 将以线性退避等待的方式重试该操作，每次尝试的等待时间比上一次长 retryDelay 毫秒。此选项表示重试次数。如果 recursive 选项不为 true，则忽略此选项。 默认值: 0。
• recursive <boolean> 如果为 true，则执行递归目录移除。在递归模式下，失败的操作会进行重试。 默认值: false。
• retryDelay <integer> 重试之间等待的毫秒数。如果 recursive 选项不为 true，则忽略此选项。 默认值: 100。

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

fsPromises.stat(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
• bigint <boolean> 返回的 <fs.Stats> 对象中的数值是否应为 bigint。默认值： false。
• throwIfNoEntry <boolean> 如果没有文件系统条目存在时，是否抛出异常，而不是返回 undefined。 默认值: true。

fsPromises.statfs(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
• bigint <boolean> 返回的 <fs.StatFs> 对象中的数值是否应为 bigint 类型。 默认值: false。

fsPromises.symlink(target, path[, type])#

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> 默认值: null
• 返回：<Promise> 成功时以 undefined 兑现。

创建符号链接。

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

fsPromises.truncate(path[, len])#

• path <string> | <Buffer> | <URL>
• len <integer> 默认值： 0
• 返回：<Promise> 成功时以 undefined 兑现。

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

fsPromises.unlink(path)#

• path <string> | <Buffer> | <URL>
• 返回：<Promise> 成功时以 undefined 兑现。

如果 path 引用符号链接，则删除该链接，而不影响该链接所指向的文件或目录。如果 path 引用非符号链接的文件路径，则删除该文件。详细信息请参考 POSIX unlink(2) 文档。

fsPromises.utimes(path, atime, mtime)#

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 返回：<Promise> 成功时以 undefined 兑现。

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

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

• 值可以是表示 Unix 纪元时间的数字、Date 对象，或类似于 '123456789.0' 的数值字符串。
• 如果值无法转换为数字，或者为 NaN、Infinity 或 -Infinity，则会抛出 Error。

fsPromises.watch(filename[, options])#

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> 指示只要有文件在被监视，进程是否应继续运行。 默认值: true。
  • recursive <boolean> 指示是否应监视所有子目录，还是仅监视当前目录。当指定了目录时，这在受支持的平台上有效（详见注意事项）。 默认值: false。
  • encoding <string> 指定用于传递给监听器的文件名的字符编码。 默认值: 'utf8'。
  • signal <AbortSignal> 一个用于指示监视器何时停止的 <AbortSignal>。
  • maxQueue <number> 指定在返回的 <AsyncIterator> 迭代之间排队的事件数。 默认值: 2048。
  • overflow <string> 当排队的事件多于 maxQueue 允许的数量时，设为 'ignore' 或 'throw'。'ignore' 表示丢弃溢出事件并发出警告，而 'throw' 表示抛出异常。 默认值: 'ignore'。
  • ignore <string> | <RegExp> | <Function> | <Array> 要忽略的模式。字符串是 glob 模式（使用 minimatch），RegExp 模式会针对文件名进行测试，而函数会接收文件名并返回 true 以忽略。 默认值: undefined。
• 返回: <AsyncIterator>，包含以下属性的对象
  • eventType <string> 变更的类型
  • filename <string> | <Buffer> | <null> 发生变更的文件名。

返回一个异步迭代器，监视 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;
  }
})();
copy

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

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

fsPromises.writeFile(file, data[, options])#

• file <string> | <Buffer> | <URL> | <FileHandle> 文件名或 FileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> 默认值： 'utf8'
  • mode <integer> 默认值： 0o666
  • flag <string> 详见文件系统 flags 支持。 默认值: 'w'。
  • flush <boolean> 如果所有数据都成功写入文件，且 flush 为 true，则使用 filehandle.sync() 来冲刷数据。 默认值: false。
  • signal <AbortSignal> 允许中止正在进行的 writeFile
• 返回：<Promise> 成功时以 undefined 兑现。

将数据异步写入文件，如果文件已存在，则替换该文件。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 });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
}
copy

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

fsPromises.constants#

• 类型：<Object>

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

回调 API#

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

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

fs.access(path[, mode], callback)#

• path <string> | <Buffer> | <URL>
• mode <integer> 默认值： fs.constants.F_OK
• callback <Function>
  • err <Error>

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

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

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

const file = 'package.json';

// Check if the file exists in the current directory.
access(file, constants.F_OK, (err) => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
});

// Check if the file is readable.
access(file, constants.R_OK, (err) => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`);
});

// Check if the file is writable.
access(file, constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
});

// Check if the file is readable and writable.
access(file, constants.R_OK | constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
});
copy

不要在调用 fs.open()、fs.readFile() 或 fs.writeFile() 之前使用 fs.access() 检查文件的可访问性。这样做会引入竞态条件，因为其他进程可能在两次调用之间更改文件的状态。相反，用户代码应直接打开/读取/写入文件，并在文件无法访问时处理引发的错误。

写入（不推荐）

import { access, open, close } from 'node:fs';

access('myfile', (err) => {
  if (!err) {
    console.error('myfile already exists');
    return;
  }

  open('myfile', 'wx', (err, fd) => {
    if (err) throw err;

    try {
      writeMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
});
copy

写入（推荐）

import { open, close } from 'node:fs';

open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  try {
    writeMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
});
copy

读取（不推荐）

import { access, open, close } from 'node:fs';
access('myfile', (err) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  open('myfile', 'r', (err, fd) => {
    if (err) throw err;

    try {
      readMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
});
copy

读取（推荐）

import { open, close } from 'node:fs';

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  try {
    readMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
});
copy

上面的“不推荐”示例检查可访问性，然后使用文件；“推荐”示例更好，因为它们直接使用文件并处理可能出现的错误。

通常，仅当文件不会被直接使用时才检查文件的可访问性，例如当其可访问性是来自另一个进程的信号时。

在 Windows 上，目录上的访问控制策略 (ACL) 可能会限制对文件或目录的访问。然而，fs.access() 函数不检查 ACL，因此即使 ACL 限制用户读取或写入，它也可能报告路径是可访问的。

fs.appendFile(path, data[, options], callback)#

• path <string> | <Buffer> | <URL> | <number> 文件名或文件描述符
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> 默认值： 'utf8'
  • mode <integer> 默认值： 0o666
  • flag <string> 参见 文件系统 flags 的支持。默认值： 'a'。
  • flush <boolean> 如果为 true，底层文件描述符在关闭前会被刷新。默认值： false。
• callback <Function>
  • err <Error>

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

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

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', (err) => {
  if (err) throw err;
  console.log('The "data to append" was appended to file!');
});
copy

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

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', 'utf8', callback);
copy

path 可以指定为一个已打开用于追加的文件描述符（使用 fs.open() 或 fs.openSync()）。文件描述符不会自动关闭。

import { open, close, appendFile } from 'node:fs';

function closeFd(fd) {
  close(fd, (err) => {
    if (err) throw err;
  });
}

open('message.txt', 'a', (err, fd) => {
  if (err) throw err;

  try {
    appendFile(fd, 'data to append', 'utf8', (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    throw err;
  }
});
copy

fs.chmod(path, mode, callback)#

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

异步更改文件的权限。除了可能的异常外，没有其他参数传递给完成回调。

详细信息请参考 POSIX chmod(2) 文档。

import { chmod } from 'node:fs';

chmod('my_file.txt', 0o775, (err) => {
  if (err) throw err;
  console.log('The permissions for file "my_file.txt" have been changed!');
});
copy

文件模式#

fs.chmod() 和 fs.chmodSync() 方法中使用的 mode 参数是一个数值掩码，通过对以下常量进行逻辑 OR 运算创建

构建 mode 的一种更简单的方法是使用三个八进制数字序列（例如 765）。最左侧的数字（示例中的 7）指定文件所有者的权限。中间的数字（示例中的 6）指定组的权限。最右侧的数字（示例中的 5）指定其他人的权限。

例如，八进制值 0o765 表示

• 所有者可以读取、写入和执行文件。
• 组可以读取和写入文件。
• 其他人可以读取和执行文件。

当在期望文件模式的地方使用原始数字时，任何大于 0o777 的值都可能导致不支持一致工作的特定于平台的行为。因此，诸如 S_ISVTX、S_ISGID 或 S_ISUID 等常量没有在 fs.constants 中暴露。

注意事项：在 Windows 上只能更改写权限，并且没有实现组、所有者或其他人的权限区分。

fs.chown(path, uid, gid, callback)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

异步更改文件的所有者和组。除了可能的异常外，没有其他参数传递给完成回调。

详细信息请参考 POSIX chown(2) 文档。

fs.close(fd[, callback])#

• fd <integer>
• callback <Function>
  • err <Error>

关闭文件描述符。除了可能的异常外，没有其他参数传递给完成回调。

在任何当前通过其他 fs 操作使用的文件描述符 (fd) 上调用 fs.close() 可能导致未定义的行为。

详细信息请参考 POSIX close(2) 文档。

fs.copyFile(src, dest[, mode], callback)#

• src <string> | <Buffer> | <URL> 要复制的源文件名
• dest <string> | <Buffer> | <URL> 复制操作的目标文件名
• mode <integer> 复制操作的修饰符。 默认值: 0。
• callback <Function>
  • err <Error>

异步将 src 复制到 dest。默认情况下，如果 dest 已存在，它将被覆盖。除了可能的异常外，没有其他参数传递给回调函数。Node.js 不保证复制操作的原子性。如果目标文件打开写入后发生错误，Node.js 将尝试移除目标文件。

mode 是一个可选整数，指定复制操作的行为。可以创建一个由两个或多个值按位 OR 组成的掩码（例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）。

• fs.constants.COPYFILE_EXCL：如果 dest 已存在，则复制操作将失败。
• fs.constants.COPYFILE_FICLONE：复制操作将尝试创建写时复制 (copy-on-write) 再链接 (reflink)。如果平台不支持写时复制，则使用回退复制机制。
• fs.constants.COPYFILE_FICLONE_FORCE：复制操作将尝试创建写时复制再链接。如果平台不支持写时复制，则操作将失败。

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

function callback(err) {
  if (err) throw err;
  console.log('source.txt was copied to destination.txt');
}

// destination.txt will be created or overwritten by default.
copyFile('source.txt', 'destination.txt', callback);

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback);
copy

fs.cp(src, dest[, options], callback)#

• src <string> | <URL> 要复制的源路径。
• dest <string> | <URL> 要复制到的目标路径。
• options <Object>
• dereference <boolean> 取消引用符号链接。默认值： false。
• errorOnExist <boolean> 当 force 为 false 且目标存在时，抛出错误。默认值： false。
• filter <Function> 用于过滤复制的文件/目录的函数。返回 true 以复制项目，返回 false 以忽略它。忽略目录时，其所有内容也将被跳过。也可以返回解析为 true 或 false 的 Promise。默认值： undefined。
  • src <string> 要复制的源路径。
  • dest <string> 要复制到的目标路径。
  • 返回：<boolean> | <Promise> 可强制转换为 boolean 的值或以此类值兑现的 Promise。
• force <boolean> 覆盖现有文件或目录。如果您将其设置为 false 且目标存在，复制操作将忽略错误。使用 errorOnExist 选项更改此行为。默认值： true。
• mode <integer> 复制操作的修饰符。 默认值: 0。详见 fs.copyFile() 的 mode 标志。
• preserveTimestamps <boolean> 当为 true 时，将保留来自 src 的时间戳。默认值： false。
• recursive <boolean> 递归复制目录。默认值： false
• verbatimSymlinks <boolean> 当为 true 时，将跳过符号链接的路径解析。默认值： false

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

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

fs.createReadStream(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> 详见文件系统 flags 支持。 默认值: 'r'。
  • encoding <string> 默认值： null
  • fd <integer> | <FileHandle> 默认值: null
  • mode <integer> 默认值： 0o666
  • autoClose <boolean> 默认值： true
  • emitClose <boolean> 默认值： true
  • start <integer>
  • end <integer> 默认值： Infinity
  • highWaterMark <integer> 默认值： 64 * 1024
  • fs <Object> | <null> 默认值: null
  • signal <AbortSignal> | <null> 默认值: null
• 返回：<fs.ReadStream>