Node.js v12.22.12 文档

同步的示例#

中英对照

异常会被立即地抛出，可以使用 try…catch 来处理，也可以允许冒泡。

const fs = require('fs');

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

回调的示例#

中英对照

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

const fs = require('fs');

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

Promise 的示例#

Promise-based operations return a Promise that is resolved when the asynchronous operation is complete.

const fs = require('fs').promises;

(async function(path) {
  try {
    await fs.unlink(path);
    console.log(`successfully deleted ${path}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello');

回调与基于 promise 的操作的顺序#

中英对照

例如，以下内容容易出错，因为 fs.stat() 操作可能会在 fs.rename() 操作之前完成：

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  console.log('renamed complete');
});
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err;
  console.log(`stats: ${JSON.stringify(stats)}`);
});

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  fs.stat('/tmp/world', (err, stats) => {
    if (err) throw err;
    console.log(`stats: ${JSON.stringify(stats)}`);
  });
});

const fs = require('fs').promises;

(async function(from, to) {
  try {
    await fs.rename(from, to);
    const stats = await fs.stat(to);
    console.log(`stats: ${JSON.stringify(stats)}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello', '/tmp/world');

文件路径#

中英对照

字符串形式的路径被解释为标识绝对或相对文件名的 UTF-8 字符序列。 相对路径将相对于通过调用 process.cwd() 确定的当前工作目录进行解析。

在 POSIX 上使用绝对路径的示例：

const fs = require('fs');

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

在 POSIX 上使用相对路径的示例（相对于 process.cwd()）:

fs.open('file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

使用 Buffer 指定的路径主要用于将文件路径视为不透明字节序列的某些 POSIX 操作系统。 在此类系统上，单个文件路径可能包含使用多种字符编码的子序列。 与字符串路径一样，Buffer 路径可以是相对的或绝对的：

在 POSIX 上使用绝对路径的示例：

fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

在 Windows 上，Node.js 遵循独立驱动器工作目录的概念。 当使用不带反斜杠的驱动器路径时，可以观察到此行为。 例如，fs.readdirSync('C:\\') 可能返回与 fs.readdirSync('C:') 不同的结果。 有关详细信息，请参阅此 MSDN 页面。

URL object support#

中英对照

const fs = require('fs');
const fileUrl = new URL('file:///tmp/hello');

fs.readFileSync(fileUrl);

file: URL 始终是绝对路径。

// 在 Windows 上：

// - 带有主机名的 WHATWG 文件 URL 转换为 UNC 路径
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// - 带有驱动器号的 WHATWG 文件 URL 转换为绝对路径
// file:///C:/tmp/hello => C:\tmp\hello
fs.readFileSync(new URL('file:///C:/tmp/hello'));

// - 没有主机名的 WHATWG 文件 URL 必须有驱动器号
fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));
fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute

// 在其他平台上：

// - 不支持带有主机名的 WHATWG 文件 URL
// file://hostname/p/a/t/h/file => throw!
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute

// - WHATWG 文件 URL 转换为绝对路径
// file:///tmp/hello => /tmp/hello
fs.readFileSync(new URL('file:///tmp/hello'));

// 在 Windows 上
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

// 在 POSIX 上
fs.readFileSync(new URL('file:///p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
/ characters */

// 在 Windows 上
fs.readFileSync(new URL('file:///C:/path/%5C'));
fs.readFileSync(new URL('file:///C:/path/%5c'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

文件描述符#

中英对照

在 POSIX 系统上，对于每个进程，内核维护一个当前打开的文件和资源表。 每个打开的文件都分配了一个简单的数字标识符，称为文件描述符。 在系统级，所有文件系统操作都使用这些文件描述符来识别和跟踪每个特定文件。 Windows 系统使用不同但概念上相似的机制来跟踪资源。

分配后，文件描述符可用于从文件读取数据、向文件写入数据或请求有关文件的信息。

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.fstat(fd, (err, stat) => {
    if (err) throw err;
    // 使用统计

    // 
    fs.close(fd, (err) => {
      if (err) throw err;
    });
  });
});

否则将导致内存泄漏，最终导致应用程序崩溃。

线程池的使用#

中英对照

有关更多信息，请参阅 UV_THREADPOOL_SIZE 文档。

fs.Dir 类#

中英对照

表示目录流的类。

由 fs.opendir()、fs.opendirSync() 或 fsPromises.opendir() 创建。

const fs = require('fs');

async function print(path) {
  const dir = await fs.promises.opendir(path);
  for await (const dirent of dir) {
    console.log(dirent.name);
  }
}
print('./').catch(console.error);

dir.close()#

中英对照

• 返回: <Promise>

异步地关闭目录的底层资源句柄。 后续读取将导致错误。

dir.close(callback)#

中英对照

• callback <Function>
  • err <Error>

异步地关闭目录的底层资源句柄。 后续读取将导致错误。

资源句柄关闭后将调用 callback。

dir.closeSync()#

中英对照

同步地关闭目录的底层资源句柄。 后续读取将导致错误。

dir.path#

中英对照

• <string>

提供给 fs.opendir()、fs.opendirSync() 或 fsPromises.opendir() 的此目录的只读路径。

dir.read()#

中英对照

• 返回: <Promise> 包含 <fs.Dirent> | <null>

通过 readdir(3) 异步地读取下一个目录条目作为 fs.Dirent。

此函数返回的目录条目没有操作系统底层目录机制提供的特定顺序。

dir.read(callback)#

中英对照

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

通过 readdir(3) 异步地读取下一个目录条目作为 fs.Dirent。

读取完成后，将使用 fs.Dirent 或 null（如果读取不到更多的目录条目）调用 callback。

此函数返回的目录条目没有操作系统底层目录机制提供的特定顺序。

dir.readSync()#

中英对照

• 返回: <fs.Dirent> | <null>

如果读取不到更多的目录条目，则将返回 null。

此函数返回的目录条目没有操作系统底层目录机制提供的特定顺序。

dir[Symbol.asyncIterator]()#

中英对照

• 返回: <AsyncIterator> <fs.Dirent> 的

异步迭代器返回的条目始终是 fs.Dirent。 来自 dir.read() 的 null 情况是在内部处理的。

有关示例，请参见 fs.Dir。

此迭代器返回的目录条目没有操作系统底层目录机制提供的特定顺序。

fs.Dirent 类#

中英对照

目录条目的表示，可以是目录中的文件或子目录，通过从 fs.Dir 读取返回。 目录条目是文件名和文件类型对的组合。

dirent.isBlockDevice()#

中英对照

• 返回: <boolean>

如果 fs.Dirent 对象描述块设备，则返回 true。

dirent.isCharacterDevice()#

中英对照

• 返回: <boolean>

如果 fs.Dirent 对象描述字符设备，则返回 true。

dirent.isDirectory()#

中英对照

• 返回: <boolean>

如果 fs.Dirent 对象描述文件系统目录，则返回 true。

dirent.isFIFO()#

中英对照

• 返回: <boolean>

如果 fs.Dirent 对象描述先进先出 (FIFO) 管道，则返回 true。

dirent.isFile()#

中英对照

• 返回: <boolean>

如果 fs.Dirent 对象描述常规文件，则返回 true。

dirent.isSocket()#

中英对照

• 返回: <boolean>

如果 fs.Dirent 对象描述套接字，则返回 true。

dirent.isSymbolicLink()#

中英对照

• 返回: <boolean>

如果 fs.Dirent 对象描述符号链接，则返回 true。

dirent.name#

中英对照

• <string> | <Buffer>

此 fs.Dirent 对象引用的文件名。 该值的类型由传给 fs.readdir() 或 fs.readdirSync() 的 options.encoding 决定。

fs.FSWatcher 类#

中英对照

• 继承自 <EventEmitter>

成功调用 fs.watch() 方法将返回新的 fs.FSWatcher 对象。

每当修改指定的被监视文件时，所有 fs.FSWatcher 对象都会触发 'change' 事件。

'change' 事件#

中英对照

• eventType <string> 发生的变更事件的类型
• filename <string> | <Buffer> 更改的文件名（如果相关/可用）

当监视的目录或文件中的某些内容发生更改时触发。 在 fs.watch() 中查看更多详细信息。

根据操作系统支持，可能不提供 filename 参数。 如果提供了 filename，如果 fs.watch() 在其 encoding 选项设置为 'buffer' 的情况下被调用，它将作为 Buffer 提供，否则 filename 将是 UTF-8 字符串。

// 通过 fs.watch() 监听器处理的示例
fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename);
    // 打印: <Buffer ...>
  }
});

'close' 事件#

中英对照

当监视器停止监视变化时触发。 关闭的 fs.FSWatcher 对象在事件句柄中不再可用。

'error' 事件#

中英对照

• error <Error>

在监视文件时发生错误时触发。 出错的 fs.FSWatcher 对象在事件句柄中不再可用。

watcher.close()#

中英对照

停止监视给定 fs.FSWatcher 上的更改。 一旦停止，fs.FSWatcher 对象就不再可用。

watcher.ref()#

中英对照

• 返回: <fs.FSWatcher>

调用时，只要 FSWatcher 处于活动状态，就请求 Node.js 事件循环不退出。 多次调用 watcher.ref() 将不起作用。

默认情况下，所有 FSWatcher 对象都被“引用”，这使得通常不需要调用 watcher.ref() 除非之前已经调用过 watcher.unref()。

watcher.unref()#

中英对照

• 返回: <fs.FSWatcher>

调用时，活动的 FSWatcher 对象不需要 Node.js 事件循环保持活动状态。 如果没有其他活动保持事件循环运行，则进程可能会在调用 FSWatcher 对象的回调之前退出。 多次调用 watcher.unref() 将不起作用。

fs.StatWatcher 类#

中英对照

• 继承自 <EventEmitter>

成功调用 fs.watchFile() 方法将返回新的 fs.StatWatcher 对象。

watcher.ref()#

中英对照

• 返回: <fs.StatWatcher>

调用时，只要 StatWatcher 处于活动状态，就请求 Node.js 事件循环不退出。 多次调用 watcher.ref() 将不起作用。

默认情况下，所有 StatWatcher 对象都被“引用”，这使得通常不需要调用 watcher.ref() 除非之前已经调用过 watcher.unref()。

watcher.unref()#

中英对照

• 返回: <fs.StatWatcher>

调用时，活动的 StatWatcher 对象不需要 Node.js 事件循环保持活动状态。 如果没有其他活动保持事件循环运行，则进程可能会在调用 StatWatcher 对象的回调之前退出。 多次调用 watcher.unref() 将不起作用。

fs.ReadStream 类#

中英对照

• 继承自: <stream.Readable>

fs.ReadStream 的实例是使用 fs.createReadStream() 函数创建和返回的。

'close' 事件#

中英对照

当 fs.ReadStream 的底层文件描述符已关闭时触发。

'open' 事件#

中英对照

• fd <integer> ReadStream 使用的整数文件描述符。

当 fs.ReadStream 的文件描述符被打开时触发。

'ready' 事件#

中英对照

当 fs.ReadStream 准备好使用时触发。

'open' 后立即触发。

readStream.bytesRead#

中英对照

• <number>

到目前为止已读取的字节数。

readStream.path#

中英对照

• <string> | <Buffer>

流正在读取的文件的路径，如 fs.createReadStream() 的第一个参数中所指定。 如果 path 作为字符串传入，则 readStream.path 将是字符串。 如果 path 作为 Buffer 传入，则 readStream.path 将是 Buffer。

readStream.pending#

中英对照

• <boolean>

如果底层文件尚未打开，即在触发 'ready' 事件之前，则此属性为 true。

fs.Stats 类#

中英对照

fs.Stats 对象提供有关文件的信息。

从 fs.stat()、fs.lstat() 和 fs.fstat() 及其同步方法返回的对象属于此类型。 如果传给这些方法的 options 中的 bigint 为 true，则数值将为 bigint 而不是 number，并且该对象将包含额外的以 Ns 为后缀的纳秒精度属性。

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

bigint 版本：

BigIntStats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atimeNs: 1318289051000000000n,
  mtimeNs: 1318289051000000000n,
  ctimeNs: 1318289051000000000n,
  birthtimeNs: 1318289051000000000n,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()#

中英对照

• 返回: <boolean>

如果 fs.Stats 对象描述块设备，则返回 true。

stats.isCharacterDevice()#

中英对照

• 返回: <boolean>

如果 fs.Stats 对象描述字符设备，则返回 true。

stats.isDirectory()#

中英对照

• 返回: <boolean>

如果 fs.Stats 对象描述文件系统目录，则返回 true。

stats.isFIFO()#

中英对照

• 返回: <boolean>

如果 fs.Stats 对象描述先进先出 (FIFO) 管道，则返回 true。

stats.isFile()#

中英对照

• 返回: <boolean>

如果 fs.Stats 对象描述常规文件，则返回 true。

stats.isSocket()#

中英对照

• 返回: <boolean>

如果 fs.Stats 对象描述套接字，则返回 true。

stats.isSymbolicLink()#

中英对照

• 返回: <boolean>

如果 fs.Stats 对象描述符号链接，则返回 true。

此方法仅在使用 fs.lstat() 时有效。

stats.dev#

中英对照

• <number> | <bigint>

包含文件的设备的数字标识符。

stats.ino#

中英对照

• <number> | <bigint>

文件的文件系统特定的索引节点编号。

stats.mode#

中英对照

• <number> | <bigint>

描述文件类型和模式的位字段。

stats.nlink#

中英对照

• <number> | <bigint>

文件存在的硬链接数。

stats.uid#

中英对照

• <number> | <bigint>

拥有文件的用户的数字用户标识符 (POSIX)。

stats.gid#

中英对照

• <number> | <bigint>

拥有文件的群组的数字群组标识符 (POSIX)。

stats.rdev#

中英对照

• <number> | <bigint>

如果文件代表设备，则为数字设备标识符。

stats.size#

中英对照

• <number> | <bigint>

文件的大小（以字节为单位）。

stats.blksize#

中英对照

• <number> | <bigint>

i/o 操作的文件系统块大小。

stats.blocks#

中英对照

• <number> | <bigint>

为此文件分配的块数。

stats.atimeMs#

中英对照

• <number> | <bigint>

指示最后一次访问此文件的时间戳，以 POSIX Epoch 以来的毫秒数表示。

stats.mtimeMs#

中英对照

• <number> | <bigint>

指示最后一次修改此文件的时间戳，以 POSIX Epoch 以来的毫秒数表示。

stats.ctimeMs#

中英对照

• <number> | <bigint>

指示最后一次更改文件状态的时间戳，以 POSIX Epoch 以来的毫秒数表示。

stats.birthtimeMs#

中英对照

• <number> | <bigint>

指示此文件创建时间的时间戳，以 POSIX Epoch 以来的毫秒数表示。

stats.atimeNs#

中英对照

• <bigint>

仅在 bigint: true 传入到生成对象的方法中时出现。 指示最后一次访问此文件的时间戳，以 POSIX Epoch 以来的纳秒数表示。

stats.mtimeNs#

中英对照

• <bigint>

仅在 bigint: true 传入到生成对象的方法中时出现。 指示最后一次修改此文件的时间戳，以 POSIX Epoch 以来的纳秒数表示。

stats.ctimeNs#

中英对照

• <bigint>

仅在 bigint: true 传入到生成对象的方法中时出现。 指示最后一次更改文件状态的时间戳，以 POSIX Epoch 以来的纳秒数表示。

stats.birthtimeNs#

中英对照

• <bigint>

仅在 bigint: true 传入到生成对象的方法中时出现。 指示此文件创建时间的时间戳，以 POSIX Epoch 以来的纳秒数表示。

stats.atime#

中英对照

• <Date>

指示最后一次访问此文件的时间戳。

stats.mtime#

中英对照

• <Date>

指示最后一次修改此文件的时间戳。

stats.ctime#

中英对照

• <Date>

指示最后一次更改文件状态的时间戳。

stats.birthtime#

中英对照

• <Date>

指示此文件创建时间的时间戳。

统计的时间值#

中英对照

atimeMs、mtimeMs、ctimeMs、birthtimeMs 属性是数值，以毫秒为单位保存相应的时间。 它们的精度是特定于平台的。 当 bigint: true 传给生成对象的方法时，属性将是长整数，否则它们将是数字。

atimeNs、mtimeNs、ctimeNs、birthtimeNs 属性是以纳秒为单位保存相应时间的长整数。 它们仅在 bigint: true 传入到生成对象的方法中时出现。 它们的精度是特定于平台的。

atime、mtime、ctime 和 birthtime 是不同时间的 Date 对象替代表示。 Date 和数字值是不关联的。 分配新的数值或改变 Date 值不会反映在相应的替代表示中。

统计对象中的时间具有以下语义：

• atime "访问时间": 上次访问文件数据的时间。 由 mknod(2)、 utimes(2) 和 read(2) 系统调用更改。
• mtime "修改时间": 上次修改文件数据的时间。 由 mknod(2)、 utimes(2) 和 write(2) 系统调用更改。
• ctime "更改时间": 上次更改文件状态（修改索引节点数据）的时间。 由 chmod(2)、 chown(2)、 link(2)、 mknod(2)、 rename(2)、 unlink(2)、 utimes(2)、 read(2) 和 write(2) 系统调用更改。
• birthtime "创建时间": 文件创建时间。 创建文件时设置一次。 在创建时间不可用的文件系统上，该字段可能改为保存 ctime 或 1970-01-01T00:00Z（即 Unix 纪元时间戳 0）。 在这种情况下，该值可能大于 atime 或 mtime。 在 Darwin 和其他 FreeBSD 变体上，如果使用 utimes(2) 系统调用将 atime 显式设置为比当前 birthtime 更早的值，也会被设置。

在 Node.js 0.12 之前，ctime 是 Windows 系统上的 birthtime。 从 0.12 开始，ctime 不是“创建时间”，在 Unix 系统上，它从来都不是。

fs.WriteStream 类#

中英对照

• 继承自 <stream.Writable>

fs.WriteStream 的实例是使用 fs.createWriteStream() 函数创建和返回的。

'close' 事件#

中英对照

当 WriteStream 的底层文件描述符已关闭时触发。

'open' 事件#

中英对照

• fd <integer> WriteStream 使用的整数文件描述符。

打开 WriteStream 的文件时触发。

'ready' 事件#

中英对照

当 fs.WriteStream 准备好使用时触发。

'open' 后立即触发。

writeStream.bytesWritten#

中英对照

到目前为止写入的字节数。 不包括仍在排队等待写入的数据。

writeStream.path#

中英对照

流正在写入的文件的路径，如 fs.createWriteStream() 的第一个参数中所指定。 如果 path 作为字符串传入，则 writeStream.path 将是字符串。 如果 path 作为 Buffer 传入，则 writeStream.path 将是 Buffer。

writeStream.pending#

中英对照

• <boolean>

如果底层文件尚未打开，即在触发 'ready' 事件之前，则此属性为 true。

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

中英对照

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

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

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

const file = 'package.json';

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

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

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

// 检查当前目录中是否存在文件，是否可写。
fs.access(file, fs.constants.F_OK | fs.constants.W_OK, (err) => {
  if (err) {
    console.error(
      `${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}`);
  } else {
    console.log(`${file} exists, and it is writable`);
  }
});

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

写入（不推荐）

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

  fs.open('myfile', 'wx', (err, fd) => {
    if (err) throw err;
    writeMyData(fd);
  });
});

