Node.js v18.18.2 文档

Promise 示例#

基于 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');copy

回调示例#

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

import { unlink } from 'node:fs';

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

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

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

同步示例#

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

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}const { unlinkSync } = require('node:fs');

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

Promise API#

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

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

类：FileHandle#

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

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

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

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

事件：'close'#

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

filehandle.appendFile(data[, options])#

• data <字符串> | <缓冲区> | <类型化数组> | <数据视图> | <异步迭代> | <可迭代> | <流>
• options <对象> | <字符串>
  • encoding <字符串> | <null> 默认值： 'utf8'
• 返回：<Promise>成功后，将执行undefined。

filehandle.writeFile()的别名。

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

filehandle.chmod(mode)#

• mode <integer>文件模式位掩码。
• 返回：<Promise>成功后，将执行undefined。

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

filehandle.chown(uid, gid)#

• uid <整数>文件的新所有者的用户 ID。
• gid <整数>文件的新组的组 ID。
• 返回：<Promise>成功后，将执行undefined。

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

filehandle.close()#

• 返回：<Promise>成功后，将执行undefined。

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

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

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

filehandle.createReadStream([options])#

• options <对象>
  • encoding <字符串> 默认值： null
  • autoClose <布尔值> 默认值： true
  • emitClose <布尔值> 默认值： true
  • start <整数>
  • end <整数> 默认值： Infinity
  • highWaterMark <整数> 默认值： 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');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); copy

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

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

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

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

filehandle.createWriteStream([options])#

• options <对象>
  • encoding <字符串> 默认值： 'utf8'
  • autoClose <布尔值> 默认值： true
  • emitClose <布尔值> 默认值： true
  • start <整数>
• 返回：<fs.WriteStream>

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

如果'error'或'finish' 上的 autoClose设置为 true（默认行为）， 文件描述符将自动关闭。如果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 <缓冲区> | <类型化数组> | <Da​​taView>将填充读取的文件数据的缓冲区。
• offset <integer>缓冲区中开始填充的位置。
• length <整数>要读取的字节数。
• position <整数> | <null>开始从文件读取数据的位置。如果为null，将从当前文件位置读取数据，并更新该位置。如果position是整数，则当前文件位置将保持不变。
• 返回：<Promise>成功后，使用具有两个属性的对象实现：
  • bytesRead <整数>读取的字节数
  • buffer <缓冲区> | <类型化数组> | <Da​​taView>对传入的buffer 参数的引用。

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

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

filehandle.read([options])#

• options <对象>
  • buffer <缓冲区> | <类型化数组> | <Da​​taView>将填充读取的文件数据的缓冲区。默认值： Buffer.alloc(16384)
  • offset <integer>缓冲区中开始填充的位置。 默认值： 0
  • length <整数>要读取的字节数。默认值： buffer.byteLength - offset
  • position <整数> | <null>开始从文件读取数据的位置。如果null，将从当前文件位置读取数据，并更新该位置。如果position是整数，则当前文件位置将保持不变。默认值：： null
• 返回：<Promise>成功后，使用具有两个属性的对象实现：
  • bytesRead <整数>读取的字节数
  • buffer <缓冲区> | <类型化数组> | <Da​​taView>对传入的buffer 参数的引用。

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

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

filehandle.read(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <Da​​taView>将填充读取的文件数据的缓冲区。
• options <对象>
  • offset <integer>缓冲区中开始填充的位置。 默认值： 0
  • length <整数>要读取的字节数。默认值： buffer.byteLength - offset
  • position <integer>开始从文件读取数据的位置。如果null，将从当前文件位置读取数据，并更新该位置。如果position是整数，则当前文件位置将保持不变。默认值：： null
• 返回：<Promise>成功后，使用具有两个属性的对象实现：
  • bytesRead <整数>读取的字节数
  • buffer <缓冲区> | <类型化数组> | <Da​​taView>对传入的buffer 参数的引用。

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

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

filehandle.readableWebStream(options)#

• options <对象>

  • type <字符串> | <undefined>是否打开普通流或'bytes'流。 默认值： undefined

• 返回：<可读流>

返回可用于读取文件数据的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();
})();copy

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

