Node.js v24.0.0 文档

类: FileHandle#

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

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

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

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

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

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

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

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

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

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

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

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

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 中的任何一个的按位 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('can access');
} catch {
  console.error('cannot access');
} copy

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

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

• path <string> | <Buffer> | <URL> | <FileHandle> 文件名或 <FileHandle>
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> 默认值: 'utf8'
  • mode <integer> 默认值: 0o666
  • flag <string> 参见 文件系统 flags 的支持。 默认值: 'a'。
  • flush <boolean> 如果为 true，则在关闭底层文件描述符之前将其刷新。 默认值: false。
• 返回: <Promise> 成功时兑现为 undefined。

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

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

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

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

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：复制操作将尝试创建一个写时复制的 reflink。如果平台不支持写时复制，则使用备用复制机制。
  • fs.constants.COPYFILE_FICLONE_FORCE：复制操作将尝试创建一个写时复制的 reflink。如果平台不支持写时复制，则操作将失败。
• 返回: <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 <string> | <URL> 要复制的源路径。
• dest <string> | <URL> 要复制到的目标路径。
• options <Object>
  • dereference <boolean> 解引用符号链接。 默认值: false。
  • errorOnExist <boolean> 当 force 为 false 并且目标存在时，抛出一个错误。 默认值: false。
  • filter <Function> 用于过滤复制的文件/目录的函数。 返回 true 以复制该项，返回 false 以忽略它。 忽略目录时，其所有内容也将被跳过。 也可以返回一个解析为 true 或 false 的 Promise。默认值: undefined。
    • src <string> 要复制的源路径。
    • dest <string> 要复制到的目标路径。
    • 返回: <boolean> | <Promise> 一个可以强制转换为 boolean 的值，或者一个解析为此值的 Promise。
  • force <boolean> 覆盖现有文件或目录。如果将此选项设置为 false 且目标存在，则复制操作将忽略错误。使用 errorOnExist 选项来更改此行为。默认值: true。
  • mode <integer> 复制操作的修饰符。默认值: 0。 请参阅 fsPromises.copyFile() 的 mode 标志。
  • preserveTimestamps <boolean> 当 true 时，将保留来自 src 的时间戳。默认值: false。
  • recursive <boolean> 递归复制目录。 默认值: false
  • verbatimSymlinks <boolean> 当 true 时，将跳过符号链接的路径解析。默认值: false
• 返回: <Promise> 成功时兑现为 undefined。

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

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

fsPromises.glob(pattern[, options])#

• pattern <string> | <string[]>
• options <Object>
  • cwd <string> 当前工作目录。 默认值: process.cwd()
  • exclude <Function> | <string[]> 用于过滤掉文件/目录的函数或要排除的 glob 模式列表。 如果提供一个函数，返回 true 以排除该项，返回 false 以包含该项。 默认值: undefined。
  • withFileTypes <boolean> 如果 glob 应该将路径作为 Dirent 返回，则为 true，否则为 false。 默认值: false。
• 返回: <AsyncIterator> 一个 AsyncIterator，它产生与模式匹配的文件的路径。

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

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 引用符号链接，在这种情况下，将对链接本身进行 stat，而不是对其引用的文件进行 stat。 有关更多详细信息，请参阅 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(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 <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: '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 <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
  • 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 <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
  • withFileTypes <boolean> 默认值: false
  • recursive <boolean> 如果为 true，则递归读取目录的内容。 在递归模式下，它将列出所有文件、子文件和目录。 默认值: 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 <string> | <Buffer> | <URL> | <FileHandle> 文件名或 FileHandle
• options <Object> | <string>
  • encoding <string> | <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 <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• 返回: <Promise> 成功后使用 linkString 来实现。

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

可选的 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.statfs(path[, options])#

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

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

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

创建符号链接。

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

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> | <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 <string> | <Buffer> | <URL> | <FileHandle> 文件名或 FileHandle
• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> 默认值: 'utf8'
  • mode <integer> 默认值: 0o666
  • flag <string> 参阅文件系统 flags 的支持。 默认值: 'w'。
  • flush <boolean> 如果所有数据都已成功写入文件，并且 flush 为 true，则使用 filehandle.sync() 来刷新数据。 默认值: false。
  • signal <AbortSignal> 允许中止正在进行的 writeFile
• 返回: <Promise> 成功时兑现为 undefined。

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

如果 data 是 buffer，则忽略 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 });

  // 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#

• <Object>

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

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 中的任何一个的按位 OR 组成的掩码（例如 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 <string> | <Buffer> | <URL> | <number> 文件名或文件描述符
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> 默认值: 'utf8'
  • mode <integer> 默认值: 0o666
  • flag <string> 参见 文件系统 flags 的支持。 默认值: 'a'。
  • flush <boolean> 如果为 true，则在关闭底层文件描述符之前将其刷新。 默认值: false。