写入（推荐）

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

    throw err;
  }

  writeMyData(fd);
});

读取（不推荐）

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

    throw err;
  }

  fs.open('myfile', 'r', (err, fd) => {
    if (err) throw err;
    readMyData(fd);
  });
});

读取（推荐）

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

    throw err;
  }

  readMyData(fd);
});

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

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

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

fs.accessSync(path[, mode])#

中英对照

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

同步地测试用户对 path 指定的文件或目录的权限。 mode 参数是可选的整数，指定要执行的可访问性检查。 查看文件访问的常量以获取可能的 mode 值。 可以创建由两个或多个值的按位或组成的掩码（例如 fs.constants.W_OK | fs.constants.R_OK）。

如果任何可访问性检查失败，将抛出 Error。 否则，该方法将返回 undefined。

try {
  fs.accessSync('etc/passwd', fs.constants.R_OK | fs.constants.W_OK);
  console.log('can read/write');
} catch (err) {
  console.error('no access!');
}

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

中英对照

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

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

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

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

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

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

fs.open('message.txt', 'a', (err, fd) => {
  if (err) throw err;
  fs.appendFile(fd, 'data to append', 'utf8', (err) => {
    fs.close(fd, (err) => {
      if (err) throw err;
    });
    if (err) throw err;
  });
});