filehandle.readFile(options)#

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

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

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

<FileHandle>必须支持读取。

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

filehandle.readLines([options])#

• options <对象>
  • encoding <字符串> 默认值： null
  • autoClose <布尔值> 默认值： true
  • emitClose <布尔值> 默认值： true
  • start <整数>
  • end <整数> 默认值： Infinity
  • highWaterMark <整数> 默认值： 64 * 1024
• 返回：<readline.InterfaceConstructor>

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

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

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

for await (const line of file.readLines()) {
  console.log(line);
}const { open } = require('node:fs/promises');

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

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

filehandle.readv(buffers[, position])#

• buffers <缓冲区[]> | <TypedArray[]> | <数据视图[]>
• position <整数> | <null>距应读取数据的文件开头的偏移量。如果position不是number，则将从当前位置读取数据。默认值： null
• 返回：<Promise>成功后实现包含两个属性的对象：
  • bytesRead <integer>读取的字节数
  • buffers <缓冲区[]> | <TypedArray[]> | <Da​​taView[]>属性包含对buffers输入的引用。

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

filehandle.stat([options])#

• options <对象>
  • bigint <boolean>返回的<fs.Stats>对象中的数值是否 应为bigint。默认值： false。
• 返回：<Promise>通过文件的<fs.Stats>实现。

filehandle.sync()#

• 返回：<Promise>成功后，将执行undefined。

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

filehandle.truncate(len)#

• len <整数> 默认值： 0
• 返回：<Promise>成功后，执行undefined。

截断文件。

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

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

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

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

如果文件之前短于len字节，则会对其进行扩展，并用空字节 ( '\0' )填充扩展部分：

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

filehandle.utimes(atime, mtime)#

• atime <数字> | <字符串> | <日期>
• mtime <数字> | <字符串> | <日期>
• 返回：< Promise >

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

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

• buffer <缓冲区> | <类型化数组> | <数据视图>
• offset <integer> buffer内要写入的数据开始的起始位置。
• length <integer>从buffer写入的字节数。默认值： buffer.byteLength - offset
• position <整数> | <null>距文件开头的偏移量，应写入buffer中的数据。如果position不是number，则数据将写入当前位置。 有关更多详细信息，请参阅 POSIX pwrite(2)文档。默认值： null
• 返回：< Promise >

将buffer写入文件。

该 Promise 通过包含两个属性的对象来解决：

• bytesWritten <integer>写入的字节数
• buffer <缓冲区> | <类型化数组> | <Da​​taView>对buffer写入的引用 。

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

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

