文件系统

稳定性：2 - 稳定

node:fs 模块启用了一种基于标准 POSIX 函数建模的文件系统交互方式。

要使用基于 Promise 的 API：

import * as fs from 'node:fs/promises';

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

要使用回调和同步 API：

import * as fs from 'node:fs';

const fs = require('node:fs');

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

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

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

try {
  await unlink('/tmp/hello');
  console.log('成功删除 /tmp/hello');
} catch (error) {
  console.error('发生了错误：', error.message);
}

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

(async function(path) {
  try {
    await unlink(path);
    console.log(`成功删除 ${path}`);
  } catch (error) {
    console.error('发生了错误：', error.message);
  }
})('/tmp/hello');

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

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('成功删除 /tmp/hello');
});

const { unlink } = require('node:fs');

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('成功删除 /tmp/hello');
});

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

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

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('成功删除 /tmp/hello');
} catch (err) {
  // 处理错误
}

const { unlinkSync } = require('node:fs');

try {
  unlinkSync('/tmp/hello');
  console.log('成功删除 /tmp/hello');
} catch (err) {
  // 处理错误
}

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

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

FileHandle 对象是数值型文件描述符的对象包装器。

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

所有 FileHandle 对象都是 EventEmitter。

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

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

filehandle.appendFile(data, options?): void

filehandle.writeFile() 的别名。

操作文件句柄时，无法更改通过 fsPromises.open() 设置的模式。因此，这等同于 filehandle.writeFile()。

filehandle.chmod(mode): void

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

filehandle.chown(uid, gid): void

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

filehandle.close(): void

• 返回：Promise 成功时兑现为 undefined。

等待句柄上的所有待处理操作完成后关闭文件句柄。

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

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

filehandle.createReadStream(options?): void

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?): void

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

默认情况下，如果 autoClose 在 'error' 或 'finish' 时设置为 true，文件描述符将自动关闭。如果 autoClose 为 false，即使发生错误，文件描述符也不会关闭。应用程序负责关闭文件描述符，并确保不会发生文件描述符泄漏。

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

filehandle.datasync(): void

• 返回：Promise 成功时兑现为 undefined。

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

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

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

filehandle.pull(...transforms?, options?): void

稳定性：1 - 实验性

使用 node:stream/iter pull 模型将文件内容作为异步迭代器返回。读取以 chunkSize 字节块（默认 128 KB）执行。如果提供了转换，它们将通过 stream/iter pull() 应用。

当迭代器被消费时文件句柄被锁定，当迭代完成、发生错误或消费者中断时解锁。

此函数仅在启用 --experimental-stream-iter 标志时可用。

filehandle.pullSync(...transforms?, options?): void

稳定性：1 - 实验性

filehandle.pull() 的同步对应物。返回一个同步迭代器，使用主线程上的同步 I/O 读取文件。读取以 chunkSize 字节块（默认 128 KB）执行。

当迭代器被消费时文件句柄被锁定。与异步 pull() 不同，此方法不支持 AbortSignal，因为所有操作都是同步的。

此函数仅在启用 --experimental-stream-iter 标志时可用。

filehandle[Symbol.asyncDispose](): void

调用 filehandle.close() 并返回一个 promise，当文件句柄关闭时该 promise 会兑现。

此方法支持将文件句柄与 await using 一起使用。作用域退出时，文件将自动关闭。有关更多信息，请参阅 MDN 关于 using 语句的文档。

fsPromises.access(path, mode?): void

测试用户对 path 指定的文件或目录的权限。mode 参数是一个可选整数，指定要执行的可访问性检查。mode 应为值 fs.constants.F_OK 或由任何 fs.constants.R_OK、fs.constants.W_OK 和 fs.constants.X_OK 的按位 OR 组成的掩码（例如 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('可以访问');
} catch {
  console.error('无法访问');
}

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

fsPromises.appendFile(path, data, options?): void

异步地向文件追加数据，如果文件尚不存在则创建该文件。 data 可以是字符串、缓冲区、AsyncIterable 或 Iterable 对象。

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

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

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

fsPromises.chmod(path, mode): void

更改文件的权限。

fsPromises.chown(path, uid, gid): void

更改文件的所有权。

fsPromises.copyFile(src, dest, mode?): void

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

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

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

try {
  await copyFile('source.txt', 'destination.txt');
  console.log('source.txt 已复制到 destination.txt');
} catch {
  console.error('无法复制该文件');
}

// 通过使用 COPYFILE_EXCL，如果 destination.txt 存在，操作将失败。
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
  console.log('source.txt 已复制到 destination.txt');
} catch {
  console.error('无法复制该文件');
}

fsPromises.cp(src, dest, options?): void

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

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