fs.appendFileSync(path, data[, options])#

中英对照

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

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

try {
  fs.appendFileSync('message.txt', 'data to append');
  console.log('The "data to append" was appended to file!');
} catch (err) {
  /* 处理错误 */
}

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

fs.appendFileSync('message.txt', 'data to append', 'utf8');

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

let fd;

try {
  fd = fs.openSync('message.txt', 'a');
  fs.appendFileSync(fd, 'data to append', 'utf8');
} catch (err) {
  /* 处理错误 */
} finally {
  if (fd !== undefined)
    fs.closeSync(fd);
}

fs.chmod(path, mode, callback)#

中英对照

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

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

另见: chmod(2)。

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

文件的模式#

中英对照

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

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

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

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

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

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

fs.chmodSync(path, mode)#

中英对照

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>

有关详细信息，请参阅此 API 的异步版本的文档：fs.chmod()。

另见: chmod(2)。

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

中英对照

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

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

另见: chown(2)。

fs.chownSync(path, uid, gid)#

中英对照

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

同步地更改文件的所有者和群组。 返回 undefined。 这是 fs.chown() 的同步版本。

另见: chown(2)。

fs.close(fd, callback)#

中英对照

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

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

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

fs.closeSync(fd)#

中英对照

• fd <integer>

同步的 close(2)。 返回 undefined。

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