filehandle.write(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图>
• options <对象>
  • offset <整数> 默认值： 0
  • length <整数> 默认值： buffer.byteLength - offset
  • position <整数> 默认值： null
• 返回：< Promise >

将buffer写入文件。

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

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

• string <字符串>
• position <整数> | <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 <字符串> | <缓冲区> | <类型化数组> | <数据视图> | <异步迭代> | <可迭代> | <流>
• options <对象> | <字符串>
  • encoding <字符串> | <null>当data是字符串时预期的字符编码。默认值： 'utf8'
• 返回：< Promise >

异步将数据写入文件，如果文件已存在则替换该文件。 data可以是字符串、缓冲区、<AsyncIterable>或<Iterable>对象。一旦成功， Promise 就得到解决，没有任何争议。

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

<FileHandle>必须支持写入。

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

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

filehandle.writev(buffers[, position])#

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

将<ArrayBufferView>数组写入文件。

该 Promise 通过包含两个属性的对象来解决：

• bytesWritten <integer>写入的字节数
• buffers <缓冲区[]> | <TypedArray[]> | <Da​​taView[]>对buffers输入的引用 。

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

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

filehandle[Symbol.asyncDispose]()#

filehandle.close()的别名。

fsPromises.access(path[, mode])#

• path <字符串> | <缓冲区> | <网址>
• mode <整数> 默认值： fs.constants.F_OK
• 返回：<Promise>成功后，会执行undefined。

测试用户对path指定的文件或目录的权限。mode参数是一个可选整数，用于指定要执行的可访问性检查。mode应该是值fs.constants.F_OK 或由fs.constants.R_OK、 fs.constants.W_OK和fs.constants.X_OK（例如 fs.constants.W_OK | fs.constants.R_OK）。检查文件访问常量以了解mode的可能值。

如果可访问性检查成功，则 Promise 将被解决，但没有任何价值。如果任何可访问性检查失败，则 Promise 将被拒绝并返回<Error>对象。以下示例检查当前进程是否可以读取和写入文件 /etc/passwd 。

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

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

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

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

• path <字符串> | <缓冲区> | <网址> | <FileHandle>文件名或<FileHandle>
• data <字符串> | <缓冲区>
• options <对象> | <字符串>
  • encoding <字符串> | <null> 默认值： 'utf8'
  • mode <整数> 默认值： 0o666
  • flag <string>查看文件系统的支持flags。默认值： 'a'。
• 返回：<Promise>成功后，执行undefined。

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

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

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

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

fsPromises.chmod(path, mode)#

• path <字符串> | <缓冲区> | <网址>
• mode <字符串> | <整数>
• 返回：<Promise>成功后，将执行undefined。

更改文件的权限。

fsPromises.chown(path, uid, gid)#

• path <字符串> | <缓冲区> | <网址>
• uid <整数>
• gid <整数>
• 返回：<Promise>成功后，将执行undefined。

更改文件的所有权。

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

• src <字符串> | <缓冲区> | <URL>要复制的源文件名
• dest <字符串> | <缓冲区> | <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.error('The file could not be copied');
}

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
} copy

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

• src <字符串> | <URL>要复制的源路径。
• dest <字符串> | <URL>要复制到的目标路径。
• options <对象>
  • dereference <boolean>取消引用符号链接。默认值： false。
  • errorOnExist <boolean>当force为false且目标存在时，抛出错误。默认值： false。
  • filter <Function>过滤复制文件/目录的函数。返回 true复制该项目，返回false忽略它。还可以返回 解析为true或false 的 Promise 默认值： undefined。
    • src <string>要复制的源路径。
    • dest <string>要复制到的目标路径。
    • 返回：<布尔值> | < Promise >
  • force <boolean>覆盖现有文件或目录。如果您将其设置为 false 并且目标存在，则复制操作将忽略错误。使用errorOnExist选项更改此行为。 默认值： true。
  • mode <integer>用于复制操作的修饰符。默认值： 0。请参阅fsPromises.copyFile()的mode标志。
  • preserveTimestamps <boolean>何时保留src的true时间戳。默认值： false。
  • recursive <boolean>递归复制目录默认值： false
  • verbatimSymlinks <boolean>当true时，将跳过符号链接的路径解析。默认值： false
• 返回：<Promise>成功后，将执行undefined。

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

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

fsPromises.lchmod(path, mode)#

• path <字符串> | <缓冲区> | <网址>
• mode <整数>
• 返回：<Promise>成功后，将执行undefined。

更改符号链接的权限。

该方法仅在 macOS 上实现。

fsPromises.lchown(path, uid, gid)#

• path <字符串> | <缓冲区> | <网址>
• uid <整数>
• gid <整数>
• 返回：<Promise>成功后， 将执行undefined。

更改符号链接的所有权。

fsPromises.lutimes(path, atime, mtime)#

• path <字符串> | <缓冲区> | <网址>
• atime <数字> | <字符串> | <日期>
• mtime <数字> | <字符串> | <日期>
• 返回：<Promise>成功后， 将执行undefined。

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

fsPromises.link(existingPath, newPath)#

