Node.js v18.20.0 文档

Promise 示例#

¥Promise example

基于 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#

该 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.

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

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

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

¥All <FileHandle> objects are <EventEmitter>.

如果未使用 filehandle.close() 方法关闭 <FileHandle>，则它将尝试自动关闭文件描述符并触发进程警告，从而有助于防止内存泄漏。请不要依赖此行为，因为它可能不可靠并且该文件可能未被关闭。相反，始终显式关闭 <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>. 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'

    ¥encoding <string> | <null> Default: 'utf8'

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

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> 文件模式位掩码。

  ¥mode <integer> the file mode bit mask.

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

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

¥Modifies the permissions on the file. See chmod(2).

filehandle.chown(uid, gid)#

• uid <integer> 文件的新所有者的用户 ID。

  ¥uid <integer> The file's new owner's user id.

• gid <integer> 文件的新群组的组 ID。

  ¥gid <integer> The file's new group's group id.

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

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

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

filehandle.close()#

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

等待句柄上的任何未决操作完成后，关闭文件句柄。

¥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

    ¥encoding <string> Default: null

  • autoClose <boolean> 默认值：true

    ¥autoClose <boolean> Default: true

  • emitClose <boolean> 默认值：true

    ¥emitClose <boolean> Default: true

  • start <integer>

  • end <integer> 默认值：Infinity

    ¥end <integer> Default: Infinity

  • highWaterMark <integer> 默认值：64 * 1024

    ¥highWaterMark <integer> Default: 64 * 1024

• 返回：<fs.ReadStream>

  ¥Returns: <fs.ReadStream>

与 <stream.Readable> 的 16 KiB 默认 highWaterMark 不同，此方法返回的流的默认 highWaterMark 为 64 KiB。

¥Unlike the 16 KiB default highWaterMark for a <stream.Readable>, the stream returned by this method has a default highWaterMark of 64 KiB.

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

¥options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start counting at 0, allowed values are in the [0, Number.MAX_SAFE_INTEGER] range. If start is omitted or undefined, filehandle.createReadStream() reads sequentially from the current file position. The encoding can be any one of those accepted by <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'

    ¥encoding <string> Default: 'utf8'

  • autoClose <boolean> 默认值：true

    ¥autoClose <boolean> Default: true

  • emitClose <boolean> 默认值：true

    ¥emitClose <boolean> Default: true

  • start <integer>

• 返回：<fs.WriteStream>

  ¥Returns: <fs.WriteStream>

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

¥options may also include a start option to allow writing data at some position past the beginning of the file, allowed values are in the [0, Number.MAX_SAFE_INTEGER] range. Modifying a file rather than replacing it may require the flags open option to be set to r+ rather than the default r. The encoding can be any one of those accepted by <Buffer>.

如果将 autoClose 设置为 true（默认行为），则在 'error' 或 'finish' 时文件描述符将自动关闭。如果 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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

将与文件关联的所有当前排队的 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> 对象管理的数字文件描述符。

  ¥<number> The numeric file descriptor managed by the <FileHandle> object.

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

• buffer <Buffer> | <TypedArray> | <DataView> 将填充读取的文件数据的缓冲区。

  ¥buffer <Buffer> | <TypedArray> | <DataView> A buffer that will be filled with the file data read.

• offset <integer> 缓冲区中开始填充的位置。

  ¥offset <integer> The location in the buffer at which to start filling.

• length <integer> 读取的字节数。

  ¥length <integer> The number of bytes to read.

• position <integer> | <null> 从文件开始读取数据的位置。如果为 null，则将从当前文件位置读取数据，并将更新该位置。如果 position 是整数，则当前文件位置将保持不变。

  ¥position <integer> | <null> The location where to begin reading data from the file. If null, data will be read from the current file position, and the position will be updated. If position is an integer, the current file position will remain unchanged.

• 返回：<Promise> 成功时将使用具有以下两个属性的对象履行：

  ¥Returns: <Promise> Fulfills upon success with an object with two properties:

  • bytesRead <integer> 读取的字节数

    ¥bytesRead <integer> The number of bytes read

  • buffer <Buffer> | <TypedArray> | <DataView> 对传入的 buffer 参数的引用。

    ¥buffer <Buffer> | <TypedArray> | <DataView> A reference to the passed in buffer argument.

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

