Node.js fs.readFile(path[, options], callback)用法及代码示例

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

参数

• path <string> | <Buffer> | <URL> | <integer> 文件名或文件说明符
• options <Object>|<string>
  • encoding <string> | <null> 默认： null
  • flag <string>参看支持文件系统flags.默认： 'r'.
  • signal <AbortSignal> 允许中止 in-progress 读取文件
• 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);
});

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

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

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

import { readFile } from 'node:fs';

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

当路径是目录时，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>
});

可以使用 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();

fs.readFile() 函数缓冲整个文件。为了最大限度地降低内存成本，如果可能，更喜欢通过 fs.createReadStream() 进行流式传输。

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

文件说明符#

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

性能注意事项#

fs.readFile() 方法一次将一个文件的内容异步读取到内存中，允许事件循环在每个块之间切换。这允许读取操作对可能使用底层 libuv 线程池的其他活动的影响较小，但意味着将完整文件读入内存需要更长的时间。

额外的读取开销在不同的系统上可能会有很大差异，并且取决于正在读取的文件类型。如果文件类型不是常规文件(例如管道)并且 Node.js 无法确定实际文件大小，则每次读取操作将加载 64 KiB 个数据。对于常规文件，每次读取将处理 512 KiB 个数据。

对于需要as-fast-as-possible 读取文件内容的应用程序，最好直接使用fs.read() 并且应用程序代码管理读取文件本身的全部内容。

Node.js GitHub 问题#25741 提供了更多信息和关于fs.readFile() 在不同 Node.js 版本中针对多种文件大小的性能的详细分析。