• existingPath <字符串> | <缓冲区> | <网址>
• newPath <字符串> | <缓冲区> | <网址>
• 返回：<Promise>成功后， 将执行undefined。

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

fsPromises.lstat(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <对象>
  • bigint <boolean>返回的<fs.Stats>对象中的数值是否 应为bigint。默认值： false。
• 返回：<Promise> 满足给定符号链接path的<fs.Stats>对象。

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

fsPromises.mkdir(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <对象> | <整数>
  • recursive <布尔值> 默认值： false
  • mode <字符串> | <整数> Windows 不支持。默认值： 0o777。
• 返回：<Promise>成功后，如果recursive 为false ，则满足undefined ，或者如果recursive为true，则满足创建的第一个目录路径。

异步创建目录。

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

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

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

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}const { mkdir } = require('node:fs/promises');
const { join } = require('node:path');

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

  console.log(dirCreation);
  return dirCreation;
}

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

fsPromises.mkdtemp(prefix[, options])#

• prefix <字符串>
• options <字符串> | <对象>
  • encoding <字符串> 默认值： 'utf8'
• 返回：<Promise> 使用包含新创建的临时目录的文件系统路径的字符串来实现。

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

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

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

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

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

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

• path <字符串> | <缓冲区> | <网址>
• flags <字符串> | <number>查看文件系统flags的支持。 默认值： 'r'。
• mode <字符串> | <integer>如果创建文件，则设置文件模式（权限和粘性位）。默认值： 0o666（可读可写）
• 返回：<Promise>通过<FileHandle>对象实现。

打开<FileHandle>。

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

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

fsPromises.opendir(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <对象>
  • encoding <字符串> | <null> 默认值： 'utf8'
  • bufferSize <number>从目录读取时内部缓冲的目录条目数。值越高，性能越好，但内存使用率越高。默认值： 32
  • recursive <boolean>解析的Dir将是一个 包含所有子文件和目录的<AsyncIterable> 。默认值： false
• 返回：<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);
} copy

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