• callback <Function>
  • err <Error>

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

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

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

异步将 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：复制操作将尝试创建一个写时复制的 reflink。如果平台不支持写时复制，则使用备用复制机制。
• fs.constants.COPYFILE_FICLONE_FORCE：复制操作将尝试创建一个写时复制的 reflink。如果平台不支持写时复制，则操作将失败。

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 <string> | <URL> 要复制的源路径。
• dest <string> | <URL> 要复制到的目标路径。
• options <Object>
  • dereference <boolean> 解引用符号链接。 默认值: false。
  • errorOnExist <boolean> 当 force 为 false 并且目标存在时，抛出一个错误。 默认值: false。
  • filter <Function> 用于过滤复制的文件/目录的函数。 返回 true 以复制该项，返回 false 以忽略它。 忽略目录时，其所有内容也将被跳过。 也可以返回一个解析为 true 或 false 的 Promise。默认值: undefined。
    • src <string> 要复制的源路径。
    • dest <string> 要复制到的目标路径。
    • 返回: <boolean> | <Promise> 一个可以强制转换为 boolean 的值，或者一个解析为此值的 Promise。
  • force <boolean> 覆盖现有文件或目录。如果将此选项设置为 false 且目标存在，则复制操作将忽略错误。使用 errorOnExist 选项来更改此行为。默认值: true。
  • mode <integer> 复制操作的修饰符。 默认值: 0。 参见 fs.copyFile() 的 mode 标志。
  • preserveTimestamps <boolean> 当 true 时，将保留来自 src 的时间戳。默认值: false。
  • recursive <boolean> 递归复制目录。 默认值: false
  • verbatimSymlinks <boolean> 当 true 时，将跳过符号链接的路径解析。默认值: false
• callback <Function>
  • err <Error>

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

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

fs.createReadStream(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> 参见 文件系统 flags 的支持。默认值: 'r'。
  • encoding <string> 默认值: null
  • fd <integer> | <FileHandle> 默认值: null
  • mode <integer> 默认值: 0o666
  • autoClose <boolean> 默认值: true
  • emitClose <boolean> 默认值: true
  • start <integer>
  • end <integer> 默认值: Infinity
  • highWaterMark <integer> 默认值: 64 * 1024
  • fs <Object> | <null> 默认值: null
  • signal <AbortSignal> | <null> 默认值: null
• 返回: <fs.ReadStream>

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

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

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

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

通过提供 fs 选项，可以覆盖相应的 fs 实现，用于 open、read 和 close。 当提供 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 <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> 参见 文件系统 flags 的支持。默认值: 'w'。
  • encoding <string> 默认值: 'utf8'
  • fd <integer> | <FileHandle> 默认值: null
  • mode <integer> 默认值: 0o666
  • autoClose <boolean> 默认值: true
  • emitClose <boolean> 默认值: true
  • start <integer>
  • fs <Object> | <null> 默认值: null
  • signal <AbortSignal> | <null> 默认值: null
  • highWaterMark <number> 默认值: 16384
  • flush <boolean> 如果为 true，则在关闭底层文件描述符之前将其刷新。 默认值: false。
• 返回: <fs.WriteStream>

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

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

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

通过提供 fs 选项，可以覆盖相应的 fs 实现，用于 open、write、writev 和 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 <string> | <Buffer> | <URL>
• callback <Function>
  • exists <boolean>

通过检查文件系统，测试给定 path 上的元素是否存在。然后使用 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() 的原因之一。

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

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

写入（不推荐）

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

如果文件之前短于 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.glob(pattern[, options], callback)#

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> 当前工作目录。 默认值: process.cwd()
  • exclude <Function> | <string[]> 用于过滤掉文件/目录的函数或要排除的 glob 模式列表。 如果提供一个函数，返回 true 以排除该项，返回 false 以包含该项。 默认值: undefined。
  • withFileTypes <boolean> 如果 glob 应该将路径作为 Dirent 返回，则为 true，否则为 false。 默认值: false。

• callback <Function>

  • err <Error>

• 检索与指定模式匹配的文件。

import { glob } from 'node:fs';

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});const { glob } = require('node:fs');

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});copy

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 是符号链接，则对链接本身进行 stat，而不是对其引用的文件进行 stat。

有关更多详细信息，请参见 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> 仅当使用设置为 true 的 recursive 创建目录时才存在。

异步地创建一个目录。

回调会得到一个可能的异常，如果 recursive 为 true，则会得到第一个创建的目录路径，(err[, path])。 如果未创建任何目录（例如，如果先前已创建），则当 recursive 为 true 时，path 仍然可以是 undefined。