fs.constants#

中英对照

• <Object>

返回一个包含文件系统操作常用常量的对象。

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

中英对照

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

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

flags 是可选的整数，用于指定复制操作的行为。 可以创建由两个或多个值的按位或组成的掩码（例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）。

• fs.constants.COPYFILE_EXCL: 如果 dest 已经存在，则复制操作将失败。
• fs.constants.COPYFILE_FICLONE: 复制操作将尝试创建写时复制引用链接。 如果平台不支持写时复制，则使用后备复制机制。
• fs.constants.COPYFILE_FICLONE_FORCE: 复制操作将尝试创建写时复制引用链接。 如果平台不支持写时复制，则该操作将失败。

const fs = require('fs');

// 默认情况下将创建或覆盖 destination.txt。
fs.copyFile('source.txt', 'destination.txt', (err) => {
  if (err) throw err;
  console.log('source.txt was copied to destination.txt');
});

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

// 通过使用 COPYFILE_EXCL，如果 destination.txt 存在，则该操作将失败。
fs.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL, callback);

fs.copyFileSync(src, dest[, flags])#

中英对照

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

同步地复制 src 到 dest。 默认情况下，如果 dest 已经存在，则会被覆盖。 返回 undefined。 Node.js 不保证复制操作的原子性。 如果在打开目标文件进行写入后发生错误，Node.js 将尝试删除目标文件。

