Node.js v20.20.6 文档

Promise 示例#>

【Promise example】

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

【Promise-based operations return a promise that is fulfilled when the asynchronous operation is complete.】

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

回调示例#>

【Callback example】

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

【The callback form takes a completion callback function as its last argument and invokes the operation asynchronously. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation is completed successfully, then the first argument is null or 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');
});拷贝

当需要最大化性能（包括执行时间和内存分配）时，node:fs 模块 API 的基于回调的版本相比使用 Promise API 更为可取。

【The callback-based versions of the node:fs module APIs are preferable over the use of the promise APIs when maximal performance (both in terms of execution time and memory allocation) is required.】

同步示例#>

【Synchronous example】

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

【The synchronous APIs block the Node.js event loop and further JavaScript execution until the operation is complete. Exceptions are thrown immediately and can be handled using try…catch, or can be allowed to bubble up.】

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
}拷贝

Promise API#>

【Promises API】

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

【The fs/promises API provides asynchronous file system methods that return promises.】

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

【The promise APIs use the underlying Node.js threadpool to perform file system operations off the event loop thread. These operations are not synchronized or threadsafe. Care must be taken when performing multiple concurrent modifications on the same file or data corruption may occur.】

类：FileHandle#>

【Class: FileHandle】

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

【A <FileHandle> object is an object wrapper for a numeric file descriptor.】

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

【Instances of the <FileHandle> object are created by the fsPromises.open() method.】

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

【All <FileHandle> objects are <EventEmitter>s.】

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

【If a <FileHandle> is not closed using the filehandle.close() method, it will try to automatically close the file descriptor and emit a process warning, helping to prevent memory leaks. Please do not rely on this behavior because it can be unreliable and the file may not be closed. Instead, always explicitly close <FileHandle>s. Node.js may change this behavior in the future.】

事件：'close'#>

【Event: 'close'】

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

【The 'close' event is emitted when the <FileHandle> has been closed and can no longer be used.】

filehandle.appendFile(data[, options])#>

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> 默认值: 'utf8'
  • flush <boolean> 如果为 true，在关闭底层文件描述符之前会先刷新它。默认值： false。
• 返回：<Promise> 成功时返回 undefined。

filehandle.writeFile() 的别名。

【Alias of filehandle.writeFile().】

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

【When operating on file handles, the mode cannot be changed from what it was set to with fsPromises.open(). Therefore, this is equivalent to filehandle.writeFile().】

filehandle.chmod(mode)#>

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

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

【Modifies the permissions on the file. See chmod(2).】

filehandle.chown(uid, gid)#>

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

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

【Changes the ownership of the file. A wrapper for chown(2).】

filehandle.close()#>

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

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

【Closes the file handle after waiting for any pending operation on the handle to complete.】

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

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

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
• 返回: <fs.ReadStream>

options 可以包含 start 和 end 值，用于读取以下范围内的字节是文件而不是整个文件。start 和 end 都是包容性的， 从0开始计数，允许的值在 [0, Number.MAX_SAFE_INTEGER] 范围。如果 start 是 省略或 undefined，fs.createReadStream() 顺序读取于 当前文件位置。encoding 可以是以下任何一种被接受的 <Buffer>。

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

【If the FileHandle points to a character device that only supports blocking reads (such as keyboard or sound card), read operations do not finish until data is available. This can prevent the process from exiting and the stream from closing naturally.】

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

【By default, the stream will emit a 'close' event after it has been destroyed. Set the emitClose option to false to change this behavior.】

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); 拷贝

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

【If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. If autoClose is set to true (default behavior), on 'error' or 'end' the file descriptor will be closed automatically.】

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

【An example to read the last 10 bytes of a file which is 100 bytes long:】

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

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

filehandle.createWriteStream([options])#>

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

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

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

【If autoClose is set to true (default behavior) on 'error' or 'finish' the file descriptor will be closed automatically. If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak.】

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

【By default, the stream will emit a 'close' event after it has been destroyed. Set the emitClose option to false to change this behavior.】

filehandle.datasync()#>

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

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

【Forces all currently queued I/O operations associated with the file to the operating system's synchronized I/O completion state. Refer to the POSIX fdatasync(2) documentation for details.】

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

【Unlike filehandle.sync this method does not flush modified metadata.】

filehandle.fd#>

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

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 参数的引用。

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

【Reads data from the file and stores that in the given buffer.】

如果文件没有被同时修改，当读取的字节数为零时，就到达了文件末尾。

【If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero.】

filehandle.read([options])#>

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

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

【Reads data from the file and stores that in the given buffer.】

如果文件没有被同时修改，当读取的字节数为零时，就到达了文件末尾。

【If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero.】

filehandle.read(buffer[, options])#>

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

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

【Reads data from the file and stores that in the given buffer.】

如果文件没有被同时修改，当读取的字节数为零时，就到达了文件末尾。

【If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero.】

filehandle.readableWebStream([options])#>

• options <Object>
  • type <string> | <undefined> 是否打开普通流或 'bytes' 流。 默认值: undefined
• 返回：<ReadableStream>

返回一个可用于读取文件数据的 ReadableStream。

【Returns a ReadableStream that may be used to read the files data.】

如果此方法被调用超过一次，或者在 FileHandle 已关闭或正在关闭之后调用，将会抛出错误。

【An error will be thrown if this method is called more than once or is called after the FileHandle is closed or closing.】

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();
})();拷贝

虽然 ReadableStream 会读取文件直至完成，但它不会自动关闭 FileHandle。用户代码仍然必须调用 fileHandle.close() 方法。

【While the ReadableStream will read the file to completion, it will not close the FileHandle automatically. User code must still call the fileHandle.close() method.】

filehandle.readFile(options)#>

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

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

【Asynchronously reads the entire contents of a file.】

如果 options 是一个字符串，那么它指定了 encoding。

【If options is a string, then it specifies the encoding.】

<FileHandle> 必须支持阅读。

【The <FileHandle> has to support reading.】

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

【If one or more filehandle.read() calls are made on a file handle and then a filehandle.readFile() call is made, the data will be read from the current position till the end of the file. It doesn't always read from the beginning of the file.】

