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
• 返回: <fs.ReadStream>

与 <stream.Readable> 的 16 KiB 默认 highWaterMark 不同，此方法返回的流的默认 highWaterMark 为 64 KiB。

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';

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

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

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

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

import { createReadStream } from 'node:fs';

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

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • flags <string> See support of file system flags. Default: 'r'.
  • encoding <string> Default: null
  • fd <integer> | <FileHandle> Default: null
  • mode <integer> Default: 0o666
  • autoClose <boolean> Default: true
  • emitClose <boolean> Default: true
  • start <integer>
  • end <integer> Default: Infinity
  • highWaterMark <integer> Default: 64 * 1024
  • fs <Object> | <null> Default: null
• Returns: <fs.ReadStream>

Unlike the 16 KiB default highWaterMark for a <stream.Readable>, the stream returned by this method has a default highWaterMark of 64 KiB.

options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start counting at 0, allowed values are in the [0, Number.MAX_SAFE_INTEGER] range. If fd is specified and start is omitted or undefined, fs.createReadStream() reads sequentially from the current file position. The encoding can be any one of those accepted by <Buffer>.

If fd is specified, ReadStream will ignore the path argument and will use the specified file descriptor. This means that no 'open' event will be emitted. fd should be blocking; non-blocking fds should be passed to <net.Socket>.

If fd points to a character device that only supports blocking reads (such as keyboard or sound card), read operations do not finish until data is available. This can prevent the process from exiting and the stream from closing naturally.

By default, the stream will emit a 'close' event after it has been destroyed. Set the emitClose option to false to change this behavior.

By providing the fs option, it is possible to override the corresponding fs implementations for open, read, and close. When providing the fs option, an override for read is required. If no fd is provided, an override for open is also required. If autoClose is true, an override for close is also required.

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

If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. If autoClose is set to true (default behavior), on 'error' or 'end' the file descriptor will be closed automatically.

mode sets the file mode (permission and sticky bits), but only if the file was created.

An example to read the last 10 bytes of a file which is 100 bytes long:

import { createReadStream } from 'node:fs';

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

If options is a string, then it specifies the encoding.