¥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)

    ¥buffer <Buffer> | <TypedArray> | <DataView> A buffer that will be filled with the file data read. Default: Buffer.alloc(16384)

  • offset <integer> 缓冲区中开始填充的位置。默认值：0

    ¥offset <integer> The location in the buffer at which to start filling. Default: 0

  • length <integer> 读取的字节数。默认值：buffer.byteLength - offset

    ¥length <integer> The number of bytes to read. Default: buffer.byteLength - offset

  • position <integer> | <null> 从文件开始读取数据的位置。如果为 null，则将从当前文件位置读取数据，并将更新该位置。如果 position 是整数，则当前文件位置将保持不变。Default::null

    ¥position <integer> | <null> The location where to begin reading data from the file. If null, data will be read from the current file position, and the position will be updated. If position is an integer, the current file position will remain unchanged. Default:: null

• 返回：<Promise> 成功时将使用具有以下两个属性的对象履行：

  ¥Returns: <Promise> Fulfills upon success with an object with two properties:

  • bytesRead <integer> 读取的字节数

    ¥bytesRead <integer> The number of bytes read

  • buffer <Buffer> | <TypedArray> | <DataView> 对传入的 buffer 参数的引用。

    ¥buffer <Buffer> | <TypedArray> | <DataView> A reference to the passed in buffer argument.

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

¥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> 将填充读取的文件数据的缓冲区。

  ¥buffer <Buffer> | <TypedArray> | <DataView> A buffer that will be filled with the file data read.

• options <Object>

  • offset <integer> 缓冲区中开始填充的位置。默认值：0

    ¥offset <integer> The location in the buffer at which to start filling. Default: 0

  • length <integer> 读取的字节数。默认值：buffer.byteLength - offset

    ¥length <integer> The number of bytes to read. Default: buffer.byteLength - offset

  • position <integer> 从文件开始读取数据的位置。如果为 null，则将从当前文件位置读取数据，并将更新该位置。如果 position 是整数，则当前文件位置将保持不变。Default::null

    ¥position <integer> The location where to begin reading data from the file. If null, data will be read from the current file position, and the position will be updated. If position is an integer, the current file position will remain unchanged. Default:: null

• 返回：<Promise> 成功时将使用具有以下两个属性的对象履行：

  ¥Returns: <Promise> Fulfills upon success with an object with two properties:

  • bytesRead <integer> 读取的字节数

    ¥bytesRead <integer> The number of bytes read

  • buffer <Buffer> | <TypedArray> | <DataView> 对传入的 buffer 参数的引用。

    ¥buffer <Buffer> | <TypedArray> | <DataView> A reference to the passed in buffer argument.

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

¥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

    ¥type <string> | <undefined> Whether to open a normal or a 'bytes' stream. Default: undefined

• 返回：<ReadableStream>

  ¥Returns: <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

    ¥encoding <string> | <null> Default: null

  • signal <AbortSignal> 允许中止正在进行的 readFile

    ¥signal <AbortSignal> allows aborting an in-progress readFile

• 返回：<Promise> 成功读取时将使用文件内容履行。如果未指定编码（使用 options.encoding），则数据作为 <Buffer> 对象返回。否则，数据将为字符串。

  ¥Returns: <Promise> Fulfills upon a successful read with the contents of the file. If no encoding is specified (using options.encoding), the data is returned as a <Buffer> object. Otherwise, the data will be a string.

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

¥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

    ¥encoding <string> Default: null

  • autoClose <boolean> 默认值：true

    ¥autoClose <boolean> Default: true

  • emitClose <boolean> 默认值：true

    ¥emitClose <boolean> Default: true

  • start <integer>

  • end <integer> 默认值：Infinity

    ¥end <integer> Default: Infinity

  • highWaterMark <integer> 默认值：64 * 1024

    ¥highWaterMark <integer> Default: 64 * 1024

• 返回：<readline.InterfaceConstructor>

  ¥Returns: <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])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>

• position <integer> | <null> 要从中读取数据的文件的开头偏移量。如果 position 不是 number，则将从当前位置读取数据。默认值：null

  ¥position <integer> | <null> The offset from the beginning of the file where the data should be read from. If position is not a number, the data will be read from the current position. Default: null

• 返回：<Promise> 成功时将使用包含以下两个属性的对象履行：

  ¥Returns: <Promise> Fulfills upon success an object containing two properties:

  • bytesRead <integer> 读取的字节数

    ¥bytesRead <integer> the number of bytes read

  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> 包含对 buffers 输入的引用的属性。

    ¥buffers <Buffer[]> | <TypedArray[]> | <DataView[]> property containing a reference to the buffers input.

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

¥Read from a file and write to an array of <ArrayBufferView>

filehandle.stat([options])#

• options <Object>

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

    ¥bigint <boolean> Whether the numeric values in the returned <fs.Stats> object should be bigint. Default: false.

• 返回：<Promise> 通过文件的 <fs.Stats> 来履行。

  ¥Returns: <Promise> Fulfills with an <fs.Stats> for the file.

filehandle.sync()#

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