filehandle.readLines([options])#>

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

创建 readline 接口并对文件进行流式处理的便捷方法。有关选项，请参见 filehandle.createReadStream()。

【Convenience method to create a readline interface and stream over the file. See filehandle.createReadStream() for the options.】

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);
  }
})();拷贝

filehandle.readv(buffers[, position])#>

• '缓冲区' <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> 数据应从文件开头的偏移量开始读取。如果 position 不是 number 类型，数据将从当前位置读取。默认值: null
• 返回：<Promise> 在成功时返回一个包含两个属性的对象：
  • bytesRead <integer> 读取的字节数
  • '缓冲区' <Buffer[]> | <TypedArray[]> | <DataView[]> 属性，包含对“缓冲区”输入的引用。

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

【Read from a file and write to an array of <ArrayBufferView>s】

filehandle.stat([options])#>

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

filehandle.sync()#>

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

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

【Request that all data for the open file descriptor is flushed to the storage device. The specific implementation is operating system and device specific. Refer to the POSIX fsync(2) documentation for more detail.】

filehandle.truncate(len)#>

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

截断文件。

【Truncates the file.】

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

【If the file was larger than len bytes, only the first len bytes will be retained in the file.】

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

【The following example retains only the first four bytes of the file:】

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''）：

【If the file previously was shorter than len bytes, it is extended, and the extended part is filled with null bytes ('\0'):】

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

【If len is negative then 0 will be used.】

filehandle.utimes(atime, mtime)#>

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

更改 <FileHandle> 所引用对象的文件系统时间戳，成功时不带任何参数地完成承诺。

【Change the file system timestamps of the object referenced by the <FileHandle> then fulfills the promise with no arguments upon success.】

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 写入文件。

【Write buffer to the file.】

这个 promise 是通过一个包含两个属性的对象来实现的：

【The promise is fulfilled with an object containing two properties:】

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

在同一个文件上多次使用 filehandle.write() 是不安全的，如果不等待 Promise 被解决（或被拒绝）。对于这种情况，请使用 filehandle.createWriteStream()。

【It is unsafe to use filehandle.write() multiple times on the same file without waiting for the promise to be fulfilled (or rejected). For this scenario, use filehandle.createWriteStream().】

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

【On Linux, positional writes do not work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.】

filehandle.write(buffer[, options])#>

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

将 buffer 写入文件。

【Write buffer to the file.】

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

【Similar to the above filehandle.write function, this version takes an optional options object. If no options object is specified, it will default with the above values.】

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

• string <string>
• position <integer> | <null> 从文件开头开始偏移的位置，string 中的数据应写入该位置。如果 position 不是 number 类型，则数据将写入当前的位置。详情参见 POSIX pwrite(2) 文档。默认值: null
• encoding <string> 预期的字符串编码。默认值： 'utf8'
• 返回：<Promise>

将 string 写入文件。如果 string 不是字符串，承诺将被拒绝并返回一个错误。

【Write string to the file. If string is not a string, the promise is rejected with an error.】

这个 promise 是通过一个包含两个属性的对象来实现的：

【The promise is fulfilled with an object containing two properties:】

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

在同一个文件上多次使用 filehandle.write() 是不安全的，如果不等待 Promise 被解决（或被拒绝）。对于这种情况，请使用 filehandle.createWriteStream()。

【It is unsafe to use filehandle.write() multiple times on the same file without waiting for the promise to be fulfilled (or rejected). For this scenario, use filehandle.createWriteStream().】

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

【On Linux, positional writes do not work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.】

filehandle.writeFile(data, options)#>

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> 当 data 是字符串时，预期的字符编码。默认值： 'utf8'
• 返回：<Promise>

异步地将数据写入文件，如果文件已存在则替换它。data 可以是字符串、缓冲区、<AsyncIterable> 或 <Iterable> 对象。操作成功时，Promise 将不带任何参数地完成。

【Asynchronously writes data to a file, replacing the file if it already exists. data can be a string, a buffer, an <AsyncIterable>, or an <Iterable> object. The promise is fulfilled with no arguments upon success.】

如果 options 是一个字符串，那么它指定了 encoding。

【If options is a string, then it specifies the encoding.】

<FileHandle> 必须支持写入。

【The <FileHandle> has to support writing.】

在同一个文件上多次使用 filehandle.writeFile() 是不安全的，除非等待该 promise 被完成（或拒绝）。

【It is unsafe to use filehandle.writeFile() multiple times on the same file without waiting for the promise to be fulfilled (or rejected).】

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

【If one or more filehandle.write() calls are made on a file handle and then a filehandle.writeFile() call is made, the data will be written from the current position till the end of the file. It doesn't always write from the beginning of the file.】

filehandle.writev(buffers[, position])#>

• '缓冲区' <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> 数据应从文件开头的偏移量开始写入 buffers。如果 position 不是 number，数据将写入当前位置。默认值： null
• 返回：<Promise>

将 <ArrayBufferView> 数组写入文件。

【Write an array of <ArrayBufferView>s to the file.】

这个 promise 是通过一个包含两个属性的对象来实现的：

【The promise is fulfilled with an object containing a two properties:】

• bytesWritten <integer> 写入的字节数
• '缓冲区' <Buffer[]> | <TypedArray[]> | <DataView[]> 对“缓冲区”输入的引用。

在同一个文件上多次调用 writev() 而不等待 Promise 被完成（或拒绝）是不安全的。

【It is unsafe to call writev() multiple times on the same file without waiting for the promise to be fulfilled (or rejected).】

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

【On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.】

filehandle[Symbol.asyncDispose]()#>

filehandle.close() 的别名。

【An alias for filehandle.close().】

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 的可能取值。

【Tests a user's permissions for the file or directory specified by path. The mode argument is an optional integer that specifies the accessibility checks to be performed. mode should be either the value fs.constants.F_OK or a mask consisting of the bitwise OR of any of fs.constants.R_OK, fs.constants.W_OK, and fs.constants.X_OK (e.g. fs.constants.W_OK | fs.constants.R_OK). Check File access constants for possible values of mode.】