flags 是可选的整数，用于指定复制操作的行为。 可以创建由两个或多个值的按位或组成的掩码（例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）。

• fs.constants.COPYFILE_EXCL: 如果 dest 已经存在，则复制操作将失败。
• fs.constants.COPYFILE_FICLONE: 复制操作将尝试创建写时复制引用链接。 如果平台不支持写时复制，则使用后备复制机制。
• fs.constants.COPYFILE_FICLONE_FORCE: 复制操作将尝试创建写时复制引用链接。 如果平台不支持写时复制，则该操作将失败。

const fs = require('fs');

// 默认情况下将创建或覆盖 destination.txt。
fs.copyFileSync('source.txt', 'destination.txt');
console.log('source.txt was copied to destination.txt');

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

// 通过使用 COPYFILE_EXCL，如果 destination.txt 存在，则该操作将失败。
fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL);

fs.createReadStream(path[, options])#

中英对照

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

与可读流的 16 kb 默认 highWaterMark 不同，此方法返回的流的默认 highWaterMark 为 64 kb。

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

将 emitClose 选项设置为 true 以更改此行为。

通过提供 fs 选项，可以覆盖 open、read 和 close 的相应 fs 实现。 提供 fs 选项时，需要覆盖 open、read 和 close。

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

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

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

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

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

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