请求将打开文件描述符的所有数据刷新到存储设备。具体实现是操作系统和设备特定的。有关更多详细信息，请参阅 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

  ¥len <integer> Default: 0

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

截断文件。

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

  ¥Returns: <Promise>

更改 <FileHandle> 引用的对象的文件系统时间戳，然后在成功时不带参数解决 promise 。

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

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

• buffer <Buffer> | <TypedArray> | <DataView>

• offset <integer> 要开始写入数据的 buffer 的起始位置。

  ¥offset <integer> The start position from within buffer where the data to write begins.

• length <integer> 要从 buffer 写入的字节数。默认值：buffer.byteLength - offset

  ¥length <integer> The number of bytes from buffer to write. Default: buffer.byteLength - offset

• position <integer> | <null> 要写入来自 buffer 的数据的文件的开头偏移量。如果 position 不是 number，则数据将被写入当前位置。有关更多详细信息，请参阅 POSIX pwrite(2) 文档。默认值：null

  ¥position <integer> | <null> The offset from the beginning of the file where the data from buffer should be written. If position is not a number, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail. Default: null

• 返回：<Promise>

  ¥Returns: <Promise>

将 buffer 写入文件。

¥Write buffer to the file.

使用包含以下两个属性的对象来解决 promise：

¥The promise is resolved with an object containing two properties:

• bytesWritten <integer> 写入的字节数

  ¥bytesWritten <integer> the number of bytes written

• buffer <Buffer> | <TypedArray> | <DataView> 对被写入的 buffer 的引用。

  ¥buffer <Buffer> | <TypedArray> | <DataView> a reference to the buffer written.