fsPromises.glob(pattern, options?): void

当启用 followSymlinks 时，检测到的符号链接循环不会被递归遍历。

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

for await (const entry of glob('**/*.js'))
  console.log(entry);

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

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

稳定性：0 - 已弃用

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

更改符号链接上的权限。

此方法仅在 macOS 上实现。

• path string | Buffer | URL
• uid integer
• gid integer
• 返回：Promise 成功时 fulfilled 的值为 undefined。

更改符号链接的所有权。

• path string | Buffer | URL
• atime number | string | Date
• mtime number | string | Date
• 返回：Promise 成功时 fulfilled 值为 undefined。

以与 [fs.utimes][] 相同的方式更改文件的访问和修改时间，不同之处在于如果路径引用符号链接，则链接不会被解引用：相反，符号链接本身的时间戳会被更改。

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

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

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

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

• path string | Buffer | URL
• options Object | integer
  • recursive boolean 默认： false
  • mode string | integer 在 Windows 上不支持。有关更多详细信息，请参阅 文件模式。默认： 0o777。
• 返回：Promise 成功时，如果 recursive 为 false 则 fulfilled 为 undefined，如果 recursive 为 true 则 fulfilled 为创建的第一个目录路径。

异步创建目录。

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

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(`已创建 ${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);

fs.promises.mkdtemp(): void

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

mkdtemp(): void

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

此函数和结果对象上的处置函数都是异步的，因此应结合 await + await using 使用，例如： await using dir = await fsPromises.mkdtempDisposable('prefix')。

有关显式资源管理的更多信息，请参阅 MDN 关于 using 语句的文档。

详细信息，请参阅 [mkdtempDisposable()][] 的文档。

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

open(): void

打开一个 FileHandle。

请参阅 POSIX open(2) 文档了解更多详情。

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

opendir(): void

异步打开一个目录以进行迭代扫描。请参阅 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?): void

读取目录的内容。

可选的 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?): void

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

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

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

如果提供了 buffer 且未指定编码，返回的 Buffer 将 是所提供缓冲区上的一个视图，其中只包含已读取的字节。如果 所提供的缓冲区太小，无法容纳整个文件，则该 promise 将被 拒绝。

当 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();

可以使用 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 必须支持读取。

使用预分配缓冲区和 buffer 选项的示例：

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

const buf = Buffer.alloc(16384);
const contents = await readFile('/path/to/file', { buffer: buf });
console.log(contents); // `buf` 上仅包含已读取字节的视图

使用返回缓冲区的函数时使用 buffer 选项的示例：

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

const contents = await readFile('/path/to/file', {
  buffer: (size) => Buffer.alloc(size),
});
console.log(contents);

fsPromises.readlink(path, options?): void

读取 path 引用的符号链接内容。请参阅 POSIX readlink(2) 文档了解更多详情。成功时 Promise 兑现为 linkString。

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

fsPromises.realpath(path, options?): void

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

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

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

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

fsPromises.rename(oldPath, newPath): void

将 oldPath 重命名为 newPath。

fsPromises.rmdir(path, options?): void

移除由 path 标识的目录。

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

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

fsPromises.rm(path, options?): void

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

fsPromises.stat(path, options?): void

fsPromises.statfs(path, options?): void

fsPromises.symlink(target, path, type?): void

创建一个符号链接。

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

fsPromises.truncate(path, len?): void

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

fsPromises.unlink(path): void

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

fsPromises.utimes(path, atime, mtime): void

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

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

• 值可以是代表 Unix 纪元时间的数字、Date，或 数字字符串如 '123456789.0'。
• 如果值无法转换为数字，或是 NaN、Infinity 或 -Infinity，将抛出 Error。

fsPromises.watch(filename, options?): void

返回一个异步迭代器，监视 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?): void

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

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

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

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

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

在不等待 Promise 结算的情况下多次在同一文件上使用 fsPromises.writeFile() 是不安全的。

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

可以使用 AbortSignal 取消 fsPromises.writeFile()。 取消是“尽力而为”，可能仍会有少量数据 被写入。

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

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

  // 在 Promise 结算前中止请求。
  controller.abort();

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

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

• 类型：对象

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

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

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

fs.access(path, mode?, callback): void

测试用户对 path 指定的文件或目录的权限。mode 参数是一个可选的整数，指定要执行的访问检查。mode 应该是值 fs.constants.F_OK 或由 fs.constants.R_OK、fs.constants.W_OK 和 fs.constants.X_OK 中任意一个按位 OR 组成的掩码（例如 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): void

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

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

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', (err) => {
  if (err) throw err;
  console.log('“data to append” 已附加到文件！');
});

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