Node.js v18.6.0 文档

Promise 的示例#

中英对照

基于 promise 的操作会返回一个当异步操作完成时被履行的 promise。

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

回调的示例#

中英对照

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

import { unlink } from 'node:fs';

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

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

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

同步的示例#

中英对照

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

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // 处理错误
}const { unlinkSync } = require('node:fs');

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

Promise 的 API#

中英对照

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

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

FileHandle 类#

中英对照

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

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

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

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

'close' 事件#

中英对照

当 <FileHandle> 已关闭且不再可用时，则触发 'close' 事件。

filehandle.appendFile(data[, options])#

中英对照

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> 默认值: 'utf8'
• 返回: <Promise> 成功时将使用 undefined 履行。

filehandle.writeFile() 的别名。

当在文件句柄上进行操作时，则无法将模式更改为使用 fsPromises.open() 设置的模式。 因此，这相当于 filehandle.writeFile()。

filehandle.chmod(mode)#

中英对照

• mode <integer> 文件模式位掩码。
• 返回: <Promise> 成功时将使用 undefined 履行。

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

filehandle.chown(uid, gid)#

中英对照

• uid <integer> 文件的新所有者的用户 ID。
• gid <integer> 文件的新群组的组 ID。
• 返回: <Promise> 成功时将使用 undefined 履行。

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

filehandle.close()#

中英对照

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

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

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

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

filehandle.createReadStream([options])#

中英对照

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

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

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

如果 FileHandle 指向只支持阻塞读取的字符设备（如键盘或声卡），则读取操作在数据可用之前不会完成。 这可以防止进程退出和流自然关闭。

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

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

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

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

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

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

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

filehandle.createWriteStream([options])#

中英对照

• options <Object>
  • encoding <string> 默认值: 'utf8'
  • autoClose <boolean> 默认值: true
  • emitClose <boolean> 默认值: true
  • start <integer>
• 返回: <fs.WriteStream>

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

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

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

filehandle.datasync()#

中英对照

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

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

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

filehandle.fd#

中英对照

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

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

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> 将填充读取的文件数据的缓冲区。
• offset <integer> 缓冲区中开始填充的位置。
• length <integer> 读取的字节数。
• position <integer> | <null> 从文件开始读取数据的位置。 如果为 null，则将从当前文件位置读取数据，并将更新该位置。 如果 position 是整数，则当前文件位置将保持不变。
• 返回: <Promise> 成功时将使用具有以下两个属性的对象履行：
  • bytesRead <integer> 读取的字节数
  • buffer <Buffer> | <TypedArray> | <DataView> 对传入的 buffer 参数的引用。

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

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

filehandle.read([options])#

中英对照

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

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

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

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

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

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

filehandle.readableWebStream()#

中英对照

• 返回: <ReadableStream>

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

如果多次调用此方法或在 FileHandle 关闭中或关闭后调用该方法会报错。

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

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

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

await file.close();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() 方法。

filehandle.readFile(options)#

中英对照

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

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

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

<FileHandle> 必须支持读取。

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

filehandle.readv(buffers[, position])#

中英对照

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

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

filehandle.stat([options])#

中英对照

• options <Object>
  • bigint <boolean> 返回的 <fs.Stats> 对象中的数值是否应为 bigint。 默认值: false。
• 返回: <Promise> 使用文件的 <fs.Stats> 履行。

filehandle.sync()#

中英对照

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

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

filehandle.truncate(len)#

中英对照

• len <integer> 默认值: 0
• 返回: <Promise> 成功时将使用 undefined 履行。

截断文件。

如果文件大于 len 个字节，则仅前 len 个字节将保留在文件中。

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

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

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

如果文件先前小于 len 个字节，则将其扩展，并且扩展部分将使用空字节（'\0'）填充：

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

filehandle.utimes(atime, mtime)#

中英对照

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

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

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

中英对照

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

将 buffer 写入文件。

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

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

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

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

filehandle.write(buffer[, options])#

中英对照

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

将 buffer 写入文件。

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

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

中英对照

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

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

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

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

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

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

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。

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

<FileHandle> 必须支持写入。

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

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

filehandle.writev(buffers[, position])#

中英对照

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

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

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

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

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

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