如果可访问性检查成功，Promise 将以无值的形式被实现。如果任何可访问性检查失败，Promise 将被一个 <Error> 对象拒绝。以下示例检查当前进程是否可以读取和写入文件 /etc/passwd。

【If the accessibility check is successful, the promise is fulfilled with no value. If any of the accessibility checks fail, the promise is rejected with an <Error> object. The following example checks if the file /etc/passwd can be read and written by the current process.】

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() 来检查文件的可访问性是不推荐的。这会引入竞争条件，因为在两次调用之间，其他进程可能会改变文件的状态。相反，用户代码应该直接打开/读取/写入文件，并处理文件不可访问时产生的错误。

【Using fsPromises.access() to check for the accessibility of a file before calling fsPromises.open() is not recommended. Doing so introduces a race condition, since other processes may change the file's state between the two calls. Instead, user code should open/read/write the file directly and handle the error raised if the file is not accessible.】

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>。

【Asynchronously append data to a file, creating the file if it does not yet exist. data can be a string or a <Buffer>.】

如果 options 是一个字符串，那么它指定了 encoding。

【If options is a string, then it specifies the encoding.】

mode 选项只会影响新创建的文件。详情请参见 fs.open()。

【The mode option only affects the newly created file. See fs.open() for more details.】

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

【The path may be specified as a <FileHandle> that has been opened for appending (using fsPromises.open()).】

fsPromises.chmod(path, mode)#>

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

更改文件的权限。

【Changes the permissions of a file.】

fsPromises.chown(path, uid, gid)#>

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

更改文件的所有权。

【Changes the ownership of a file.】

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

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

异步地将 src 复制到 dest。默认情况下，如果 dest 已经存在，会被覆盖。

【Asynchronously copies src to dest. By default, dest is overwritten if it already exists.】

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

【No guarantees are made about the atomicity of the copy operation. If an error occurs after the destination file has been opened for writing, an attempt will be made to remove the destination.】

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');
} 拷贝

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
• 返回：<Promise> 成功时返回 undefined。

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

【Asynchronously copies the entire directory structure from src to dest, including subdirectories and files.】

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

【When copying a directory to another directory, globs are not supported and behavior is similar to cp dir1/ dir2/.】

fsPromises.lchmod(path, mode)#>

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

更改符号链接的权限。

【Changes the permissions on a symbolic link.】

此方法仅在 macOS 上实现。

【This method is only implemented on macOS.】

fsPromises.lchown(path, uid, gid)#>

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

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

【Changes the ownership on a symbolic link.】

fsPromises.lutimes(path, atime, mtime)#>

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

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

【Changes the access and modification times of a file in the same way as fsPromises.utimes(), with the difference that if the path refers to a symbolic link, then the link is not dereferenced: instead, the timestamps of the symbolic link itself are changed.】

fsPromises.link(existingPath, newPath)#>

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

在 existingPath 与 newPath 之间创建一个新链接。有关详细信息，请参阅 POSIX link(2) 文档。

【Creates a new link from the existingPath to the newPath. See the POSIX link(2) documentation for more detail.】

fsPromises.lstat(path[, options])#>

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返回的 <fs.Stats> 对象中的数值是否应为 bigint。默认值： false。
• 返回：<Promise> 使用给定符号链接 path 的 <fs.Stats> 对象完成。

等同于 fsPromises.stat()，除非 path 指向符号链接，在这种情况下，会对链接本身进行状态获取，而不是它指向的文件。更多细节请参考 POSIX lstat(2) 文档。

【Equivalent to fsPromises.stat() unless path refers to a symbolic link, in which case the link itself is stat-ed, not the file that it refers to. Refer to the POSIX lstat(2) document for more detail.】

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，则返回创建的第一个目录路径。

异步地创建目录。

【Asynchronously creates a directory.】

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

【The optional options argument can be an integer specifying mode (permission and sticky bits), or an object with a mode property and a recursive property indicating whether parent directories should be created. Calling fsPromises.mkdir() when path is a directory that exists results in a rejection only when recursive is false.】

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);拷贝

fsPromises.mkdtemp(prefix[, options])#>

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

创建一个唯一的临时目录。通过在提供的 prefix 后附加六个随机字符来生成唯一的目录名。由于平台差异，避免在 prefix 中使用尾随的 X 字符。一些平台，特别是 BSD 系统，可能会返回超过六个随机字符，并将 prefix 尾随的 X 字符替换为随机字符。

【Creates a unique temporary directory. A unique directory name is generated by appending six random characters to the end of the provided prefix. Due to platform inconsistencies, avoid trailing X characters in prefix. Some platforms, notably the BSDs, can return more than six random characters, and replace trailing X characters in prefix with random characters.】

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

【The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use.】

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）结尾。

【The fsPromises.mkdtemp() method will append the six randomly selected characters directly to the prefix string. For instance, given a directory /tmp, if the intention is to create a temporary directory within /tmp, the prefix must end with a trailing platform-specific path separator (require('node:path').sep).】

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

• path <string> | <Buffer> | <URL>
• flags <string> | <number> 参见 文件系统 flags 支持。 默认值： 'r'。
• mode <string> | <integer> 如果文件被创建，设置文件模式（权限和粘滞位）。默认值: 0o666（可读可写）
• 返回：<Promise> 以 <FileHandle> 对象完成。

打开一个 <FileHandle>。

【Opens a <FileHandle>.】

有关更多详细信息，请参阅 POSIX open(2) 文档。

【Refer to the POSIX open(2) documentation for more detail.】

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

