fs.createReadStream(path[, options])
与可读流的 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
是字符串,则它指定编码。
path
<string> | <Buffer> | <URL>options
<string> | <Object>flags
<string> See support of file systemflags
. Default:'r'
.encoding
<string> Default:null
fd
<integer> Default:null
mode
<integer> Default:0o666
autoClose
<boolean> Default:true
emitClose
<boolean> Default:false
start
<integer>end
<integer> Default:Infinity
highWaterMark
<integer> Default:64 * 1024
fs
<Object> | <null> Default:null
- Returns: <fs.ReadStream> See Readable Stream.
Unlike the 16 kb default highWaterMark
for a readable stream, the stream
returned by this method has a default highWaterMark
of 64 kb.
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 fd
s 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 not emit a 'close'
event after it has been
destroyed. This is the opposite of the default for other Readable
streams.
Set the emitClose
option to true
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,
overrides for open
, read
, and close
are required.
const fs = require('fs');
// Create a stream from some character device.
const stream = fs.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:
fs.createReadStream('sample.txt', { start: 90, end: 99 });
If options
is a string, then it specifies the encoding.