fsPromises.readdir(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <字符串> | <对象>
  • encoding <字符串> 默认值： 'utf8'
  • withFileTypes <布尔值> 默认值： false
  • recursive <布尔值> 默认值： false
• 返回：<Promise> 实现目录中文件名称的数组，不包括'.'和'..'。

读取目录的内容。

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

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

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

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

fsPromises.readFile(path[, options])#

• path <字符串> | <缓冲区> | <网址> | <FileHandle>文件名或FileHandle
• options <对象> | <字符串>
  • encoding <字符串> | <null> 默认值： null
  • flag <string>查看文件系统的支持flags。默认值： 'r'。
  • signal <AbortSignal>允许中止正在进行的 readFile
• 返回：<Promise> 履行文件的内容。

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

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

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

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

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

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

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

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

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

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

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

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

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

fsPromises.readlink(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <字符串> | <对象>
  • encoding <字符串> 默认： 'utf8'
• 返回：<Promise>成功后，将履行linkString。

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

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

fsPromises.realpath(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <字符串> | <对象>
  • encoding <字符串> 默认： '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 <字符串> | <缓冲区> | <网址>
• newPath <字符串> | <缓冲区> | <网址>
• 返回：<Promise>成功后，将执行undefined。

将oldPath重命名为newPath。

fsPromises.rmdir(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <对象>
  • maxRetries <整数>如果是EBUSY、EMFILE、ENFILE、ENOTEMPTY或 EPERM遇到错误时，Node.js 会重试该操作，每次尝试都会延长retryDelay毫秒的线性退避等待时间。该选项代表重试次数。如果recursive 选项不是true ，则忽略此选项。默认值： 0。
  • recursive <boolean>如果为true，则执行递归目录删除。在递归模式下，操作失败时会重试。默认值： false。 已弃用。
  • retryDelay <整数>两次重试之间等待的时间（以毫秒为单位）。如果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 <字符串> | <缓冲区> | <网址>
• options <对象>
  • force <boolean>当true时，如果path不存在，则异常将被忽略。默认值： false。
  • maxRetries <整数>如果是EBUSY、EMFILE、ENFILE、ENOTEMPTY或 EPERM遇到错误时，Node.js 将重试该操作，每次尝试都会延长retryDelay毫秒的线性退避等待时间。该选项代表重试次数。如果recursive 选项不是true ，则忽略此选项。默认值： 0。
  • recursive <boolean>如果为true，则执行递归目录删除。在递归模式下，操作失败时会重试。默认值： false。
  • retryDelay <整数>两次重试之间等待的时间（以毫秒为单位）。如果recursive选项不是true ，则忽略此选项。 默认值： 100。
• 返回：<Promise>成功后，将执行undefined。

删除文件和目录（以标准 POSIX rm实用程序为模型）。

fsPromises.stat(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <对象>
  • bigint <boolean>返回的<fs.Stats>对象中的数值是否 应为bigint。默认值： false。
• 返回：<Promise> 满足给定path的<fs.Stats>对象。

fsPromises.statfs(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <对象>
  • bigint <boolean>返回的<fs.StatFs>对象中的数值是否 应为bigint。默认值： false。
• 返回：<Promise>满足给定path的<fs.StatFs>对象。

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

• target <字符串> | <缓冲区> | <网址>
• path <字符串> | <缓冲区> | <网址>
• type <字符串> 默认值： 'file'
• 返回：<Promise>成功后，将执行undefined。

创建符号链接。

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

fsPromises.truncate(path[, len])#

• path <字符串> | <缓冲区> | <网址>
• len <整数> 默认值： 0
• 返回：<Promise>成功后，将执行undefined。

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

fsPromises.unlink(path)#

• path <字符串> | <缓冲区> | <网址>
• 返回：<Promise>成功后，将执行undefined。

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

fsPromises.utimes(path, atime, mtime)#

• path <字符串> | <缓冲区> | <网址>
• atime <数字> | <字符串> | <日期>
• mtime <数字> | <字符串> | <日期>
• 返回：<Promise>成功后，会执行undefined。

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

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

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

fsPromises.watch(filename[, options])#

• filename <字符串> | <缓冲区> | <网址>
• options <字符串> | <对象>
  • persistent <boolean>指示只要正在监视文件，进程是否应继续运行。默认值： true。
  • recursive <boolean>指示是否应监视所有子目录，或仅监视当前目录。这在指定目录时适用，并且仅在支持的平台上适用（请参阅注意事项）。默认值： false。
  • encoding <string>指定传递给侦听器的文件名所使用的字符编码。默认值： 'utf8'。
  • signal <AbortSignal>用于在观察者应该停止时发出信号的<AbortSignal>。
• 返回：具有以下属性的对象的 <AsyncIterator> ：
  • eventType <string>更改的类型
  • filename <字符串> | <缓冲区> | <null>文件名已更改。

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

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

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

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

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

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

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

• file <字符串> | <缓冲区> | <网址> | <FileHandle>文件名或FileHandle
• data <字符串> | <缓冲区> | <类型化数组> | <数据视图> | <异步迭代> | <可迭代> | <流>
• options <对象> | <字符串>
  • encoding <字符串> | <null> 默认值： 'utf8'
  • mode <整数> 默认值： 0o666
  • flag <string>查看文件系统的支持flags。默认值： 'w'。
  • signal <AbortSignal>允许中止正在进行的 writeFile
• 返回：<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 });

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

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

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

fsPromises.constants#

• <对象>

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

回调接口#

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

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

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

• path <字符串> | <缓冲区> | <网址>
• mode <整数> 默认值： fs.constants.F_OK
• callback <函数>
  • err <错误>

测试用户对path指定的文件或目录的权限。mode参数是一个可选整数，用于指定要执行的可访问性检查。mode应该是值fs.constants.F_OK 或由fs.constants.R_OK、 fs.constants.W_OK和fs.constants.X_OK（例如 fs.constants.W_OK | fs.constants.R_OK）。检查文件访问常量以了解mode的可能值。

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

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

const file = 'package.json';

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

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

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

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

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

写（不推荐）

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

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

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

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

写（推荐）

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

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

    throw err;
  }

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

阅读（不推荐）

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

    throw err;
  }

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

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

阅读（推荐）

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

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

    throw err;
  }

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

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

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

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

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

• path <字符串> | <缓冲区> | <网址> | <number>文件名或文件描述符
• data <字符串> | <缓冲区>
• options <对象> | <字符串>
  • encoding <字符串> | <null> 默认值： 'utf8'
  • mode <整数> 默认值： 0o666
  • flag <string>查看文件系统的支持flags。默认值： 'a'。
• callback <函数>
  • err <错误>

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

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

import { appendFile } from 'node:fs';

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

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

import { appendFile } from 'node:fs';

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

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

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

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

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

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

fs.chmod(path, mode, callback)#

• path <字符串> | <缓冲区> | <网址>
• mode <字符串> | <整数>
• callback <函数>
  • err <错误>

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

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

import { chmod } from 'node:fs';

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

文件模式#

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

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

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

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

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

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

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

• path <字符串> | <缓冲区> | <网址>
• uid <整数>
• gid <整数>
• callback <函数>
  • err <错误>

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

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

fs.close(fd[, callback])#

• fd <整数>
• callback <函数>
  • err <错误>

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

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

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

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

• src <字符串> | <缓冲区> | <URL>要复制的源文件名
• dest <字符串> | <缓冲区> | <URL>复制操作的目标文件名
• mode <integer>用于复制操作的修饰符。默认值： 0。
• callback <函数>

异步复制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 will be created or overwritten by default.
copyFile('source.txt', 'destination.txt', callback);

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

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

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

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

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

fs.createReadStream(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <字符串> | <对象>
  • flags <string>查看文件系统的支持flags。默认值： 'r'。
  • encoding <字符串> 默认值： null
  • fd <整数> | <文件句柄> 默认值： null
  • mode <整数> 默认值： 0o666
  • autoClose <布尔值> 默认值： true
  • emitClose <布尔值> 默认值： true
  • start <整数>
  • end <整数> 默认值： Infinity
  • highWaterMark <整数> 默认值： 64 * 1024
  • fs <对象> | <null> 默认值： null
  • signal <中止信号> | <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';

// 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); copy

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

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

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

import { createReadStream } from 'node:fs';

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

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

fs.createWriteStream(path[, options])#

• path <字符串> | <缓冲区> | <网址>
• options <字符串> | <对象>
  • flags <string>查看文件系统的支持flags。默认值： 'w'。
  • encoding <字符串> 默认值： 'utf8'
  • fd <整数> | <文件句柄> 默认值： null
  • mode <整数> 默认值： 0o666
  • autoClose <布尔值> 默认值： true
  • emitClose <布尔值> 默认值： true
  • start <整数>
  • fs <对象> | <null> 默认值： null
  • signal <中止信号> | <null> 默认值： null
• 返回：<fs.WriteStream>

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

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

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

通过提供fs选项，可以覆盖open、write 、 writev相应的 fs 实现和close。 在不使用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 <字符串> | <缓冲区> | <网址>
• callback <函数>
  • exists <布尔值>

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

import { exists } from 'node:fs';

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

此回调的参数与其他 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;
        });
      }
    });
  }
}); copy