【Some characters (< > : " / \ | ? *) are reserved under Windows as documented by Naming Files, Paths, and Namespaces. Under NTFS, if the filename contains a colon, Node.js will open a file system stream, as described by this MSDN page.】

fsPromises.opendir(path[, options])#>

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> 默认值: 'utf8'
  • bufferSize <number> 从目录读取时内部缓冲的目录项数量。数值越大，性能越好，但内存使用也越高。默认值： 32
  • recursive <boolean> 已解析的 Dir 将是一个 <AsyncIterable>，包含所有子文件和子目录。默认值： false
• 返回：<Promise> 使用 <fs.Dir> 完成。

异步打开目录以进行迭代扫描。有关更多详细信息，请参阅 POSIX opendir(3) 文档。

【Asynchronously open a directory for iterative scanning. See the POSIX opendir(3) documentation for more detail.】

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

【Creates an <fs.Dir>, which contains all further functions for reading from and cleaning up the directory.】

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

【The encoding option sets the encoding for the path while opening the directory and subsequent read operations.】

使用异步迭代的示例：

【Example using async iteration:】

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> 对象将在迭代器退出后自动关闭。

【When using the async iterator, the <fs.Dir> object will be automatically closed after the iterator exits.】

fsPromises.readdir(path[, options])#>

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

读取目录的内容。

【Reads the contents of a directory.】

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

【The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the filenames. If the encoding is set to 'buffer', the filenames returned will be passed as <Buffer> objects.】

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

【If options.withFileTypes is set to true, the returned array will contain <fs.Dirent> objects.】

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])#>

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

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

【Asynchronously reads the entire contents of a file.】

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

【If no encoding is specified (using options.encoding), the data is returned as a <Buffer> object. Otherwise, the data will be a string.】

如果 options 是字符串，那么它指定了编码。

【If options is a string, then it specifies the encoding.】

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

【When the path is a directory, the behavior of fsPromises.readFile() is platform-specific. On macOS, Linux, and Windows, the promise will be rejected with an error. On FreeBSD, a representation of the directory's contents will be returned.】

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

【An example of reading a package.json file located in the same directory of the running code:】

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();拷贝

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

【It is possible to abort an ongoing readFile using an <AbortSignal>. If a request is aborted the promise returned is rejected with an 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);
} 拷贝

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

【Aborting an ongoing request does not abort individual operating system requests but rather the internal buffering fs.readFile performs.】

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

【Any specified <FileHandle> has to support reading.】

fsPromises.readlink(path[, options])#>

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

读取由 path 指向的符号链接的内容。有关更多详细信息，请参阅 POSIX readlink(2) 文档。成功时，承诺将返回 linkString。

【Reads the contents of the symbolic link referred to by path. See the POSIX readlink(2) documentation for more detail. The promise is fulfilled with the linkString upon success.】

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

【The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the link path returned. If the encoding is set to 'buffer', the link path returned will be passed as a <Buffer> object.】

fsPromises.realpath(path[, options])#>

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

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

【Determines the actual location of path using the same semantics as the fs.realpath.native() function.】

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

【Only paths that can be converted to UTF8 strings are supported.】

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

【The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the path. If the encoding is set to 'buffer', the path returned will be passed as a <Buffer> object.】

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

【On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on /proc in order for this function to work. Glibc does not have this restriction.】

fsPromises.rename(oldPath, newPath)#>

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

将 oldPath 重命名为 newPath。

【Renames oldPath to newPath.】

fsPromises.rmdir(path[, options])#>

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 错误，Node.js 会以线性回退的方式重试操作，每次重试等待时间比上次增加 retryDelay 毫秒。此选项表示重试次数。如果 recursive 选项不是 true，此选项将被忽略。默认值： 0。
  • recursive <boolean> 如果为 true，则执行递归目录删除。在递归模式下，操作在失败时会重试。默认值： false。 已弃用。
  • retryDelay <integer> 重试之间等待的时间，以毫秒为单位。如果 recursive 选项不为 true，则此选项将被忽略。默认值: 100。
• 返回：<Promise> 成功时返回 undefined。

删除由 path 指定的目录。

【Removes the directory identified by path.】

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

【Using fsPromises.rmdir() on a file (not a directory) results in the promise being rejected with an ENOENT error on Windows and an ENOTDIR error on POSIX.】

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

【To get a behavior similar to the rm -rf Unix command, use fsPromises.rm() with options { recursive: true, force: true }.】

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。
• 返回：<Promise> 成功时返回 undefined。

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

【Removes files and directories (modeled on the standard POSIX rm utility).】

fsPromises.stat(path[, options])#>

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

fsPromises.statfs(path[, options])#>

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返回的 <fs.StatFs> 对象中的数值是否应为 bigint。默认值： false。
• 返回：<Promise> 使用给定 path 的 <fs.StatFs> 对象完成。

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

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

创建符号链接。

【Creates a symbolic link.】

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

【The type argument is only used on Windows platforms and can be one of 'dir', 'file', or 'junction'. If the type argument is not a string, Node.js will autodetect target type and use 'file' or 'dir'. If the target does not exist, 'file' will be used. Windows junction points require the destination path to be absolute. When using 'junction', the target argument will automatically be normalized to absolute path. Junction points on NTFS volumes can only point to directories.】

fsPromises.truncate(path[, len])#>

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

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

【Truncates (shortens or extends the length) of the content at path to len bytes.】

fsPromises.unlink(path)#>

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

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

【If path refers to a symbolic link, then the link is removed without affecting the file or directory to which that link refers. If the path refers to a file path that is not a symbolic link, the file is deleted. See the POSIX unlink(2) documentation for more detail.】

fsPromises.utimes(path, atime, mtime)#>

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

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

【Change the file system timestamps of the object referenced by path.】

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

【The atime and mtime arguments follow these rules:】

• 值可以是表示 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>，用来指示观察者何时应该停止。
• 返回：具有以下属性的 <AsyncIterator> 个对象：
  • eventType <string> 变更类型
  • filename <string> | <Buffer> | <null> 文件名已更改。

返回一个异步迭代器，用于监视 filename 的变化，其中 filename 可以是文件或目录。

【Returns an async iterator that watches for changes on filename, where filename is either a file or a directory.】

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'。

【On most platforms, 'rename' is emitted whenever a filename appears or disappears in the directory.】

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

【All the caveats for fs.watch() also apply to 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> 对象。

【Asynchronously writes data to a file, replacing the file if it already exists. data can be a string, a buffer, an <AsyncIterable>, or an <Iterable> object.】

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

【The encoding option is ignored if data is a buffer.】