fs.createWriteStream(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> 请参阅对文件系统 flags 的支持。 默认值: 'w'。
  • encoding <string> 默认值: 'utf8'
  • fd <integer> 默认值: null
  • mode <integer> 默认值: 0o666
  • autoClose <boolean> 默认值: true
  • emitClose <boolean> 默认值: false
  • start <integer>
  • fs <Object> | <null> 默认值: null
• 返回: <fs.WriteStream> 参见可写流。

options 还可以包括 start 选项，以允许在文件开头的某个位置写入数据，允许的值在 [0, Number.MAX_SAFE_INTEGER] 范围内。

encoding 可以是 Buffer 接受的任何一种。

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

将 emitClose 选项设置为 true 以更改此行为。

通过提供 fs 选项，可以覆盖 open、write、writev 和 close 的相应 fs 实现。 在没有 writev() 的情况下覆盖 write() 会降低性能，因为某些优化 (_writev()) 将被禁用。 提供 fs 选项时，需要覆盖 open、close、以及 write 和 writev 中的至少一个。

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

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

fs.exists(path, callback)#

中英对照

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

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

fs.exists('/etc/passwd', (exists) => {
  console.log(exists ? 'it\'s there' : 'no passwd!');
});

此回调的参数与其他 Node.js 回调不一致。 通常，Node.js 回调的第一个参数是 err 参数，后跟可选的其他参数。 fs.exists() 回调只有一个布尔参数。 这是推荐 fs.access() 而不是 fs.exists() 的原因之一。

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

写入（不推荐）

fs.exists('myfile', (exists) => {
  if (exists) {
    console.error('myfile already exists');
  } else {
    fs.open('myfile', 'wx', (err, fd) => {
      if (err) throw err;
      writeMyData(fd);
    });
  }
});

写入（推荐）

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

    throw err;
  }

  writeMyData(fd);
});