写（推荐）

import { open, close } from 'node:fs';
open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

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

阅读（不推荐）

import { 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');
  }
}); copy

阅读（推荐）

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

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

    throw err;
  }

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

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

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

fs.fchmod(fd, mode, callback)#

• fd <整数>
• mode <字符串> | <整数>
• callback <函数>
  • err <错误>

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

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

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

• fd <整数>
• uid <整数>
• gid <整数>
• callback <函数>
  • err <错误>

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

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

fs.fdatasync(fd, callback)#

• fd <整数>
• callback <函数>
  • err <错误>

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

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

• fd <整数>
• options <对象>
  • bigint <boolean>返回的<fs.Stats>对象中的数值是否 应为bigint。默认值： false。
• callback <函数>
  • err <错误>
  • stats <fs.Stats>

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

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

fs.fsync(fd, callback)#

• fd <整数>
• callback <函数>
  • err <错误>

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

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

• fd <整数>
• len <整数> 默认值： 0
• callback <函数>
  • err <错误>

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

有关更多详细信息，请参阅 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;
  }
}); copy

如果文件之前短于len字节，则会对其进行扩展，并用空字节 ( '\0' )填充扩展部分：

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

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

• fd <整数>
• atime <数字> | <字符串> | <日期>
• mtime <数字> | <字符串> | <日期>
• callback <函数>
  • err <错误>

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