如果 options 是字符串，那么它指定了编码。

【If options is a string, then it specifies the encoding.】

mode 选项只会影响新创建的文件。详情请参见 fs.open()。

【The mode option only affects the newly created file. See fs.open() for more details.】

任何指定的 <FileHandle> 都必须支持写入。

【Any specified <FileHandle> has to support writing.】

在不等待 Promise 完成的情况下，多次使用 fsPromises.writeFile() 写入同一个文件是不安全的。

【It is unsafe to use fsPromises.writeFile() multiple times on the same file without waiting for the promise to be settled.】

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

【Similarly to fsPromises.readFile - fsPromises.writeFile is a convenience method that performs multiple write calls internally to write the buffer passed to it. For performance sensitive code consider using fs.createWriteStream() or filehandle.createWriteStream().】

可以使用 <AbortSignal> 来取消 fsPromises.writeFile()。取消是“尽最大努力”的，有些数据仍可能会被写入。

【It is possible to use an <AbortSignal> to cancel an fsPromises.writeFile(). Cancelation is "best effort", and some amount of data is likely still to be written.】

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);
} 拷贝

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

【Aborting an ongoing request does not abort individual operating system requests but rather the internal buffering fs.writeFile performs.】

fsPromises.constants#>

• <Object>

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

【Returns an object containing commonly used constants for file system operations. The object is the same as fs.constants. See FS constants for more details.】

回调接口#>

【Callback API】

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

【The callback APIs perform all operations asynchronously, without blocking the event loop, then invoke a callback function upon completion or error.】

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

【The callback APIs use the underlying Node.js threadpool to perform file system operations off the event loop thread. These operations are not synchronized or threadsafe. Care must be taken when performing multiple concurrent modifications on the same file or data corruption may occur.】

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 的可能取值。

【Tests a user's permissions for the file or directory specified by path. The mode argument is an optional integer that specifies the accessibility checks to be performed. mode should be either the value fs.constants.F_OK or a mask consisting of the bitwise OR of any of fs.constants.R_OK, fs.constants.W_OK, and fs.constants.X_OK (e.g. fs.constants.W_OK | fs.constants.R_OK). Check File access constants for possible values of mode.】

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