读取（不推荐）

fs.exists('myfile', (exists) => {
  if (exists) {
    fs.open('myfile', 'r', (err, fd) => {
      if (err) throw err;
      readMyData(fd);
    });
  } else {
    console.error('myfile does not exist');
  }
});

读取（推荐）

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

    throw err;
  }

  readMyData(fd);
});

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

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

fs.existsSync(path)#

中英对照

• path <string> | <Buffer> | <URL>
• 返回: <boolean>

如果路径存在则返回 true，否则返回 false。

有关详细信息，请参阅此 API 的异步版本的文档：fs.exists()。

fs.exists() 已弃用，但 fs.existsSync() 不是。 fs.exists() 的 callback 参数接受与其他 Node.js 回调不一致的参数。 fs.existsSync() 不使用回调。

if (fs.existsSync('/etc/passwd')) {
  console.log('The path exists.');
}

fs.fchmod(fd, mode, callback)#

中英对照

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

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

fs.fchmodSync(fd, mode)#

中英对照

• fd <integer>
• mode <string> | <integer>

同步的 fchmod(2)。 返回 undefined。

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

中英对照

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

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

fs.fchownSync(fd, uid, gid)#

中英对照

• fd <integer>
• uid <integer>
• gid <integer>

同步的 fchown(2)。 返回 undefined。

fs.fdatasync(fd, callback)#

中英对照

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

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

fs.fdatasyncSync(fd)#

中英对照

• fd <integer>

同步的 fdatasync(2)。 返回 undefined。

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

中英对照

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

异步的 fstat(2)。 回调有两个参数 (err, stats)，其中 stats 是 fs.Stats 对象。

fs.fstatSync(fd[, options])#

中英对照

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

同步的 fstat(2)。

fs.fsync(fd, callback)#

中英对照

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

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

fs.fsyncSync(fd)#

中英对照

• fd <integer>

同步的 fsync(2)。 返回 undefined。

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

中英对照

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

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

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

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

console.log(fs.readFileSync('temp.txt', 'utf8'));
// 打印: Node.js

// 
const fd = fs.openSync('temp.txt', 'r+');

// 
fs.ftruncate(fd, 4, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt', 'utf8'));
});
// 打印: Node

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

console.log(fs.readFileSync('temp.txt', 'utf8'));
// 打印: Node.js

// 
const fd = fs.openSync('temp.txt', 'r+');

// 
fs.ftruncate(fd, 10, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt'));
});
// 打印: <Buffer 4e 6f 64 65 2e 6a 73 00 00 00>
// 

fs.ftruncateSync(fd[, len])#

中英对照

• fd <integer>
• len <integer> 默认值: 0

返回 undefined。

有关详细信息，请参阅此 API 的异步版本的文档：fs.ftruncate()。

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

中英对照

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

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

此函数在 7.1 之前的 AIX 版本上不起作用，它将返回错误 UV_ENOSYS。

fs.futimesSync(fd, atime, mtime)#

中英对照

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

fs.futimes() 的同步版本。 返回 undefined。

fs.lchmod(path, mode, callback)#

中英对照

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

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

fs.lchmodSync(path, mode)#

中英对照

• path <string> | <Buffer> | <URL>
• mode <integer>

同步的 lchmod(2)。 返回 undefined。

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

中英对照

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

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

fs.lchownSync(path, uid, gid)#

中英对照

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

同步的 lchown(2)。 返回 undefined。

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.lutimesSync(path, atime, mtime)#

中英对照

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

更改 path 引用的符号链接的文件系统时间戳。 返回 undefined，或在参数不正确或操作失败时抛出异常。 这是 fs.lutimes() 的同步版本。

fs.link(existingPath, newPath, callback)#

中英对照

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

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

fs.linkSync(existingPath, newPath)#

中英对照

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

同步的 link(2)。 返回 undefined。

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

中英对照

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

异步的 lstat(2)。 回调有两个参数 (err, stats)，其中 stats 是 fs.Stats 对象。 lstat() 与 stat() 相同，除了如果 path 是符号链接，则被统计的是链接本身，而不是它引用的文件。

fs.lstatSync(path[, options])#

中英对照

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

同步的 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>

异步地创建目录。

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

当 path 是已存在的目录时，调用 fs.mkdir() 仅在 recursive 为 false 时才导致错误。

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

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

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

另见: mkdir(2)。