在同一文件上多次使用 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 resolved (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

    ¥offset <integer> Default: 0

  • length <integer> 默认值：buffer.byteLength - offset

    ¥length <integer> Default: buffer.byteLength - offset

  • position <integer> 默认值：null

    ¥position <integer> Default: null

• 返回：<Promise>

  ¥Returns: <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

  ¥position <integer> | <null> The offset from the beginning of the file where the data from string should be written. If position is not a number the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail. Default: null

• encoding <string> 预期的字符串编码。默认值：'utf8'

  ¥encoding <string> The expected string encoding. Default: 'utf8'

• 返回：<Promise>

  ¥Returns: <Promise>

将 string 写入文件。如果 string 不是字符串，则 promise 使用错误拒绝。

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

使用包含以下两个属性的对象来解决 promise：

¥The promise is resolved with an object containing two properties:

• bytesWritten <integer> 写入的字节数

  ¥bytesWritten <integer> the number of bytes written

• buffer <string> 对被写入的 string 的引用。

  ¥buffer <string> a reference to the string written.

在同一文件上多次使用 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 resolved (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'

    ¥encoding <string> | <null> The expected character encoding when data is a string. Default: 'utf8'

• 返回：<Promise>

  ¥Returns: <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 resolved 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 resolved (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])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>

• position <integer> | <null> 要写入来自 buffers 的数据的文件的开头偏移量。如果 position 不是 number，则数据将被写入当前位置。默认值：null

  ¥position <integer> | <null> The offset from the beginning of the file where the data from buffers should be written. If position is not a number, the data will be written at the current position. Default: null

• 返回：<Promise>

  ¥Returns: <Promise>

将 <ArrayBufferView> 的数组写入文件。

¥Write an array of <ArrayBufferView> to the file.

使用包含以下两个属性的对象来解决 promise：

¥The promise is resolved with an object containing a two properties:

• bytesWritten <integer> 写入的字节数

  ¥bytesWritten <integer> the number of bytes written

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> 对 buffers 输入的引用。

  ¥buffers <Buffer[]> | <TypedArray[]> | <DataView[]> a reference to the buffers input.

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

¥It is unsafe to call writev() multiple times on the same file without waiting for the promise to be resolved (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

  ¥mode <integer> Default: fs.constants.F_OK

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

测试用户对 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。如果任何可访问性检查失败，则使用 <Error> 对象拒绝 promise。以下示例检查当前进程是否可以读写文件 /etc/passwd。

¥If the accessibility check is successful, the promise is resolved 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>

  ¥path <string> | <Buffer> | <URL> | <FileHandle> filename or <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> 默认值：'utf8'

    ¥encoding <string> | <null> Default: 'utf8'

  • mode <integer> 默认值：0o666

    ¥mode <integer> Default: 0o666

  • flag <string> 参见 支持文件系统 flags。默认值：'a'。

    ¥flag <string> See support of file system flags. Default: 'a'.

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

异步地将数据追加到文件，如果该文件尚不存在，则创建该文件。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 指定为已打开用于追加（使用 fsPromises.open()）的 <FileHandle>。

¥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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

更改文件的权限。

¥Changes the permissions of a file.

fsPromises.chown(path, uid, gid)#

• path <string> | <Buffer> | <URL>

• uid <integer>

• gid <integer>

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

更改文件的所有权。

¥Changes the ownership of a file.

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

• src <string> | <Buffer> | <URL> 要复制的源文件名

  ¥src <string> | <Buffer> | <URL> source filename to copy

• dest <string> | <Buffer> | <URL> 复制操作的目标文件名

  ¥dest <string> | <Buffer> | <URL> destination filename of the copy operation

• mode <integer> 指定复制操作行为的可选修饰符。可以创建一个由两个或多个值的按位或组成的掩码（例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）默认值：0。

  ¥mode <integer> Optional modifiers that specify the behavior of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE) Default: 0.

  • fs.constants.COPYFILE_EXCL：如果 dest 已经存在，则复制操作将失败。

    ¥fs.constants.COPYFILE_EXCL: The copy operation will fail if dest already exists.

  • fs.constants.COPYFILE_FICLONE：复制操作将尝试创建写时复制引用链接。如果平台不支持写时复制，则使用后备复制机制。

    ¥fs.constants.COPYFILE_FICLONE: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used.

  • fs.constants.COPYFILE_FICLONE_FORCE：复制操作将尝试创建写时复制引用链接。如果平台不支持写时复制，则该操作将失败。

    ¥fs.constants.COPYFILE_FICLONE_FORCE: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail.

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

异步地将 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> 要复制的源路径。

  ¥src <string> | <URL> source path to copy.

• dest <string> | <URL> 要复制到的目标路径。

  ¥dest <string> | <URL> destination path to copy to.

• options <Object>

  • dereference <boolean> 取消引用符号链接。默认值：false。

    ¥dereference <boolean> dereference symlinks. Default: false.

  • errorOnExist <boolean> 当 force 是 false 且目标存在时，抛出错误。默认值：false。

    ¥errorOnExist <boolean> when force is false, and the destination exists, throw an error. Default: false.

  • filter <Function> 过滤复制文件/目录的函数。返回 true 则复制条目，返回 false 则忽略它。忽略目录时，其所有内容也将被跳过。还可以返回解析为 true 或 false 默认值的 Promise：undefined。

    ¥filter <Function> Function to filter copied files/directories. Return true to copy the item, false to ignore it. When ignoring a directory, all of its contents will be skipped as well. Can also return a Promise that resolves to true or false Default: undefined.

    • src <string> 要复制的源路径。

      ¥src <string> source path to copy.

    • dest <string> 要复制到的目标路径。

      ¥dest <string> destination path to copy to.

    • 返回：<boolean> | <Promise>

      ¥Returns: <boolean> | <Promise>

  • force <boolean> 覆盖现有文件或目录。如果将此设置为 false 并且目标存在，则复制操作将忽略错误。使用 errorOnExist 选项更改此行为。默认值：true。

    ¥force <boolean> overwrite existing file or directory. The copy operation will ignore errors if you set this to false and the destination exists. Use the errorOnExist option to change this behavior. Default: true.

  • mode <integer> 复制操作的修饰符。默认值：0。参见 fsPromises.copyFile() 的 mode 标志。

    ¥mode <integer> modifiers for copy operation. Default: 0. See mode flag of fsPromises.copyFile().

  • preserveTimestamps <boolean> 当为 true 时，则 src 的时间戳将被保留。默认值：false。

    ¥preserveTimestamps <boolean> When true timestamps from src will be preserved. Default: false.

  • recursive <boolean> 递归复制目录默认：false

    ¥recursive <boolean> copy directories recursively Default: false

  • verbatimSymlinks <boolean> 当为 true 时，则符号链接的路径解析将被跳过。默认值：false

    ¥verbatimSymlinks <boolean> When true, path resolution for symlinks will be skipped. Default: false

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

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

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

当将目录复制到另一个目录时，不支持 globs，并且行为类似于 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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

更改符号链接的权限。

¥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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

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

¥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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

以与 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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

创建从 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。

    ¥bigint <boolean> Whether the numeric values in the returned <fs.Stats> object should be bigint. Default: false.

• 返回：<Promise> 使用给定符号链接 path 的 <fs.Stats> 对象实现。

  ¥Returns: <Promise> Fulfills with the <fs.Stats> object for the given symbolic link path.

等效于 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

    ¥recursive <boolean> Default: false

  • mode <string> | <integer> Windows 上不支持。默认值：0o777。

    ¥mode <string> | <integer> Not supported on Windows. Default: 0o777.

• 返回：<Promise> 成功后，如果 recursive 为 false，则使用 undefined 履行；如果 recursive 为 true，则使用创建的第一个目录路径履行。

  ¥Returns: <Promise> Upon success, fulfills with undefined if recursive is false, or the first directory path created if recursive is true.

异步地创建目录。

¥Asynchronously creates a directory.

可选的 options 参数可以是指定 mode（权限和粘性位）的整数，也可以是具有 mode 属性和 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'

    ¥encoding <string> Default: 'utf8'

• 返回：<Promise> 用包含新创建的临时目录的文件系统路径的字符串来满足。

  ¥Returns: <Promise> Fulfills with a string containing the file system path of the newly created temporary directory.

创建唯一的临时目录。通过在所提供的 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'。

  ¥flags <string> | <number> See support of file system flags. Default: 'r'.

• mode <string> | <integer> 如果创建文件，则设置文件模式（权限和粘性位）。默认值：0o666（可读可写）

  ¥mode <string> | <integer> Sets the file mode (permission and sticky bits) if the file is created. Default: 0o666 (readable and writable)

• 返回：<Promise> 使用 <FileHandle> 对象实现。

  ¥Returns: <Promise> Fulfills with a <FileHandle> object.

打开 <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'

    ¥encoding <string> | <null> Default: 'utf8'

  • bufferSize <number> 当从目录读取时，在内部缓冲的目录条目数。值越大，性能越好，但内存使用率越高。默认值：32

    ¥bufferSize <number> Number of directory entries that are buffered internally when reading from the directory. Higher values lead to better performance but higher memory usage. Default: 32

  • recursive <boolean> 已解析的 Dir 将是包含所有子文件和目录的 <AsyncIterable>。默认值：false

    ¥recursive <boolean> Resolved Dir will be an <AsyncIterable> containing all sub files and directories. Default: false

• 返回：<Promise> 满足 <fs.Dir>。

  ¥Returns: <Promise> Fulfills with an <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'

    ¥encoding <string> Default: 'utf8'

  • withFileTypes <boolean> 默认值：false

    ¥withFileTypes <boolean> Default: false

  • recursive <boolean> 默认值：false

    ¥recursive <boolean> Default: false

• 返回：<Promise> 使用目录中文件的名称数组（不包括 '.' 和 '..'）履行。

  ¥Returns: <Promise> Fulfills with an array of the names of the files in the directory excluding '.' and '..'.

读取目录的内容。

¥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 resolved 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

  ¥path <string> | <Buffer> | <URL> | <FileHandle> filename or FileHandle

• options <Object> | <string>

  • encoding <string> | <null> 默认值：null

    ¥encoding <string> | <null> Default: null

  • flag <string> 参见 支持文件系统 flags。默认值：'r'。

    ¥flag <string> See support of file system flags. Default: 'r'.

  • signal <AbortSignal> 允许中止正在进行的 readFile

    ¥signal <AbortSignal> allows aborting an in-progress readFile

• 返回：<Promise> 使用文件的内容履行。

  ¥Returns: <Promise> Fulfills with the contents of the file.

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

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

    ¥encoding <string> Default: 'utf8'

• 返回：<Promise> 成功时将使用 linkString 履行。

  ¥Returns: <Promise> Fulfills with the linkString upon success.

读取 path 引用的符号链接的内容。有关更多详细信息，请参阅 POSIX readlink(2) 文档。成功时使用 linkString 解决 promise。

¥Reads the contents of the symbolic link referred to by path. See the POSIX readlink(2) documentation for more detail. The promise is resolved 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'

    ¥encoding <string> Default: 'utf8'

• 返回：<Promise> 成功时将使用解析的路径履行。

  ¥Returns: <Promise> Fulfills with the resolved path upon success.

使用与 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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

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

    ¥maxRetries <integer> If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or EPERM error is encountered, Node.js retries the operation with a linear backoff wait of retryDelay milliseconds longer on each try. This option represents the number of retries. This option is ignored if the recursive option is not true. Default: 0.

  • recursive <boolean> 如果为 true，则执行递归目录删除。在递归模式下，操作将在失败时重试。默认值：false。已弃用。

    ¥recursive <boolean> If true, perform a recursive directory removal. In recursive mode, operations are retried on failure. Default: false. Deprecated.

  • retryDelay <integer> 重试之间等待的时间（以毫秒为单位）。如果 recursive 选项不为 true，则忽略此选项。默认值：100。

    ¥retryDelay <integer> The amount of time in milliseconds to wait between retries. This option is ignored if the recursive option is not true. Default: 100.

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

删除由 path 标识的目录。

¥Removes the directory identified by path.

在文件（而不是目录）上使用 fsPromises.rmdir() 会导致 promise 被拒绝，在 Windows 上使用 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 命令的行为，则使用具有选项 { recursive: true, force: true } 的 fsPromises.rm()。

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

    ¥force <boolean> When true, exceptions will be ignored if path does not exist. Default: false.

  • maxRetries <integer> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 错误，Node.js 将在每次尝试时以 retryDelay 毫秒的线性退避等待时间重试该操作。此选项表示重试次数。如果 recursive 选项不为 true，则忽略此选项。默认值：0。

    ¥maxRetries <integer> If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or EPERM error is encountered, Node.js will retry the operation with a linear backoff wait of retryDelay milliseconds longer on each try. This option represents the number of retries. This option is ignored if the recursive option is not true. Default: 0.

  • recursive <boolean> 如果为 true，则执行递归目录删除。在递归模式下，操作将在失败时重试。默认值：false。

    ¥recursive <boolean> If true, perform a recursive directory removal. In recursive mode operations are retried on failure. Default: false.

  • retryDelay <integer> 重试之间等待的时间（以毫秒为单位）。如果 recursive 选项不为 true，则忽略此选项。默认值：100。

    ¥retryDelay <integer> The amount of time in milliseconds to wait between retries. This option is ignored if the recursive option is not true. Default: 100.

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

删除文件和目录（在标准 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。

    ¥bigint <boolean> Whether the numeric values in the returned <fs.Stats> object should be bigint. Default: false.

• 返回：<Promise> 满足给定 path 的 <fs.Stats> 对象。

  ¥Returns: <Promise> Fulfills with the <fs.Stats> object for the given path.

fsPromises.statfs(path[, options])#

• path <string> | <Buffer> | <URL>

• options <Object>

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

    ¥bigint <boolean> Whether the numeric values in the returned <fs.StatFs> object should be bigint. Default: false.

• 返回：<Promise> 满足给定 path 的 <fs.StatFs> 对象。

  ¥Returns: <Promise> Fulfills with the <fs.StatFs> object for the given path.

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

• target <string> | <Buffer> | <URL>

• path <string> | <Buffer> | <URL>

• type <string> 默认值：'file'

  ¥type <string> Default: 'file'

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

创建符号链接。

¥Creates a symbolic link.

type 参数仅在 Windows 平台上使用，可以是 'dir'、'file' 或 'junction' 之一。Windows 交接点要求目标路径是绝对路径。使用 'junction' 时，target 参数将自动规范化为绝对路径。NTFS 卷上的连接点只能指向目录。

¥The type argument is only used on Windows platforms and can be one of 'dir', 'file', or 'junction'. 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

  ¥len <integer> Default: 0

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

将 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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

如果 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 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

更改 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' 这样的数字字符串。

  ¥Values can be either numbers representing Unix epoch time, Dates, or a numeric string like '123456789.0'.

• 如果该值不能转换为数字，或者是 NaN、Infinity 或 -Infinity，则会抛出 Error。

  ¥If the value can not be converted to a number, or is NaN, Infinity, or -Infinity, an Error will be thrown.

fsPromises.watch(filename[, options])#

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> 指示只要正在监视文件，进程是否应继续运行。默认值：true。

    ¥persistent <boolean> Indicates whether the process should continue to run as long as files are being watched. Default: true.

  • recursive <boolean> 指示是应监视所有子目录，还是仅监视当前目录。这在指定目录时适用，并且仅适用于受支持的平台（参见 caveats）。默认值：false。

    ¥recursive <boolean> Indicates whether all subdirectories should be watched, or only the current directory. This applies when a directory is specified, and only on supported platforms (See caveats). Default: false.

  • encoding <string> 指定用于传给监听器的文件名的字符编码。默认值：'utf8'。

    ¥encoding <string> Specifies the character encoding to be used for the filename passed to the listener. Default: 'utf8'.

  • signal <AbortSignal> 用于指示监视器何时应停止的 <AbortSignal>。

    ¥signal <AbortSignal> An <AbortSignal> used to signal when the watcher should stop.

• 返回：<AsyncIterator> 个具有以下属性的对象：

  ¥Returns: <AsyncIterator> of objects with the properties:

  • eventType <string> 变更类型

    ¥eventType <string> The type of change

  • filename <string> | <Buffer> | <null> 变更的文件的名称。

    ¥filename <string> | <Buffer> | <null> The name of the file changed.

返回异步迭代器，其监视 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() 的所有 caveats 也适用于 fsPromises.watch()。

¥All the caveats for fs.watch() also apply to fsPromises.watch().

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

• file <string> | <Buffer> | <URL> | <FileHandle> 文件名或 FileHandle

  ¥file <string> | <Buffer> | <URL> | <FileHandle> filename or FileHandle

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> 默认值：'utf8'

    ¥encoding <string> | <null> Default: 'utf8'

  • mode <integer> 默认值：0o666

    ¥mode <integer> Default: 0o666

  • flag <string> 参见 支持文件系统 flags。默认值：'w'。

    ¥flag <string> See support of file system flags. Default: 'w'.

  • signal <AbortSignal> 允许中止正在进行的 writeFile

    ¥signal <AbortSignal> allows aborting an in-progress writeFile

• 返回：<Promise> 成功时将使用 undefined 履行。

  ¥Returns: <Promise> Fulfills with undefined upon success.

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

在同一个文件上多次使用 fsPromises.writeFile() 而不等待 promise 被解决是不安全的。

¥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

  ¥mode <integer> Default: 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.

写入（不推荐）

¥write (NOT RECOMMENDED)

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

写入（推荐）

¥write (RECOMMENDED)

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

读取（不推荐）

¥read (NOT RECOMMENDED)

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

读取（推荐）

¥read (RECOMMENDED)

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

上面的 "不建议" 示例检查可访问性，然后使用该文件；"recommended" 示例更好，因为它们直接使用文件并处理错误（如果有）。

¥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> 文件名或文件描述符

  ¥path <string> | <Buffer> | <URL> | <number> filename or file descriptor

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> 默认值：'utf8'

    ¥encoding <string> | <null> Default: 'utf8'

  • mode <integer> 默认值：0o666

    ¥mode <integer> Default: 0o666

  • flag <string> 参见 支持文件系统 flags。默认值：'a'。

    ¥flag <string> See support of file system flags. Default: 'a'.

• 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:

• 所有者可以读取、写入、以及执行文件。

  ¥The owner may read, write, and execute the file.

• 群组可以读取和写入文件。

  ¥The group may read and write the file.

• 其他人可以读取和执行文件。

  ¥Others may read and execute the file.

在需要文件模式的地方使用原始数字时，任何大于 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 上只能修改写权限，没有实现 group、owner、其他权限的区分。

¥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> 要复制的源文件名

  ¥src <string> | <Buffer> | <URL> source filename to copy

• dest <string> | <Buffer> | <URL> 复制操作的目标文件名

  ¥dest <string> | <Buffer> | <URL> destination filename of the copy operation

• mode <integer> 复制操作的修饰符。默认值：0。

  ¥mode <integer> modifiers for copy operation. Default: 0.

• callback <Function>

异步地将 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 是可选的整数，用于指定复制操作的行为。可以创建由两个或多个值的按位或组成的掩码（例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）。

¥mode is an optional integer that specifies the behavior of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL：如果 dest 已经存在，则复制操作将失败。

  ¥fs.constants.COPYFILE_EXCL: The copy operation will fail if dest already exists.

• fs.constants.COPYFILE_FICLONE：复制操作将尝试创建写时复制引用链接。如果平台不支持写时复制，则使用后备复制机制。

  ¥fs.constants.COPYFILE_FICLONE: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used.

• fs.constants.COPYFILE_FICLONE_FORCE：复制操作将尝试创建写时复制引用链接。如果平台不支持写时复制，则该操作将失败。

  ¥fs.constants.COPYFILE_FICLONE_FORCE: The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail.

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> 要复制的源路径。

  ¥src <string> | <URL> source path to copy.

• dest <string> | <URL> 要复制到的目标路径。

  ¥dest <string> | <URL> destination path to copy to.

• options <Object>

  • dereference <boolean> 取消引用符号链接。默认值：false。

    ¥dereference <boolean> dereference symlinks. Default: false.

  • errorOnExist <boolean> 当 force 是 false 且目标存在时，抛出错误。默认值：false。

    ¥errorOnExist <boolean> when force is false, and the destination exists, throw an error. Default: false.

  • filter <Function> 过滤复制文件/目录的函数。返回 true 则复制条目，返回 false 则忽略它。忽略目录时，其所有内容也将被跳过。还可以返回解析为 true 或 false 默认值的 Promise：undefined。

    ¥filter <Function> Function to filter copied files/directories. Return true to copy the item, false to ignore it. When ignoring a directory, all of its contents will be skipped as well. Can also return a Promise that resolves to true or false Default: undefined.

    • src <string> 要复制的源路径。

      ¥src <string> source path to copy.

    • dest <string> 要复制到的目标路径。

      ¥dest <string> destination path to copy to.

    • 返回：<boolean> | <Promise>

      ¥Returns: <boolean> | <Promise>

  • force <boolean> 覆盖现有文件或目录。如果将此设置为 false 并且目标存在，则复制操作将忽略错误。使用 errorOnExist 选项更改此行为。默认值：true。

    ¥force <boolean> overwrite existing file or directory. The copy operation will ignore errors if you set this to false and the destination exists. Use the errorOnExist option to change this behavior. Default: true.

  • mode <integer> 复制操作的修饰符。默认值：0。参见 fs.copyFile() 的 mode 标志。

    ¥mode <integer> modifiers for copy operation. Default: 0. See mode flag of fs.copyFile().

  • preserveTimestamps <boolean> 当为 true 时，则 src 的时间戳将被保留。默认值：false。

    ¥preserveTimestamps <boolean> When true timestamps from src will be preserved. Default: false.

  • recursive <boolean> 递归复制目录默认：false

    ¥recursive <boolean> copy directories recursively Default: false

  • verbatimSymlinks <boolean> 当为 true 时，则符号链接的路径解析将被跳过。默认值：false

    ¥verbatimSymlinks <boolean> When true, path resolution for symlinks will be skipped. Default: false

• callback <Function>

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

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

当将目录复制到另一个目录时，不支持 globs，并且行为类似于 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'。

    ¥flags <string> See support of file system flags. Default: 'r'.

  • encoding <string> 默认值：null

    ¥encoding <string> Default: null

  • fd <integer> | <FileHandle> 默认值：null

    ¥fd <integer> | <FileHandle> Default: null

  • mode <integer> 默认值：0o666

    ¥mode <integer> Default: 0o666

  • autoClose <boolean> 默认值：true

    ¥autoClose <boolean> Default: true

  • emitClose <boolean> 默认值：true

    ¥emitClose <boolean> Default: true

  • start <integer>

  • end <integer> 默认值：Infinity

    ¥end <integer> Default: Infinity

  • highWaterMark <integer> 默认值：64 * 1024

    ¥highWaterMark <integer> Default: 64 * 1024

  • fs <Object> | <null> 默认值：null

    ¥fs <Object> | <null> Default: null

  • signal <AbortSignal> | <null> 默认值：null

    ¥signal <AbortSignal> | <null> Default: null

• 返回：<fs.ReadStream>

  ¥Returns: <fs.ReadStream>

与 <stream.Readable> 的 16 KiB 默认 highWaterMark 不同，此方法返回的流的默认 highWaterMark 为 64 KiB。

¥Unlike the 16 KiB default highWaterMark for a <stream.Readable>, the stream returned by this method has a default highWaterMark of 64 KiB.

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

¥options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start counting at 0, allowed values are in the [0, Number.MAX_SAFE_INTEGER] range. If fd is specified and start is omitted or undefined, fs.createReadStream() reads sequentially from the current file position. The encoding can be any one of those accepted by <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 设置文件模式（权限和粘滞位），但前提是文件已创建。

¥mode sets the file mode (permission and sticky bits), but only if the file was created.

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

    ¥flags <string> See support of file system flags. Default: 'w'.

  • encoding <string> 默认值：'utf8'

    ¥encoding <string> Default: 'utf8'

  • fd <integer> | <FileHandle> 默认值：null

    ¥fd <integer> | <FileHandle> Default: null

  • mode <integer> 默认值：0o666

    ¥mode <integer> Default: 0o666

  • autoClose <boolean> 默认值：true

    ¥autoClose <boolean> Default: true

  • emitClose <boolean> 默认值：true

    ¥emitClose <boolean> Default: true

  • start <integer>

  • fs <Object> | <null> 默认值：null

    ¥fs <Object> | <null> Default: null

  • signal <AbortSignal> | <null> 默认值：null

    ¥signal <AbortSignal> | <null> Default: null

• 返回：<fs.WriteStream>

  ¥Returns: <fs.WriteStream>

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

¥options may also include a start option to allow writing data at some position past the beginning of the file, allowed values are in the [0, Number.MAX_SAFE_INTEGER] range. Modifying a file rather than replacing it may require the flags option to be set to r+ rather than the default w. The encoding can be any one of those accepted by <Buffer>.

如果将 autoClose 设置为 true（默认行为），则在 'error' 或 'finish' 时文件描述符将自动关闭。如果 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 实现。在没有 writev() 的情况下覆盖 write() 会降低性能，因为某些优化 (_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>

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

¥Test whether or not 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() 的原因之一。

¥The parameters for this callback are not consistent with other Node.js callbacks. Normally, the first parameter to a Node.js callback is an err parameter, optionally followed by other parameters. The fs.exists() callback has only one boolean parameter. This is one reason fs.access() is recommended instead of fs.exists().

不建议在调用 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.

写入（不推荐）

¥write (NOT RECOMMENDED)

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

写入（推荐）

¥write (RECOMMENDED)

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

读取（不推荐）

¥read (NOT RECOMMENDED)

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