fs.lchmod(path, mode, callback)#

• path <字符串> | <缓冲区> | <网址>
• mode <整数>
• callback <函数>
  • err <错误> | <聚合错误>

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

该方法仅在 macOS 上实现。

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

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

• path <字符串> | <缓冲区> | <网址>
• uid <整数>
• gid <整数>
• callback <函数>
  • err <错误>

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

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

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

• path <字符串> | <缓冲区> | <网址>
• atime <数字> | <字符串> | <日期>
• mtime <数字> | <字符串> | <日期>
• callback <函数>
  • err <错误>

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

除了可能的异常之外，不会向完成回调提供任何参数。

fs.link(existingPath, newPath, callback)#

• existingPath <字符串> | <缓冲区> | <网址>
• newPath <字符串> | <缓冲区> | <网址>
• callback <函数>
  • err <错误>

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

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

• path <字符串> | <缓冲区> | <网址>
• options <对象>
  • bigint <boolean>返回的<fs.Stats>对象中的数值是否 应为bigint。默认值： false。
• callback <函数>
  • err <错误>
  • stats <fs.Stats>

检索路径引用的符号链接的<fs.Stats> 。该回调获取两个参数(err, stats)，其中stats是一个<fs.Stats> 对象。lstat()与stat()相同，但如果path是符号链接，则链接本身会被统计，而不是它引用的文件。

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

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

• path <字符串> | <缓冲区> | <网址>
• options <对象> | <整数>
  • recursive <布尔值> 默认值： false
  • mode <字符串> | <整数> Windows 不支持。默认值： 0o777。
• callback <函数>
  • err <错误>
  • path <字符串> | <undefined>仅当创建的目录的 recursive设置为true 时才出现。

异步创建目录。

回调可能会出现异常，如果recursive为true，则创建的第一个目录路径为(err[, path])。 如果未创建目录（例如，如果之前创建过目录），则当recursive为true时，path仍可以为undefined。

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

import { mkdir } from 'node:fs';

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

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

import { mkdir } from 'node:fs';

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

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

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

• prefix <字符串>
• options <字符串> | <对象>
  • encoding <字符串> 默认值： 'utf8'
• callback <函数>
  • err <错误>
  • directory <字符串>

创建一个唯一的临时目录。

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

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

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

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

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

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

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

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

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

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

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

• path <字符串> | <缓冲区> | <网址>
• flags <字符串> | <number>查看文件系统flags的支持。 默认值： 'r'。
• mode <字符串> | <integer> 默认值： 0o666（可读可写）
• callback <函数>
  • err <错误>
  • fd <整数>

异步文件打开。有关更多详细信息，请参阅 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 <字符串> | <缓冲区> | <网址>
• options <对象>
  • encoding <字符串> | <null> 默认值： 'utf8'
  • bufferSize <number>从目录读取时内部缓冲的目录条目数。值越高，性能越好，但内存使用率越高。默认值： 32
  • recursive <布尔值> 默认值： false
• callback <函数>
  • err <错误>
  • dir <fs.Dir>

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

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

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

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