fs.mkdirSync(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 默认值: false
  • mode <string> | <integer> Windows 上不支持。 默认值: 0o777。
• 返回: <string> | <undefined>

同步地创建目录。 返回 undefined 或创建的第一个目录路径（如果 recursive 为 true）。 这是 fs.mkdir() 的同步版本。

另见: mkdir(2)。

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

中英对照

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

创建唯一的临时目录。

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

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

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

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

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

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

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

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

fs.mkdtempSync(prefix[, options])#

中英对照

• prefix <string>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• 返回: <string>

返回创建的目录路径。

有关详细信息，请参阅此 API 的异步版本的文档：fs.mkdtemp()。

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

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>

异步地打开文件。 参见 open(2)。

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

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

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

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

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

中英对照

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

异步地打开目录。 参见 opendir(3)。

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

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

fs.opendirSync(path[, options])#

中英对照

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

同步地打开目录。 参见 opendir(3)。

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

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

fs.openSync(path[, flags, mode])#

中英对照

• path <string> | <Buffer> | <URL>
• flags <string> | <number> 默认值: 'r'。 请参阅对文件系统 flags 的支持。
• mode <string> | <integer> 默认值: 0o666
• 返回: <number>

返回表示文件描述符的整数。

有关详细信息，请参阅此 API 的异步版本的文档：fs.open()。

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

中英对照

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer>
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

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

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

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

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

中英对照

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

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

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

中英对照

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

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

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

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

fs.readdirSync(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
  • withFileTypes <boolean> 默认值: false
• 返回: <string[]> | <Buffer[]> | <fs.Dirent[]>

同步的 readdir(3)。

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

如果 options.withFileTypes 设置为 true，则结果将包含 fs.Dirent 对象。

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

中英对照

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

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

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

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

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

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

fs.readFile('/etc/passwd', 'utf8', callback);

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

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

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

fs.readFile() 函数缓冲整个文件。 为了最小化内存成本，在可能的情况下优先通过 fs.createReadStream() 进行流式传输。

文件描述符#

中英对照

1. 任何指定的文件描述符都必须支持读取。
2. 如果将文件描述符指定为 path，则它将不会自动关闭。
3. 读数将从当前位置开始。 例如，如果文件已经具有 'Hello World' 并且使用文件描述符读取了六个字节，则使用相同文件描述符对 fs.readFile() 的调用将得到 'World'，而不是 'Hello World'。

fs.readFileSync(path[, options])#

中英对照

• path <string> | <Buffer> | <URL> | <integer> 文件名或文件描述符
• options <Object> | <string>
  • encoding <string> | <null> 默认值: null
  • flag <string> 请参阅对文件系统 flags 的支持。 默认值: 'r'。
• 返回: <string> | <Buffer>

返回 path 的内容。

有关详细信息，请参阅此 API 的异步版本的文档：fs.readFile()。

如果指定了 encoding 选项，则此函数返回字符串。 否则它返回缓冲区。

与 fs.readFile() 类似，当路径为目录时，fs.readFileSync() 的行为是特定于平台的。

// macOS、Linux 和 Windows
fs.readFileSync('<directory>');
// => [Error: EISDIR: illegal operation on a directory, read <directory>]

//  FreeBSD
fs.readFileSync('<directory>'); // => <data>

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

中英对照

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

异步的 readlink(2)。 回调有两个参数 (err, linkString)。

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

fs.readlinkSync(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• 返回: <string> | <Buffer>

同步的 readlink(2)。 返回符号链接的字符串值。

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

fs.readSync(fd, buffer, offset, length, position)#

中英对照

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer>
• 返回: <number>

返回 bytesRead 的数量。

有关详细信息，请参阅此 API 的异步版本的文档：fs.read()。

fs.readSync(fd, buffer, [options])#

中英对照

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

返回 bytesRead 的数量。

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

有关详细信息，请参阅此 API 的异步版本的文档：fs.read()。

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

中英对照

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer>
• 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.readvSync(fd, buffers[, position])#

中英对照

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer>
• 返回: <number> 读取的字节数。

有关详细信息，请参阅此 API 的异步版本的文档：fs.readv()。

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 解析为套接字或管道，则该函数将返回该对象的系统相关名称。

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.realpathSync(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• 返回: <string> | <Buffer>

返回解析的路径名。

有关详细信息，请参阅此 API 的异步版本的文档：fs.realpath()。

fs.realpathSync.native(path[, options])#

中英对照

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 默认值: 'utf8'
• 返回: <string> | <Buffer>

同步的 realpath(3)。

仅支持可以转换为 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)。

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