【The final argument, callback, is a callback function that is invoked with a possible error argument. If any of the accessibility checks fail, the error argument will be an Error object. The following examples check if package.json exists, and if it is readable or writable.】

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`);
}); 拷贝

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

【Do not use fs.access() to check for the accessibility of a file before calling fs.open(), fs.readFile(), or fs.writeFile(). Doing so introduces a race condition, since other processes may change the file's state between the two calls. Instead, user code should open/read/write the file directly and handle the error raised if the file is not accessible.】

写 (不推荐)

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;
      });
    }
  });
}); 拷贝

写（推荐）

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;
    });
  }
}); 拷贝

阅读（不推荐）

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;
      });
    }
  });
}); 拷贝

阅读（推荐）

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;
    });
  }
}); 拷贝

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

【The "not recommended" examples above check for accessibility and then use the file; the "recommended" examples are better because they use the file directly and handle the error, if any.】

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

【In general, check for the accessibility of a file only if the file will not be used directly, for example when its accessibility is a signal from another process.】

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

【On Windows, access-control policies (ACLs) on a directory may limit access to a file or directory. The fs.access() function, however, does not check the ACL and therefore may report that a path is accessible even if the ACL restricts the user from reading or writing to it.】

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>。

【Asynchronously append data to a file, creating the file if it does not yet exist. data can be a string or a <Buffer>.】

mode 选项只会影响新创建的文件。详情请参见 fs.open()。

【The mode option only affects the newly created file. See fs.open() for more details.】

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!');
}); 拷贝

如果 options 是字符串，则它指定了编码方式：

【If options is a string, then it specifies the encoding:】

import { appendFile } from 'node:fs';

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

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

【The path may be specified as a numeric file descriptor that has been opened for appending (using fs.open() or fs.openSync()). The file descriptor will not be closed automatically.】

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;
  }
}); 拷贝

fs.chmod(path, mode, callback)#>

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

异步更改文件的权限。完成回调不会提供除可能的异常以外的任何参数。

【Asynchronously changes the permissions of a file. No arguments other than a possible exception are given to the completion callback.】

有关更多详细信息，请参阅 POSIX chmod(2) 文档。

【See the POSIX chmod(2) documentation for more detail.】

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!');
}); 拷贝

文件模式#>

【File modes】

在 fs.chmod() 和 fs.chmodSync() 方法中使用的 mode 参数是一个数字位掩码，通过以下常量的逻辑或创建：

【The mode argument used in both the fs.chmod() and fs.chmodSync() methods is a numeric bitmask created using a logical OR of the following constants:】

构造 mode 的一个更简单的方法是使用由三个八进制数字组成的序列（例如 765）。最左边的数字（在例子中是 7）指定文件所有者的权限。中间的数字（在例子中是 6）指定组的权限。最右边的数字（在例子中是 5）指定其他用户的权限。

【An easier method of constructing the mode is to use a sequence of three octal digits (e.g. 765). The left-most digit (7 in the example), specifies the permissions for the file owner. The middle digit (6 in the example), specifies permissions for the group. The right-most digit (5 in the example), specifies the permissions for others.】

例如，八进制值 0o765 表示：

【For example, the octal value 0o765 means:】

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

在期望使用文件模式的情况下使用原始数字时，任何大于 0o777 的值可能会导致平台特定的行为，这些行为无法保证一致。因此，像 S_ISVTX、S_ISGID 或 S_ISUID 这样的常量在 fs.constants 中未被暴露。

【When using raw numbers where file modes are expected, any value larger than 0o777 may result in platform-specific behaviors that are not supported to work consistently. Therefore constants like S_ISVTX, S_ISGID, or S_ISUID are not exposed in fs.constants.】

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

【Caveats: on Windows only the write permission can be changed, and the distinction among the permissions of group, owner, or others is not implemented.】

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

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

异步更改文件的所有者和组。除可能的异常外，不会向完成回调提供任何参数。

【Asynchronously changes owner and group of a file. No arguments other than a possible exception are given to the completion callback.】

有关更多详细信息，请参阅 POSIX chown(2) 文档。

【See the POSIX chown(2) documentation for more detail.】

fs.close(fd[, callback])#>

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

关闭文件描述符。除了可能的异常外，完成回调不会提供其他参数。

【Closes the file descriptor. No arguments other than a possible exception are given to the completion callback.】

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

【Calling fs.close() on any file descriptor (fd) that is currently in use through any other fs operation may lead to undefined behavior.】

有关更多详细信息，请参阅 POSIX close(2) 文档。

【See the POSIX close(2) documentation for more detail.】

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 将尝试删除目标文件。

【Asynchronously copies src to dest. By default, dest is overwritten if it already exists. No arguments other than a possible exception are given to the callback function. Node.js makes no guarantees about the atomicity of the copy operation. If an error occurs after the destination file has been opened for writing, Node.js will attempt to remove the destination.】

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

• fs.constants.COPYFILE_EXCL：如果 dest 已经存在，复制操作将失败。
• fs.constants.COPYFILE_FICLONE：复制操作将尝试创建一个写时复制的反向链接。如果平台不支持写时复制，则将使用备用复制机制。
• 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); 拷贝

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
• callback <Function>
  • err <Error>

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

【Asynchronously copies the entire directory structure from src to dest, including subdirectories and files.】

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

【When copying a directory to another directory, globs are not supported and behavior is similar to 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>

options 可以包含 start 和 end 值，用于读取以下范围内的字节是文件而不是整个文件。start 和 end 都是包容性的， 从0开始计数，允许的值在 [0, Number.MAX_SAFE_INTEGER] 范围。如果指定 fd，且 start 为 省略或 undefined 时，fs.createReadStream() 会依次读取 当前档案位置。encoding 可以是以下任何一种被接受的 <Buffer>。

如果指定了 fd，ReadStream 将忽略 path 参数，并使用指定的文件描述符。这意味着不会触发 'open' 事件。fd 应该是阻塞的；非阻塞的 fd 应该传递给 <net.Socket>。

【If fd is specified, ReadStream will ignore the path argument and will use the specified file descriptor. This means that no 'open' event will be emitted. fd should be blocking; non-blocking fds should be passed to <net.Socket>.】

如果 fd 指向一个只支持阻塞读取的字符设备（例如键盘或声卡），读取操作将不会完成，直到有数据可用。这可能会阻止进程退出以及流自然关闭。

【If fd points to a character device that only supports blocking reads (such as keyboard or sound card), read operations do not finish until data is available. This can prevent the process from exiting and the stream from closing naturally.】

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

【By default, the stream will emit a 'close' event after it has been destroyed. Set the emitClose option to false to change this behavior.】

通过提供 fs 选项，可以覆盖 open、read 和 close 的对应 fs 实现。当提供 fs 选项时，必须提供 read 的覆盖实现。如果未提供 fd，还需要提供 open 的覆盖实现。如果 autoClose 为 true，还需要提供 close 的覆盖实现。

【By providing the fs option, it is possible to override the corresponding fs implementations for open, read, and close. When providing the fs option, an override for read is required. If no fd is provided, an override for open is also required. If autoClose is true, an override for close is also required.】

import { createReadStream } from 'node:fs';

// Create a stream from some character device.
const stream = createReadStream('/dev/input/event0');
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); 拷贝

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

【If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. If autoClose is set to true (default behavior), on 'error' or 'end' the file descriptor will be closed automatically.】

mode 设置文件模式（权限和粘滞位），但仅在文件被创建时生效。

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

【An example to read the last 10 bytes of a file which is 100 bytes long:】

import { createReadStream } from 'node:fs';

createReadStream('sample.txt', { start: 90, end: 99 }); 拷贝

如果 options 是字符串，那么它指定了编码。

【If options is a string, then it specifies the encoding.】

fs.createWriteStream(path[, options])#>

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> 参见 文件系统 flags 支持。默认值： 'w'。
  • encoding <string> 默认值: 'utf8'
  • fd <integer> | <FileHandle> 默认值： null
  • mode <integer> 默认值: 0o666
  • autoClose <boolean> 默认值: true
  • emitClose <boolean> 默认值: true
  • start <integer>
  • fs <Object> | <null> 默认值： null
  • signal <AbortSignal> | <null> 默认值： null
  • highWaterMark <number> 默认值: 16384
  • flush <boolean> 如果为 true，在关闭底层文件描述符之前会先刷新它。默认值： false。
• 返回：<fs.WriteStream>

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

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

【If autoClose is set to true (default behavior) on 'error' or 'finish' the file descriptor will be closed automatically. If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak.】

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

【By default, the stream will emit a 'close' event after it has been destroyed. Set the emitClose option to false to change this behavior.】

通过提供 fs 选项，可以覆盖 open、write、writev 和 close 对应的 fs 实现。仅覆盖 write() 而不覆盖 writev() 可能会降低性能，因为某些优化（_writev()）将被禁用。当提供 fs 选项时，至少需要覆盖 write 和 writev 其中之一。如果未提供 fd 选项，还需要覆盖 open。如果 autoClose 为 true，还需要覆盖 close。

【By providing the fs option it is possible to override the corresponding fs implementations for open, write, writev, and close. Overriding write() without writev() can reduce performance as some optimizations (_writev()) will be disabled. When providing the fs option, overrides for at least one of write and writev are required. If no fd option is supplied, an override for open is also required. If autoClose is true, an override for close is also required.】

像 <fs.ReadStream> 一样，如果指定了 fd，<fs.WriteStream> 将会忽略 path 参数，并使用指定的文件描述符。这意味着不会触发 'open' 事件。fd 应该是阻塞的；非阻塞的 fd 应该传给 <net.Socket>。

【Like <fs.ReadStream>, if fd is specified, <fs.WriteStream> will ignore the path argument and will use the specified file descriptor. This means that no 'open' event will be emitted. fd should be blocking; non-blocking fds should be passed to <net.Socket>.】

如果 options 是字符串，那么它指定了编码。

【If options is a string, then it specifies the encoding.】

fs.exists(path, callback)#>

• path <string> | <Buffer> | <URL>
• callback <Function>
  • exists <boolean>

通过检查文件系统来测试给定 path 处的元素是否存在。然后使用 true 或 false 调用 callback 参数：

【Test whether or not the element at the given path exists by checking with the file system. Then call the callback argument with either true or false:】

import { exists } from 'node:fs';

exists('/etc/passwd', (e) => {
  console.log(e ? 'it exists' : 'no passwd!');
}); 拷贝

此回调的参数与其他 Node.js 回调不一致。 通常，Node.js 回调的第一个参数是一个 err 参数，后面可选跟其他参数。fs.exists() 回调只有一个布尔参数。这也是推荐使用 fs.access() 而不是 fs.exists() 的原因之一。

如果 path 是符号链接，则会跟随该链接。因此，如果 path 存在但指向一个不存在的元素，回调将收到值 false。

【If path is a symbolic link, it is followed. Thus, if path exists but points to a non-existent element, the callback will receive the value false.】

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

【Using fs.exists() to check for the existence of a file before calling fs.open(), fs.readFile(), or fs.writeFile() is not recommended. Doing so introduces a race condition, since other processes may change the file's state between the two calls. Instead, user code should open/read/write the file directly and handle the error raised if the file does not exist.】

写 (不推荐)

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

exists('myfile', (e) => {
  if (e) {
    console.error('myfile already exists');
  } else {
    open('myfile', 'wx', (err, fd) => {
      if (err) throw err;

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

写（推荐）

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;
    });
  }
}); 拷贝

阅读（不推荐）

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

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

      try {
        readMyData(fd);
      } finally {
        close(fd, (err) => {
          if (err) throw err;
        });
      }
    });
  } else {
    console.error('myfile does not exist');
  }
}); 拷贝

阅读（推荐）

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;
    });
  }
}); 拷贝

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

【The "not recommended" examples above check for existence and then use the file; the "recommended" examples are better because they use the file directly and handle the error, if any.】

一般来说，只有在文件不会被直接使用时才检查文件是否存在，例如当文件的存在是来自另一个进程的信号时。

【In general, check for the existence of a file only if the file won't be used directly, for example when its existence is a signal from another process.】

fs.fchmod(fd, mode, callback)#>

• fd <integer>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

设置文件的权限。完成回调函数除了可能的异常外，不接受其他参数。

【Sets the permissions on the file. No arguments other than a possible exception are given to the completion callback.】

有关更多详细信息，请参阅 POSIX fchmod(2) 文档。

【See the POSIX fchmod(2) documentation for more detail.】

fs.fchown(fd, uid, gid, callback)#>

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

设置文件的所有者。除了可能的异常之外，完成回调不会传入任何参数。

【Sets the owner of the file. No arguments other than a possible exception are given to the completion callback.】

有关更多详细信息，请参阅 POSIX fchown(2) 文档。

【See the POSIX fchown(2) documentation for more detail.】

fs.fdatasync(fd, callback)#>

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

将与该文件相关的所有当前排队的 I/O 操作强制送入操作系统的同步 I/O 完成状态。有关详细信息，请参阅 POSIX fdatasync(2) 文档。除了可能的异常外，完成回调不传递任何参数。

【Forces all currently queued I/O operations associated with the file to the operating system's synchronized I/O completion state. Refer to the POSIX fdatasync(2) documentation for details. No arguments other than a possible exception are given to the completion callback.】

fs.fstat(fd[, options], callback)#>

• fd <integer>
• options <Object>
  • bigint <boolean> 返回的 <fs.Stats> 对象中的数值是否应为 bigint。默认值： false。
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

使用文件描述符的 <fs.Stats> 调用回调。

【Invokes the callback with the <fs.Stats> for the file descriptor.】

有关更多详细信息，请参阅 POSIX fstat(2) 文档。

【See the POSIX fstat(2) documentation for more detail.】

fs.fsync(fd, callback)#>

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

请求将开放的文件描述符的所有数据刷新到存储设备。具体实现取决于操作系统和设备。有关详细信息，请参考 POSIX fsync(2) 文档。除了可能的异常外，不向完成回调提供其他参数。

【Request that all data for the open file descriptor is flushed to the storage device. The specific implementation is operating system and device specific. Refer to the POSIX fsync(2) documentation for more detail. No arguments other than a possible exception are given to the completion callback.】

fs.ftruncate(fd[, len], callback)#>

• fd <integer>
• len <integer> 默认值： 0
• callback <Function>
  • err <Error>

截断文件描述符。完成回调函数除了可能的异常外，不会传入其他参数。

【Truncates the file descriptor. No arguments other than a possible exception are given to the completion callback.】

有关更多详细信息，请参阅 POSIX ftruncate(2) 文档。

【See the POSIX ftruncate(2) documentation for more detail.】

如果文件描述符指向的文件大于 len 字节，则文件中只会保留前 len 字节。

【If the file referred to by the file descriptor was larger than len bytes, only the first len bytes will be retained in the file.】

例如，下面的程序只保留文件的前四个字节：

【For example, the following program retains only the first four bytes of the file:】

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

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

open('temp.txt', 'r+', (err, fd) => {
  if (err) throw err;

  try {
    ftruncate(fd, 4, (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    if (err) throw err;
  }
}); 拷贝

如果文件之前短于“len”字节，则为扩展文件，且 扩展部分填充空字节（''\0''）：

【If the file previously was shorter than len bytes, it is extended, and the extended part is filled with null bytes ('\0'):】

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

【If len is negative then 0 will be used.】

fs.futimes(fd, atime, mtime, callback)#>

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

更改由提供的文件描述符引用的对象的文件系统时间戳。参见 fs.utimes()。

【Change the file system timestamps of the object referenced by the supplied file descriptor. See fs.utimes().】

fs.lchmod(path, mode, callback)#>

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

更改符号链接的权限。除了可能的异常外，完成回调不会传入其他参数。

【Changes the permissions on a symbolic link. No arguments other than a possible exception are given to the completion callback.】

此方法仅在 macOS 上实现。

【This method is only implemented on macOS.】

有关更多详细信息，请参阅 POSIX lchmod(2) 文档。

【See the POSIX lchmod(2) documentation for more detail.】

fs.lchown(path, uid, gid, callback)#>

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

设置符号链接的所有者。除了可能的异常外，完成回调不会传入其他参数。

【Set the owner of the symbolic link. No arguments other than a possible exception are given to the completion callback.】

有关更多详细信息，请参阅 POSIX lchown(2) 文档。

【See the POSIX lchown(2) documentation for more detail.】

fs.lutimes(path, atime, mtime, callback)#>

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

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

【Changes the access and modification times of a file in the same way as fs.utimes(), with the difference that if the path refers to a symbolic link, then the link is not dereferenced: instead, the timestamps of the symbolic link itself are changed.】

完成回调函数不会传入除可能的异常之外的其他参数。

【No arguments other than a possible exception are given to the completion callback.】

fs.link(existingPath, newPath, callback)#>

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

在 existingPath 和 newPath 之间创建一个新的链接。有关更多详细信息，请参阅 POSIX link(2) 文档。完成回调除了可能的异常之外，不会传递其他参数。

【Creates a new link from the existingPath to the newPath. See the POSIX link(2) documentation for more detail. No arguments other than a possible exception are given to the completion callback.】

fs.lstat(path[, options], callback)#>

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

获取路径所指向的符号链接的 <fs.Stats>。回调函数接收两个参数 (err, stats)，其中 stats 是一个 <fs.Stats> 对象。lstat() 与 stat() 完全相同，只是如果 path 是符号链接，则对链接本身进行 stat，而不是它指向的文件。

【Retrieves the <fs.Stats> for the symbolic link referred to by the path. The callback gets two arguments (err, stats) where stats is a <fs.Stats> object. lstat() is identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.】

有关更多详细信息，请参阅 POSIX lstat(2) 文档。

【See the POSIX lstat(2) documentation for more details.】

fs.mkdir(path[, options], callback)#>

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 默认值： false
  • mode <string> | <integer> 在 Windows 上不支持。默认值： 0o777。
• callback <Function>
  • err <Error>
  • path <string> | <undefined> 仅在使用 recursive 设置为 true 创建目录时才会出现。

异步地创建目录。

【Asynchronously creates a directory.】

回调函数会接收一个可能的异常，如果 recursive 为 true，还会接收到第一个创建的目录路径 (err[, path])。当 recursive 为 true 且没有创建任何目录时（例如，如果目录之前已经存在），path 仍然可能是 undefined。

【The callback is given a possible exception and, if recursive is true, the first directory path created, (err[, path]). path can still be undefined when recursive is true, if no directory was created (for instance, if it was previously created).】

可选的 options 参数可以是一个整数，用于指定 mode（权限和粘滞位），或者是一个具有 mode 属性和 recursive 属性的对象，用于指示是否应该创建父目录。当 path 是已存在的目录时调用 fs.mkdir() 只有在 recursive 为 false 时才会导致错误。如果 recursive 为 false 并且目录已存在，则会出现 EEXIST 错误。

【The optional options argument can be an integer specifying mode (permission and sticky bits), or an object with a mode property and a recursive property indicating whether parent directories should be created. Calling fs.mkdir() when path is a directory that exists results in an error only when recursive is false. If recursive is false and the directory exists, an EEXIST error occurs.】

import { mkdir } from 'node:fs';

// Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist.
mkdir('./tmp/a/apple', { recursive: true }, (err) => {
  if (err) throw err;
}); 拷贝

在 Windows 上，即使使用递归，fs.mkdir() 在根目录上也会导致错误：

【On Windows, using fs.mkdir() on the root directory even with recursion will result in an error:】

import { mkdir } from 'node:fs';

mkdir('/', { recursive: true }, (err) => {
  // => [Error: EPERM: operation not permitted, mkdir 'C:\']
}); 拷贝

有关更多详细信息，请参阅 POSIX mkdir(2) 文档。

【See the POSIX mkdir(2) documentation for more details.】

fs.mkdtemp(prefix[, options], callback)#>

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• callback <Function>
  • err <Error>
  • directory <string>

创建唯一的临时目录。

【Creates a unique temporary directory.】

生成六个随机字符，附加在必需的 prefix 后面以创建唯一的临时目录。由于平台差异，避免在 prefix 中使用尾随的 X 字符。一些平台，特别是 BSD 系统，可能会生成超过六个随机字符，并将 prefix 中尾随的 X 字符替换为随机字符。

【Generates six random characters to be appended behind a required prefix to create a unique temporary directory. Due to platform inconsistencies, avoid trailing X characters in prefix. Some platforms, notably the BSDs, can return more than six random characters, and replace trailing X characters in prefix with random characters.】

创建的目录路径作为字符串传递给回调函数的第二个参数。

【The created directory path is passed as a string to the callback's second parameter.】

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

【The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use.】

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

mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
}); 拷贝

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

【The fs.mkdtemp() method will append the six randomly selected characters directly to the prefix string. For instance, given a directory /tmp, if the intention is to create a temporary directory within /tmp, the prefix must end with a trailing platform-specific path separator (require('node:path').sep).】

import { tmpdir } from 'node:os';
import { mkdtemp } from 'node:fs';

// The parent directory for the new temporary directory
const tmpDir = tmpdir();

// This method is *INCORRECT*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmpabc123`.
  // A new temporary directory is created at the file system root
  // rather than *within* the /tmp directory.
});

// This method is *CORRECT*:
import { sep } from 'node:path';
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmp/abc123`.
  // A new temporary directory is created within
  // the /tmp directory.
}); 拷贝

fs.open(path[, flags[, mode]], callback)#>

• path <string> | <Buffer> | <URL>
• flags <string> | <number> 参见 文件系统 flags 支持。 默认值： 'r'。
• mode <string> | <integer> 默认值： 0o666（可读可写）
• callback <Function>
  • err <Error>
  • fd <integer>