fsPromises.access(path[, mode])#

中英对照

• path <string> | <Buffer> | <URL>
• mode <integer> 默认值: fs.constants.F_OK
• 返回: <Promise> 成功时将使用 undefined 履行。

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

如果可访问性检查成功，则不带值解决 promise。 如果任何可访问性检查失败，则使用 <Error> 对象拒绝 promise。 以下示例检查当前进程是否可以读写文件 /etc/passwd。

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

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

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

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'。
• 返回: <Promise> 成功时将使用 undefined 履行。

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

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

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

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

fsPromises.chmod(path, mode)#

中英对照

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• 返回: <Promise> 成功时将使用 undefined 履行。

更改文件的权限。

fsPromises.chown(path, uid, gid)#

中英对照

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 返回: <Promise> 成功时将使用 undefined 履行。

更改文件的所有权。

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

中英对照

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

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

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

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

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

// 通过使用 COPYFILE_EXCL，如果 destination.txt 存在，则该操作将失败。
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
  console.log('source.txt was copied to destination.txt');
} catch {
  console.log('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。
  • force <boolean> 覆盖现有的文件或目录。 如果将此设置为 false 并且目标存在，则复制操作将忽略错误。 使用 errorOnExist 选项更改此行为。 默认值: true。
  • preserveTimestamps <boolean> 当为 true 时，则 src 的时间戳将被保留。 默认值: false。
  • recursive <boolean> 递归地复制目录 默认值: false
  • verbatimSymlinks <boolean> 当为 true 时，则符号链接的路径解析将被跳过。 默认值: false
• 返回: <Promise> 成功时将使用 undefined 履行。

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

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

fsPromises.lchmod(path, mode)#

中英对照

• path <string> | <Buffer> | <URL>
• mode <integer>
• 返回: <Promise> 成功时将使用 undefined 履行。

更改符号链接的权限。

此方法仅在 macOS 上实现。

fsPromises.lchown(path, uid, gid)#

中英对照

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 返回: <Promise> 成功时将使用 undefined 履行。

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

fsPromises.lutimes(path, atime, mtime)#

中英对照

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 返回: <Promise> 成功时将使用 undefined 履行。

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

fsPromises.link(existingPath, newPath)#

中英对照

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 返回: <Promise> 成功时将使用 undefined 履行。

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

fsPromises.lstat(path[, options])#

中英对照

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

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

fsPromises.mkdir(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 默认值: false
  • mode <string> | <integer> Windows 上不支持。 默认值: 0o777。
• 返回: <Promise> 成功后，如果 recursive 为 false，则使用 undefined 履行；如果 recursive 为 true，则使用创建的第一个目录路径履行。

异步地创建目录。

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

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

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

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}const { mkdir } = require('node:fs/promises');
const { resolve, 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>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• 返回: <Promise> 使用包含新创建的临时目录的文件系统路径的字符串来履行。

创建唯一的临时目录。 通过在所提供的 prefix 的末尾附加六个随机字符来生成唯一的目录名称。 由于平台的不一致，请避免在 prefix 中尾随 X 字符。 某些平台，尤其是 BSD，可能返回六个以上的随机字符，并将 prefix 中的尾随 X 字符替换为随机字符。

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

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

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

fsPromises.mkdtemp() 方法会将六个随机选择的字符直接附加到 prefix 字符串。 例如，给定目录 /tmp，如果要在 /tmp 内创建临时目录，则 prefix 必须以平台特定的尾随路径分隔符（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>。

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

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

fsPromises.opendir(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> 默认值: 'utf8'
  • bufferSize <number> 当从目录读取时，在内部缓冲的目录条目数。 值越大，性能越好，但内存使用率越高。 默认值: 32
• 返回: <Promise> 使用 <fs.Dir> 履行。

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

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

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

使用异步迭代的示例：

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

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

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

fsPromises.readdir(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
  • withFileTypes <boolean> 默认值: false
• 返回: <Promise> 使用目录中文件的名称数组（不包括 '.' 和 '..'）履行。

读取目录的内容。

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

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

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

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

fsPromises.readFile(path[, options])#

中英对照

• path <string> | <Buffer> | <URL> | <FileHandle> 文件名或 FileHandle
• options <Object> | <string>
  • encoding <string> | <null> 默认值: null
  • flag <string> 请参阅对文件系统 flags 的支持。 默认值: 'r'。
  • signal <AbortSignal> 允许中止正在进行的读取文件
• 返回: <Promise> 使用文件的内容履行。

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

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

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

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

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

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

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

  // 在 promise 达成之前中止请求。
  controller.abort();

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

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

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

fsPromises.readlink(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• 返回: <Promise> 成功时将使用 linkString 履行。

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

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

fsPromises.realpath(path[, options])#

中英对照

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

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

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

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

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

fsPromises.rename(oldPath, newPath)#

中英对照

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 返回: <Promise> 成功时将使用 undefined 履行。

将 oldPath 重命名为 newPath。

fsPromises.rmdir(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <Object>
  • 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 标识的目录。

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

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

fsPromises.rm(path[, options])#

中英对照

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

删除文件和目录（在标准 POSIX rm 实用工具上建模）。

fsPromises.stat(path[, options])#

中英对照

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

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

中英对照

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> 默认值: 'file'
• 返回: <Promise> 成功时将使用 undefined 履行。

创建符号链接。

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

fsPromises.truncate(path[, len])#

中英对照

• path <string> | <Buffer> | <URL>
• len <integer> 默认值: 0
• 返回: <Promise> 成功时将使用 undefined 履行。

将 path 上的内容截断（缩短或延长长度）到 len 个字节。

fsPromises.unlink(path)#

中英对照

• path <string> | <Buffer> | <URL>
• 返回: <Promise> 成功时将使用 undefined 履行。

如果 path 指向符号链接，则删除该链接，但不影响链接所指向的文件或目录。 如果 path 指向的文件路径不是符号链接，则删除文件。 有关更多详细信息，请参阅 POSIX unlink(2) 文档。

fsPromises.utimes(path, atime, mtime)#

中英对照

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 返回: <Promise> 成功时将使用 undefined 履行。

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

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

• 值可以是代表 Unix 纪元时间的数字、Date、或数字字符串（例如 '123456789.0'）。
• 如果该值不能转换为数字，或者是 NaN、Infinity 或 -Infinity，则会抛出 Error。

fsPromises.watch(filename[, options])#

中英对照

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> 指示只要正在监视文件，进程是否应继续运行。 默认值: true。
  • recursive <boolean> 指示是应监视所有子目录，还是仅监视当前目录。 这在指定目录时适用，并且仅在受支持的平台上有效（请参见注意事项）。 默认值: false。
  • encoding <string> 指定用于传给监听器的文件名的字符编码。 默认值: 'utf8'。
  • signal <AbortSignal> 用于指示监视器何时应停止的 <AbortSignal>。
• 返回: <AsyncIterator> 具有以下属性的对象：
  • eventType <string> 变更类型
  • filename <string> | <Buffer> 变更的文件的名称。

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

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

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

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

在大多数平台上，只要目录中文件名出现或消失，就会触发 'rename'。

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

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

中英对照

• 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'。
  • signal <AbortSignal> 允许中止正在进行的写入文件
• 返回: <Promise> 成功时将使用 undefined 履行。

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

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

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

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

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

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

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

可以使用 <AbortSignal> 取消 fsPromises.writeFile()。 取消是"尽力而为"的，并且可能仍会写入一些数据。

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

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

  // 在 promise 达成之前中止请求。
  controller.abort();

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

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

fsPromises.constants#

中英对照

• <Object>

返回一个包含文件系统操作常用常量的对象。 对象与 fs.constants 相同。 有关详细信息，请参阅 FS 常量。

回调的 API#

中英对照

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

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

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

中英对照

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

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

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

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

const file = 'package.json';

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

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

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

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

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

写入（不推荐）

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

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

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

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

写入（推荐）

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

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

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

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

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

中英对照

• path <string> | <Buffer> | <URL> | <number> 文件名或文件描述符
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> 默认值: 'utf8'
  • mode <integer> 默认值: 0o666
  • flag <string> 请参阅对文件系统 flags 的支持。 默认值: 'a'。
• callback <Function>
  • err <Error>

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

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

import { appendFile } from 'node:fs';

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

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

import { appendFile } from 'node:fs';

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

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

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

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

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

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

fs.chmod(path, mode, callback)#

中英对照

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

异步地更改文件的权限。 除了可能的异常之外，没有为完成回调提供任何参数。

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

import { chmod } from 'node:fs';

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

文件的模式#

中英对照

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

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

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

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

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

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

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

中英对照

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

异步地更改文件的所有者和群组。 除了可能的异常之外，没有为完成回调提供任何参数。

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

fs.close(fd[, callback])#

中英对照

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

关闭文件描述符。 除了可能的异常之外，没有为完成回调提供任何参数。

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

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

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

中英对照

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

异步地将 src 复制到 dest。 默认情况下，如果 dest 已经存在，则会被覆盖。 除了可能的异常之外，没有给回调函数提供任何参数。 Node.js 不保证复制操作的原子性。 如果在打开目标文件进行写入后发生错误，Node.js 将尝试删除目标文件。

mode 是可选的整数，用于指定复制操作的行为。 可以创建由两个或多个值的按位或组成的掩码（例如 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。
copyFile('source.txt', 'destination.txt', callback);

// 通过使用 COPYFILE_EXCL，如果 destination.txt 存在，则该操作将失败。
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。
  • force <boolean> 覆盖现有的文件或目录。 如果将此设置为 false 并且目标存在，则复制操作将忽略错误。 使用 errorOnExist 选项更改此行为。 默认值: true。
  • preserveTimestamps <boolean> 当为 true 时，则 src 的时间戳将被保留。 默认值: false。
  • recursive <boolean> 递归地复制目录 默认值: false
  • verbatimSymlinks <boolean> 当为 true 时，则符号链接的路径解析将被跳过。 默认值: false
• callback <Function>

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

当将目录复制到另一个目录时，不支持 globs，并且行为类似于 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
• 返回: <fs.ReadStream>

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

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

如果 fd 指向仅支持阻塞读取的字符设备（例如键盘或声卡），则读取操作不会在数据可用之前完成。 这可以防止进程退出和流自然关闭。

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

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

import { createReadStream } from 'node:fs';

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

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

mode 设置文件模式（权限和粘滞位），但前提是文件已创建。

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

import { createReadStream } from 'node:fs';

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

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

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

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

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

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

通过提供 fs 选项，可以覆盖 open、write、writev 和 close 的相应 fs 实现。 在没有 writev() 的情况下覆盖 write() 会降低性能，因为某些优化 (_writev()) 将被禁用。 当提供了 fs 选项时，则至少需要覆盖 write 和 writev 之一。 如果没有提供 fd 选项，则还需要覆盖 open。 如果 autoClose 是 true，则还需要覆盖 close。

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

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

fs.exists(path, callback)#

中英对照

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

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

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() 的原因之一。

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

写入（不推荐）

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

上面的“不推荐”示例检查是否存在，然后使用该文件；“推荐”示例更好，因为它们直接使用文件并处理错误（如果有）。

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

fs.fchmod(fd, mode, callback)#

中英对照

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

设置文件的权限。 除了可能的异常之外，没有为完成回调提供任何参数。

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

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

中英对照

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

设置文件的所有者。 除了可能的异常之外，没有为完成回调提供任何参数。

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

fs.fdatasync(fd, callback)#

中英对照

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

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

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

中英对照

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

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

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

fs.fsync(fd, callback)#

中英对照

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

请求将打开文件描述符的所有数据刷新到存储设备。 具体实现是操作系统和设备特定的。 有关更多详细信息，请参考 POSIX fsync(2) 文档。 除了可能的异常之外，没有为完成回调提供任何参数。

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

中英对照

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

截断文件描述符。 除了可能的异常之外，没有为完成回调提供任何参数。

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

如果文件描述符引用的文件大于 len 个字节，则文件中将仅保留前 len 个字节。

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

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

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

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

中英对照

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

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

fs.lchmod(path, mode, callback)#

中英对照

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

更改符号链接的权限。 除了可能的异常之外，没有为完成回调提供任何参数。

此方法仅在 macOS 上实现。

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

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

中英对照

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

设置符号链接的所有者。 除了可能的异常之外，没有为完成回调提供任何参数。

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

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

中英对照

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

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

除了可能的异常之外，没有为完成回调提供任何参数。

fs.link(existingPath, newPath, callback)#

中英对照

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

创建从 existingPath 到 newPath 的新链接。 有关更多详细信息，请参阅 POSIX link(2) 文档。 除了可能的异常之外，没有为完成回调提供任何参数。

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 是符号链接，则被统计的是链接本身，而不是它引用的文件。

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

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。

异步地创建目录。

回调给出一个可能的异常和创建的第一个目录路径（如果 recursive 为 true），(err[, path])。 当 recursive 为 true 时，如果没有创建目录，则 path 仍然为 undefined。

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

import { mkdir } from 'node:fs';

// 创建 /tmp/a/apple，不管 `/tmp` 和 /tmp/a 是否存在。
mkdir('/tmp/a/apple', { recursive: true }, (err) => {
  if (err) throw err;
});

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

import { mkdir } from 'node:fs';

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

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

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

中英对照

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

创建唯一的临时目录。

生成六个随机字符，附加在所需的 prefix 后面以创建唯一的临时目录。 由于平台的不一致，请避免在 prefix 中尾随 X 字符。 某些平台，尤其是 BSD，可能返回六个以上的随机字符，并将 prefix 中的尾随 X 字符替换为随机字符。

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

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

import { mkdtemp } from 'node:fs';

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

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

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

// 新临时目录的父目录
const tmpDir = tmpdir();

// 这个方法是*不正确的*：
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // 将打印类似于 `/tmpabc123` 的内容。
  // 在文件系统根目录创建一个新的临时目录，而不是在 /tmp 目录中。
});

// 这个方法是*正确的*：
import { sep } from 'node:path';
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // 将打印类似于 `/tmp/abc123` 的内容。
  // 在 /tmp 目录中创建一个新的临时目录。
});

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>

异步地打开文件。 有关更多详细信息，请参阅 POSIX open(2) 文档。

mode 设置文件模式（权限和粘滞位），但前提是文件已创建。 在 Windows 上，只能操作写入权限；请参阅 fs.chmod()。

回调有两个参数 (err, fd)。

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

基于 fs.open() 的函数也表现出这种行为：fs.writeFile()、fs.readFile() 等。

fs.opendir(path[, options], callback)#

中英对照

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> 默认值: 'utf8'
  • bufferSize <number> 当从目录读取时，在内部缓冲的目录条目数。 值越大，性能越好，但内存使用率越高。 默认值: 32
• callback <Function>
  • err <Error>
  • dir <fs.Dir>

异步地打开目录。 有关更多详细信息，请参阅 POSIX opendir(3) 文档。

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

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

fs.read(fd, buffer, offset, length, position, callback)#

中英对照

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> 数据将写入的缓冲区。
• offset <integer> 要写入数据的 buffer 中的位置。
• length <integer> 读取的字节数。
• position <integer> | <bigint> | <null> 指定从文件中开始读取的位置。 如果 position 为 null 或 -1 ，则将从当前文件位置读取数据，并更新文件位置。 如果 position 是整数，则文件位置将保持不变。
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

从 fd 指定的文件中读取数据。

回调被赋予三个参数，(err, bytesRead, buffer)。

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

如果此方法作为其 util.promisify() 版本被调用，则返回具有 bytesRead 和 buffer 属性的 Object 的 promise。

fs.read(fd[, options], callback)#

中英对照

• fd <integer>
• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> 默认值: Buffer.alloc(16384)
  • offset <integer> 默认值: 0
  • length <integer> 默认值: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> 默认值: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

与 fs.read() 函数类似，此版本采用可选的 options 对象。 如果未指定 options 对象，则默认使用上述值。

fs.read(fd, buffer[, options], callback)#

中英对照

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> 数据将写入的缓冲区。
• options <Object>
  • offset <integer> 默认值: 0
  • length <integer> 默认值: buffer.byteLength - offset
  • position <integer> | <bigint> 默认值: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

与 fs.read() 函数类似，此版本采用可选的 options 对象。 如果未指定 options 对象，则默认使用上述值。

fs.readdir(path[, options], callback)#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
  • withFileTypes <boolean> 默认值: false
• callback <Function>
  • err <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>