可选的 options 参数可以是一个整数，用于指定 mode（权限和粘滞位），也可以是一个具有 mode 属性和 recursive 属性的对象，该属性指示是否应创建父目录。 当 path 是现有目录时，调用 fs.mkdir() 仅当 recursive 为 false 时才会导致错误。 如果 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 <string> | <Buffer> | <URL>
• 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';
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 <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.openAsBlob(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • type <string> blob 的可选 mime 类型。
• 返回: <Promise> 成功时使用 <Blob> 完成。

返回一个 <Blob>，其数据由给定文件支持。

在创建 <Blob> 后，不得修改该文件。 任何修改都会导致读取 <Blob> 数据失败，并显示 DOMException 错误。 在创建 Blob 时以及在每次读取之前，对文件执行同步 stat 操作，以便检测文件数据是否已在磁盘上修改。

import { openAsBlob } from 'node:fs';

const blob = await openAsBlob('the.file.txt');
const ab = await blob.arrayBuffer();
blob.stream();const { openAsBlob } = require('node:fs');

(async () => {
  const blob = await openAsBlob('the.file.txt');
  const ab = await blob.arrayBuffer();
  blob.stream();
})();copy

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> 默认值: 'utf8'
  • bufferSize <number> 从目录读取时内部缓冲的目录条目的数量。 较高的值可以带来更好的性能，但更高的内存使用率。 默认值: 32
  • recursive <boolean> 默认值: false
• 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()ed 版本，它会返回一个 Object 的 promise，该 Object 具有 bytesRead 和 buffer 属性。

fs.read() 方法从文件描述符 (fd) 指定的文件中读取数据。 length 参数指示 Node.js 将尝试从内核读取的最大字节数。 但是，由于各种原因，实际读取的字节数 (bytesRead) 可能低于指定的 length。

例如

• 如果文件短于指定的 length，则 bytesRead 将设置为实际读取的字节数。
• 如果在缓冲区可以被填满之前文件遇到 EOF（文件结束），Node.js 将读取所有可用字节，直到遇到 EOF，并且回调中的 bytesRead 参数将指示实际读取的字节数，这可能小于指定的 length。
• 如果文件位于慢速网络 filesystem 上，或者在读取过程中遇到任何其他问题，则 bytesRead 可能低于指定的 length。

因此，当使用 fs.read() 时，重要的是检查 bytesRead 值以确定实际从文件中读取了多少字节。 根据您的应用程序逻辑，您可能需要处理 bytesRead 低于指定 length 的情况，例如，如果您需要最小字节数，则将读取调用包装在循环中。

此行为类似于 POSIX preadv2 函数。

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
  • recursive <boolean> 如果为 true，则递归地读取目录的内容。 在递归模式下，它将列出所有文件、子文件和目录。 默认值: false。
• callback <Function>
  • err <Error>
  • files <string[]> | <Buffer[]> | <fs.Dirent[]>

读取目录的内容。 回调获取两个参数 (err, files)，其中 files 是目录中文件名（不包括 '.' 和 '..'）的数组。

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

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

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

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

• path <string> | <Buffer> | <URL> | <integer> 文件名或文件描述符
• options <Object> | <string>
  • encoding <string> | <null> 默认值: null
  • flag <string> 参见文件系统 flags 的支持。 默认值: 'r'。
  • signal <AbortSignal> 允许中止正在进行的 readFile
• callback <Function>
  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

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

import { readFile } from 'node:fs';

readFile('/etc/passwd', (err, data) => {
  if (err) throw err;
  console.log(data);
}); copy

回调传递两个参数 (err, data)，其中 data 是文件的内容。

如果未指定编码，则返回原始缓冲区。

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

import { readFile } from 'node:fs';

readFile('/etc/passwd', 'utf8', callback); copy

当路径是一个目录时，fs.readFile() 和 fs.readFileSync() 的行为是平台相关的。 在 macOS、Linux 和 Windows 上，将返回一个错误。 在 FreeBSD 上，将返回目录内容的表示形式。

import { readFile } from 'node:fs';

// macOS, Linux, and Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: illegal operation on a directory, read <directory>]
});

//  FreeBSD
readFile('<directory>', (err, data) => {
  // => null, <data>
}); copy

可以使用 AbortSignal 中止正在进行的请求。 如果请求被中止，则使用 AbortError 调用回调。

import { readFile } from 'node:fs';

const controller = new AbortController();
const signal = controller.signal;
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
});
// When you want to abort the request
controller.abort(); copy

fs.readFile() 函数缓冲整个文件。 为了最大限度地降低内存成本，在可能的情况下，首选通过 fs.createReadStream() 进行流式传输。

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

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

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

