Node.js v25.0.0 文档

类: FileHandle#

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

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

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

如果一个 <FileHandle> 没有使用 filehandle.close() 方法关闭，它将尝试自动关闭文件描述符并发出一个进程警告，以帮助防止内存泄漏。请不要依赖此行为，因为它可能不可靠，文件可能不会被关闭。相反，请始终显式关闭 <FileHandle>s。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 中任意一个或多个的按位或组成的掩码（例如 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 <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，包括子目录和文件。

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

fsPromises.glob(pattern[, options])#

• pattern <string> | <string[]>
• options <Object>
  • cwd <string> | <URL> 当前工作目录。默认: process.cwd()
  • exclude <Function> | <string[]> 用于过滤文件/目录的函数或要排除的 glob 模式列表。如果提供函数，返回 true 表示排除该项，返回 false 表示包含。默认: undefined。如果提供字符串数组，则每个字符串都应为指定要排除路径的 glob 模式。注意：不支持否定模式（例如 `!foo.js`）。
  • withFileTypes <boolean> 如果 glob 应返回 Dirents 形式的路径，则为 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 引用一个符号链接，在这种情况下，统计的是链接本身，而不是它引用的文件。有关更多详细信息，请参阅 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.mkdtempDisposable(prefix[, options])#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值： 'utf8'
• 返回: <Promise> 兑现一个异步可处置对象的 Promise
  • path <string> 创建的目录的路径。
  • remove <AsyncFunction> 一个删除已创建目录的函数。
  • [Symbol.asyncDispose] <AsyncFunction> 与 remove 相同。

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

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

有关详细信息，请参阅 fsPromises.mkdtemp() 的文档。

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

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> 兑现一个包含目录中文件名数组的 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> 目前没有公开的选项。以前曾有用于 recursive、maxBusyTries 和 emfileWait 的选项，但它们已被弃用和移除。为了向后兼容，仍然接受 options 参数，但不会使用它。
• 返回: <Promise> 成功时兑现为 undefined。

移除由 path 标识的目录。

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

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

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>，用于发出监视器应停止的信号。
  • maxQueue <number> 指定在返回的 <AsyncIterator> 的迭代之间要排队的事件数量。默认值：2048。
  • overflow <string> 当有比 maxQueue 允许的更多事件要排队时，可以是 'ignore' 或 'throw'。'ignore' 表示溢出事件被丢弃并发出警告，而 'throw' 表示抛出异常。默认值：'ignore'。
• 返回：<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 可以是字符串、缓冲区、<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#

• 类型：<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 中任意一个或多个的按位或组成的掩码（例如 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，包括子目录和文件。

将目录复制到另一个目录时，不支持通配符，行为类似于 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 选项，可以覆盖 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 <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 设置为 true（默认行为），在 'error' 或 'finish' 时，文件描述符将自动关闭。如果 autoClose 为 false，则文件描述符将不会被关闭，即使出现错误也是如此。应用程序有责任关闭它并确保没有文件描述符泄漏。

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

通过提供 fs 选项，可以覆盖 open、write、writev 和 close 对应的 fs 实现。覆盖 write() 而不覆盖 writev() 会降低性能，因为一些优化 (_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.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 <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> | <URL> 当前工作目录。默认: process.cwd()
  • exclude <Function> | <string[]> 用于过滤文件/目录的函数，或要排除的 glob 模式列表。如果提供函数，返回 true 以排除项目，返回 false 以包含项目。默认值：undefined。
  • withFileTypes <boolean> 如果 glob 应返回 Dirents 形式的路径，则为 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 是一个符号链接，那么会获取链接本身的状态，而不是它所引用的文件。

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

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

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 默认: false
  • mode <string> | <integer> 在 Windows 上不支持。默认: 0o777。
• callback <Function>
  • err <Error>
  • path <string> | <undefined> 仅在 recursive 设置为 true 并创建目录时存在。

异步地创建目录。

回调函数接收一个可能的异常，并且如果 recursive 是 true，则接收第一个创建的目录路径 (err[, path])。当 recursive 是 true 时，如果未创建目录（例如，如果它之前已创建），path 仍然可以是 undefined。

可选的 options 参数可以是一个指定 mode（权限和粘滞位）的整数，或者是一个带有 mode 属性和 recursive 属性（指示是否应创建父目录）的对象。当 path 是一个已存在的目录时，只有在 recursive 为 false 时调用 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 <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() 版本被调用，它将返回一个 promise，该 promise 解析为一个带有 bytesRead 和 buffer 属性的 Object。

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

例如：

• 如果文件短于指定的 length，bytesRead 将被设置为实际读取的字节数。
• 如果在缓冲区被填满之前文件遇到 EOF（文件结束），Node.js 将读取所有可用字节直到遇到 EOF，并且回调中的 bytesRead 参数将指示实际读取的字节数，这可能小于指定的 length。
• 如果文件位于慢速网络文件系统上或在读取期间遇到任何其他问题，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[]>

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

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

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

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

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) 实现支持的数量要高（得多）。

回调函数接收两个参数 (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)。

回调函数接收两个参数 (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> 目前没有公开的选项。以前曾有用于 recursive、maxBusyTries 和 emfileWait 的选项，但它们已被弃用和移除。为了向后兼容，仍然接受 options 参数，但不会使用它。
• callback <Function>
  • err <Error>

异步 rmdir(2)。除了一个可能的异常外，没有其他参数会传递给完成回调函数。

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

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

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.open()、fs.readFile() 或 fs.writeFile() 之前使用 fs.stat() 来检查文件是否存在。相反，用户代码应该直接打开/读取/写入文件，并处理文件不可用时引发的错误。

要检查文件是否存在而不对其进行后续操作，建议使用 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>