读取 path 引用的符号链接的内容。 回调获取两个参数 (err, linkString)。

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

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

fs.readv(fd, buffers[, position], callback)#

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> 默认值: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

从 fd 指定的文件中读取，并使用 readv() 写入到 ArrayBufferView 数组。

position 是应从中读取数据的文件的起始偏移量。 如果 typeof position !== 'number'，则将从当前位置读取数据。

回调将获得三个参数：err、bytesRead 和 buffers。 bytesRead 是从文件中读取的字节数。

如果此方法作为其 util.promisify() 版本调用，它将返回一个带有 bytesRead 和 buffers 属性的 Object 的 Promise。

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

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

通过解析 .、.. 和符号链接异步计算规范路径名。

规范路径名不一定是唯一的。 硬链接和绑定挂载可以通过多个路径名公开文件系统实体。

此函数行为类似于 realpath(3)，但有一些例外

1. 在不区分大小写的文件系统上不执行大小写转换。

2. 符号链接的最大数量与平台无关，并且通常（远）高于本机 realpath(3) 实现支持的数量。

callback 获取两个参数 (err, resolvedPath)。 可以使用 process.cwd 来解析相对路径。

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

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

如果 path 解析为套接字或管道，则该函数将返回该对象的系统相关名称。

不存在的路径会导致 ENOENT 错误。 error.path 是绝对文件路径。

fs.realpath.native(path[, options], callback)#

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

异步 realpath(3)。

callback 获取两个参数 (err, resolvedPath)。

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

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

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

fs.rename(oldPath, newPath, callback)#

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

异步地将 oldPath 处的文件重命名为作为 newPath 提供的路径名。 如果 newPath 已经存在，它将被覆盖。 如果 newPath 处存在目录，则会引发错误。 除了可能的异常之外，不会向完成回调提供任何参数。

另见: rename(2)。

import { rename } from 'node:fs';

rename('oldFile.txt', 'newFile.txt', (err) => {
  if (err) throw err;
  console.log('Rename complete!');
}); copy

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

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

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

在文件（而不是目录）上使用 fs.rmdir() 会导致 Windows 上的 ENOENT 错误和 POSIX 上的 ENOTDIR 错误。

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

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

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

异步删除文件和目录（以标准 POSIX rm 实用程序为模型）。除了可能的异常之外，不会向完成回调提供任何参数。

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

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

异步 stat(2)。回调函数接收两个参数 (err, stats)，其中 stats 是一个 <fs.Stats> 对象。

如果发生错误，err.code 将是 常见系统错误之一。

fs.stat() 遵循符号链接。 使用 fs.lstat() 查看链接本身。

不建议使用 fs.stat() 在调用 fs.open()、fs.readFile() 或 fs.writeFile() 之前检查文件是否存在。 相反，用户代码应直接打开/读取/写入文件并处理在文件不可用时引发的错误。

要检查文件是否存在而不操作它，建议使用 fs.access()。

例如，给定以下目录结构

- txtDir
-- file.txt
- app.js copy

下一个程序将检查给定路径的统计信息

import { stat } from 'node:fs';

const pathsToCheck = ['./txtDir', './txtDir/file.txt'];

for (let i = 0; i < pathsToCheck.length; i++) {
  stat(pathsToCheck[i], (err, stats) => {
    console.log(stats.isDirectory());
    console.log(stats);
  });
} copy

结果输出将类似于

true
Stats {
  dev: 16777220,
  mode: 16877,
  nlink: 3,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214262,
  size: 96,
  blocks: 0,
  atimeMs: 1561174653071.963,
  mtimeMs: 1561174614583.3518,
  ctimeMs: 1561174626623.5366,
  birthtimeMs: 1561174126937.2893,
  atime: 2019-06-22T03:37:33.072Z,
  mtime: 2019-06-22T03:36:54.583Z,
  ctime: 2019-06-22T03:37:06.624Z,
  birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
  dev: 16777220,
  mode: 33188,
  nlink: 1,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214074,
  size: 8,
  blocks: 8,
  atimeMs: 1561174616618.8555,
  mtimeMs: 1561174614584,
  ctimeMs: 1561174614583.8145,
  birthtimeMs: 1561174007710.7478,
  atime: 2019-06-22T03:36:56.619Z,
  mtime: 2019-06-22T03:36:54.584Z,
  ctime: 2019-06-22T03:36:54.584Z,
  birthtime: 2019-06-22T03:26:47.711Z
} copy

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

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

异步 statfs(2)。 返回有关包含 path 的已挂载文件系统的信息。 回调函数接收两个参数 (err, stats)，其中 stats 是一个 <fs.StatFs> 对象。

如果发生错误，err.code 将是 常见系统错误之一。

fs.symlink(target, path[, type], callback)#