Node.js v25.0.0 文档
- Node.js v25.0.0
-
目录
- 缓冲区
- 缓冲区与字符编码
- 缓冲区与 TypedArray
- 缓冲区与迭代
- 类:
Blob
- 类:
Buffer
- 静态方法:
Buffer.alloc(size[, fill[, encoding]])
- 静态方法:
Buffer.allocUnsafe(size)
- 静态方法:
Buffer.allocUnsafeSlow(size)
- 静态方法:
Buffer.byteLength(string[, encoding])
- 静态方法:
Buffer.compare(buf1, buf2)
- 静态方法:
Buffer.concat(list[, totalLength])
- 静态方法:
Buffer.copyBytesFrom(view[, offset[, length]])
- 静态方法:
Buffer.from(array)
- 静态方法:
Buffer.from(arrayBuffer[, byteOffset[, length]])
- 静态方法:
Buffer.from(buffer)
- 静态方法:
Buffer.from(object[, offsetOrEncoding[, length]])
- 静态方法:
Buffer.from(string[, encoding])
- 静态方法:
Buffer.isBuffer(obj)
- 静态方法:
Buffer.isEncoding(encoding)
Buffer.poolSize
buf[index]
buf.buffer
buf.byteOffset
buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])
buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])
buf.entries()
buf.equals(otherBuffer)
buf.fill(value[, offset[, end]][, encoding])
buf.includes(value[, byteOffset][, encoding])
buf.indexOf(value[, byteOffset][, encoding])
buf.keys()
buf.lastIndexOf(value[, byteOffset][, encoding])
buf.length
buf.parent
buf.readBigInt64BE([offset])
buf.readBigInt64LE([offset])
buf.readBigUInt64BE([offset])
buf.readBigUInt64LE([offset])
buf.readDoubleBE([offset])
buf.readDoubleLE([offset])
buf.readFloatBE([offset])
buf.readFloatLE([offset])
buf.readInt8([offset])
buf.readInt16BE([offset])
buf.readInt16LE([offset])
buf.readInt32BE([offset])
buf.readInt32LE([offset])
buf.readIntBE(offset, byteLength)
buf.readIntLE(offset, byteLength)
buf.readUInt8([offset])
buf.readUInt16BE([offset])
buf.readUInt16LE([offset])
buf.readUInt32BE([offset])
buf.readUInt32LE([offset])
buf.readUIntBE(offset, byteLength)
buf.readUIntLE(offset, byteLength)
buf.subarray([start[, end]])
buf.slice([start[, end]])
buf.swap16()
buf.swap32()
buf.swap64()
buf.toJSON()
buf.toString([encoding[, start[, end]]])
buf.values()
buf.write(string[, offset[, length]][, encoding])
buf.writeBigInt64BE(value[, offset])
buf.writeBigInt64LE(value[, offset])
buf.writeBigUInt64BE(value[, offset])
buf.writeBigUInt64LE(value[, offset])
buf.writeDoubleBE(value[, offset])
buf.writeDoubleLE(value[, offset])
buf.writeFloatBE(value[, offset])
buf.writeFloatLE(value[, offset])
buf.writeInt8(value[, offset])
buf.writeInt16BE(value[, offset])
buf.writeInt16LE(value[, offset])
buf.writeInt32BE(value[, offset])
buf.writeInt32LE(value[, offset])
buf.writeIntBE(value, offset, byteLength)
buf.writeIntLE(value, offset, byteLength)
buf.writeUInt8(value[, offset])
buf.writeUInt16BE(value[, offset])
buf.writeUInt16LE(value[, offset])
buf.writeUInt32BE(value[, offset])
buf.writeUInt32LE(value[, offset])
buf.writeUIntBE(value, offset, byteLength)
buf.writeUIntLE(value, offset, byteLength)
new Buffer(array)
new Buffer(arrayBuffer[, byteOffset[, length]])
new Buffer(buffer)
new Buffer(size)
new Buffer(string[, encoding])
- 静态方法:
- 类:
File
node:buffer
模块 APIBuffer.from()
、Buffer.alloc()
和Buffer.allocUnsafe()
- 缓冲区
-
索引
- 断言测试
- 异步上下文跟踪
- 异步钩子
- 缓冲区
- C++ 插件
- 使用 Node-API 的 C/C++ 插件
- C++ 嵌入器 API
- 子进程
- 集群
- 命令行选项
- 控制台
- 加密
- 调试器
- 已弃用的 API
- 诊断通道
- DNS
- 域
- 环境变量
- 错误
- 事件
- 文件系统
- 全局对象
- HTTP
- HTTP/2
- HTTPS
- 检查器
- 国际化
- 模块:CommonJS 模块
- 模块:ECMAScript 模块
- 模块:
node:module
API - 模块:包
- 模块:TypeScript
- 网络
- 操作系统
- 路径
- 性能钩子
- 权限
- 进程
- Punycode
- 查询字符串
- 逐行读取
- REPL
- 报告
- 单一可执行文件应用
- SQLite
- 流
- 字符串解码器
- 测试运行器
- 定时器
- TLS/SSL
- 跟踪事件
- TTY
- UDP/数据报
- URL
- 实用工具
- V8
- 虚拟机
- WASI
- Web Crypto API
- Web Streams API
- 工作线程
- Zlib
- 其他版本
- 选项
Buffer#
源代码:lib/buffer.js
Buffer
对象用于表示一个固定长度的字节序列。许多 Node.js API 都支持 Buffer
。
Buffer
类是 JavaScript 的 <Uint8Array> 类的子类,并用涵盖额外用例的方法对其进行了扩展。只要 Buffer
被支持,Node.js API 也会接受普通的 <Uint8Array>。
虽然 Buffer
类在全局作用域内可用,但仍然建议通过 import 或 require 语句显式引用它。
import { Buffer } from 'node:buffer';
// Creates a zero-filled Buffer of length 10.
const buf1 = Buffer.alloc(10);
// Creates a Buffer of length 10,
// filled with bytes which all have the value `1`.
const buf2 = Buffer.alloc(10, 1);
// Creates an uninitialized buffer of length 10.
// This is faster than calling Buffer.alloc() but the returned
// Buffer instance might contain old data that needs to be
// overwritten using fill(), write(), or other functions that fill the Buffer's
// contents.
const buf3 = Buffer.allocUnsafe(10);
// Creates a Buffer containing the bytes [1, 2, 3].
const buf4 = Buffer.from([1, 2, 3]);
// Creates a Buffer containing the bytes [1, 1, 1, 1] – the entries
// are all truncated using `(value & 255)` to fit into the range 0–255.
const buf5 = Buffer.from([257, 257.5, -255, '1']);
// Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést':
// [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation)
// [116, 195, 169, 115, 116] (in decimal notation)
const buf6 = Buffer.from('tést');
// Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74].
const buf7 = Buffer.from('tést', 'latin1');
const { Buffer } = require('node:buffer');
// Creates a zero-filled Buffer of length 10.
const buf1 = Buffer.alloc(10);
// Creates a Buffer of length 10,
// filled with bytes which all have the value `1`.
const buf2 = Buffer.alloc(10, 1);
// Creates an uninitialized buffer of length 10.
// This is faster than calling Buffer.alloc() but the returned
// Buffer instance might contain old data that needs to be
// overwritten using fill(), write(), or other functions that fill the Buffer's
// contents.
const buf3 = Buffer.allocUnsafe(10);
// Creates a Buffer containing the bytes [1, 2, 3].
const buf4 = Buffer.from([1, 2, 3]);
// Creates a Buffer containing the bytes [1, 1, 1, 1] – the entries
// are all truncated using `(value & 255)` to fit into the range 0–255.
const buf5 = Buffer.from([257, 257.5, -255, '1']);
// Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést':
// [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation)
// [116, 195, 169, 115, 116] (in decimal notation)
const buf6 = Buffer.from('tést');
// Creates a Buffer containing the Latin-1 bytes [0x74, 0xe9, 0x73, 0x74].
const buf7 = Buffer.from('tést', 'latin1');
缓冲区与字符编码#
在 Buffer
和字符串之间进行转换时,可以指定字符编码。如果未指定字符编码,将默认使用 UTF-8。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('hello world', 'utf8');
console.log(buf.toString('hex'));
// Prints: 68656c6c6f20776f726c64
console.log(buf.toString('base64'));
// Prints: aGVsbG8gd29ybGQ=
console.log(Buffer.from('fhqwhgads', 'utf8'));
// Prints: <Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'));
// Prints: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>
const { Buffer } = require('node:buffer');
const buf = Buffer.from('hello world', 'utf8');
console.log(buf.toString('hex'));
// Prints: 68656c6c6f20776f726c64
console.log(buf.toString('base64'));
// Prints: aGVsbG8gd29ybGQ=
console.log(Buffer.from('fhqwhgads', 'utf8'));
// Prints: <Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'));
// Prints: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>
Node.js 缓冲区接受其收到的编码字符串的所有大小写变体。例如,UTF-8可以指定为 'utf8'
、'UTF8'
或 'uTf8'
。
Node.js 当前支持的字符编码如下
-
'utf8'
(别名:'utf-8'
):多字节编码的 Unicode 字符。许多网页和其他文档格式使用 UTF-8。这是默认的字符编码。当将一个不完全包含有效 UTF-8 数据的Buffer
解码为字符串时,将使用 Unicode 替换字符U+FFFD
� 来表示这些错误。 -
'utf16le'
(别名:'utf-16le'
):多字节编码的 Unicode 字符。与'utf8'
不同,字符串中的每个字符都将使用 2 或 4 个字节进行编码。Node.js 只支持 UTF-16 的小端序变体。 -
'latin1'
:Latin-1 代表 ISO-8859-1。此字符编码仅支持从U+0000
到U+00FF
的 Unicode 字符。每个字符使用单个字节编码。不在此范围内的字符将被截断并映射到该范围内的字符。
使用上述编码之一将 Buffer
转换为字符串称为解码,将字符串转换为 Buffer
称为编码。
Node.js 还支持以下二进制到文本的编码。对于二进制到文本的编码,命名约定是相反的:将 Buffer
转换为字符串通常称为编码,将字符串转换为 Buffer
称为解码。
-
'base64'
: Base64 编码。从字符串创建Buffer
时,此编码也会正确接受 RFC 4648 第 5 节中指定的“URL 和文件名安全字母表”。base64 编码字符串中包含的空格、制表符和换行符等空白字符将被忽略。 -
'base64url'
:RFC 4648 第 5 节中指定的 base64url 编码。从字符串创建Buffer
时,此编码也会正确接受常规的 base64 编码字符串。当将Buffer
编码为字符串时,此编码将省略填充。 -
'hex'
:将每个字节编码为两个十六进制字符。在解码不完全由偶数个十六进制字符组成的字符串时,可能会发生数据截断。请参阅下面的示例。
还支持以下旧式字符编码
-
'ascii'
:仅适用于 7 位 ASCII 数据。当将字符串编码为Buffer
时,这等同于使用'latin1'
。当将Buffer
解码为字符串时,使用此编码会在解码为'latin1'
之前额外清除每个字节的最高位。通常,没有理由使用此编码,因为在编码或解码纯 ASCII 文本时,'utf8'
(或者,如果已知数据始终为纯 ASCII,则为'latin1'
)是更好的选择。它仅为旧版兼容性而提供。 -
'binary'
:'latin1'
的别名。此编码的名称可能非常具有误导性,因为这里列出的所有编码都在字符串和二进制数据之间进行转换。对于字符串和Buffer
之间的转换,通常'utf8'
是正确的选择。 -
'ucs2'
、'ucs-2'
:'utf16le'
的别名。UCS-2 过去指的是 UTF-16 的一个变体,不支持代码点大于 U+FFFF 的字符。在 Node.js 中,始终支持这些代码点。
import { Buffer } from 'node:buffer';
Buffer.from('1ag123', 'hex');
// Prints <Buffer 1a>, data truncated when first non-hexadecimal value
// ('g') encountered.
Buffer.from('1a7', 'hex');
// Prints <Buffer 1a>, data truncated when data ends in single digit ('7').
Buffer.from('1634', 'hex');
// Prints <Buffer 16 34>, all data represented.
const { Buffer } = require('node:buffer');
Buffer.from('1ag123', 'hex');
// Prints <Buffer 1a>, data truncated when first non-hexadecimal value
// ('g') encountered.
Buffer.from('1a7', 'hex');
// Prints <Buffer 1a>, data truncated when data ends in single digit ('7').
Buffer.from('1634', 'hex');
// Prints <Buffer 16 34>, all data represented.
现代 Web 浏览器遵循 WHATWG 编码标准,该标准将 'latin1'
和 'ISO-8859-1'
都别名为 'win-1252'
。这意味着当执行像 http.get()
这样的操作时,如果返回的字符集是 WHATWG 规范中列出的之一,服务器可能实际上返回了 'win-1252'
编码的数据,而使用 'latin1'
编码可能会错误地解码字符。
缓冲区与 TypedArray#
Buffer
实例也是 JavaScript <Uint8Array> 和 <TypedArray> 实例。所有 <TypedArray> 方法在 Buffer
上都可用。但是,Buffer
API 和 <TypedArray> API 之间存在一些细微的不兼容之处。
特别是
- 虽然
TypedArray.prototype.slice()
创建TypedArray
一部分的副本,但Buffer.prototype.slice()
创建一个指向现有Buffer
的视图,而不进行复制。这种行为可能会令人意外,并且仅为旧版兼容性而存在。可以使用TypedArray.prototype.subarray()
在Buffer
和其他TypedArray
上实现Buffer.prototype.slice()
的行为,并且应优先使用。 buf.toString()
与其TypedArray
等价物不兼容。- 一些方法,例如
buf.indexOf()
,支持额外的参数。
有两种方法可以从 Buffer
创建新的 <TypedArray> 实例
- 将
Buffer
传递给 <TypedArray> 构造函数将复制Buffer
的内容,并将其解释为整数数组,而不是目标类型的字节序列。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([1, 2, 3, 4]);
const uint32array = new Uint32Array(buf);
console.log(uint32array);
// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]
const { Buffer } = require('node:buffer');
const buf = Buffer.from([1, 2, 3, 4]);
const uint32array = new Uint32Array(buf);
console.log(uint32array);
// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]
- 传递
Buffer
的底层 <ArrayBuffer> 将创建一个与Buffer
共享内存的 <TypedArray>。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('hello', 'utf16le');
const uint16array = new Uint16Array(
buf.buffer,
buf.byteOffset,
buf.length / Uint16Array.BYTES_PER_ELEMENT);
console.log(uint16array);
// Prints: Uint16Array(5) [ 104, 101, 108, 108, 111 ]
const { Buffer } = require('node:buffer');
const buf = Buffer.from('hello', 'utf16le');
const uint16array = new Uint16Array(
buf.buffer,
buf.byteOffset,
buf.length / Uint16Array.BYTES_PER_ELEMENT);
console.log(uint16array);
// Prints: Uint16Array(5) [ 104, 101, 108, 108, 111 ]
可以通过使用 TypedArray
对象的 .buffer
属性,以相同的方式创建一个与 <TypedArray> 实例共享相同已分配内存的新 Buffer
。在这种情况下,Buffer.from()
的行为类似于 new Uint8Array()
。
import { Buffer } from 'node:buffer';
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;
// Copies the contents of `arr`.
const buf1 = Buffer.from(arr);
// Shares memory with `arr`.
const buf2 = Buffer.from(arr.buffer);
console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 a0 0f>
arr[1] = 6000;
console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 70 17>
const { Buffer } = require('node:buffer');
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;
// Copies the contents of `arr`.
const buf1 = Buffer.from(arr);
// Shares memory with `arr`.
const buf2 = Buffer.from(arr.buffer);
console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 a0 0f>
arr[1] = 6000;
console.log(buf1);
// Prints: <Buffer 88 a0>
console.log(buf2);
// Prints: <Buffer 88 13 70 17>
当使用 <TypedArray> 的 .buffer
创建 Buffer
时,可以通过传入 byteOffset
和 length
参数仅使用底层 <ArrayBuffer> 的一部分。
import { Buffer } from 'node:buffer';
const arr = new Uint16Array(20);
const buf = Buffer.from(arr.buffer, 0, 16);
console.log(buf.length);
// Prints: 16
const { Buffer } = require('node:buffer');
const arr = new Uint16Array(20);
const buf = Buffer.from(arr.buffer, 0, 16);
console.log(buf.length);
// Prints: 16
Buffer.from()
和 TypedArray.from()
具有不同的签名和实现。具体来说,<TypedArray> 的变体接受第二个参数,该参数是一个映射函数,会对类型化数组的每个元素调用
然而,Buffer.from()
方法不支持使用映射函数
缓冲区与迭代#
Buffer
实例可以使用 for..of
语法进行迭代
import { Buffer } from 'node:buffer';
const buf = Buffer.from([1, 2, 3]);
for (const b of buf) {
console.log(b);
}
// Prints:
// 1
// 2
// 3
const { Buffer } = require('node:buffer');
const buf = Buffer.from([1, 2, 3]);
for (const b of buf) {
console.log(b);
}
// Prints:
// 1
// 2
// 3
此外,可以使用 buf.values()
、buf.keys()
和 buf.entries()
方法创建迭代器。
类:Blob
#
一个 <Blob> 封装了不可变的原始数据,可以安全地在多个工作线程之间共享。
new buffer.Blob([sources[, options]])
#
sources
<string[]> | <ArrayBuffer[]> | <TypedArray[]> | <DataView[]> | <Blob[]> 一个由字符串、<ArrayBuffer>、<TypedArray>、<DataView> 或 <Blob> 对象组成的数组,或任何这些对象的混合,它们将被存储在Blob
中。options
<Object>
创建一个新的 Blob
对象,其中包含给定源的串联。
<ArrayBuffer>、<TypedArray>、<DataView> 和 <Buffer> 源被复制到 'Blob' 中,因此在创建 'Blob' 后可以安全地修改它们。
字符串源被编码为 UTF-8 字节序列并复制到 Blob 中。每个字符串部分内未匹配的代理对将被 Unicode U+FFFD 替换字符替换。
blob.arrayBuffer()
#
- 返回:<Promise>
返回一个 promise,该 promise 会兑现为一个包含 Blob
数据副本的 <ArrayBuffer>。
blob.bytes()
#
blob.bytes()
方法以 Promise<Uint8Array>
的形式返回 Blob
对象的字节。
const blob = new Blob(['hello']);
blob.bytes().then((bytes) => {
console.log(bytes); // Outputs: Uint8Array(5) [ 104, 101, 108, 108, 111 ]
});
blob.size
#
Blob
的总大小(以字节为单位)。
blob.slice([start[, end[, type]]])
#
创建并返回一个包含此 Blob
对象数据子集的新 Blob
。原始的 Blob
不会被改变。
Blob
对象与 MessageChannel
#
一旦创建了 <Blob> 对象,它可以通过 MessagePort
发送到多个目的地,而无需传输或立即复制数据。只有在调用 arrayBuffer()
或 text()
方法时,Blob
包含的数据才会被复制。
import { Blob } from 'node:buffer';
import { setTimeout as delay } from 'node:timers/promises';
const blob = new Blob(['hello there']);
const mc1 = new MessageChannel();
const mc2 = new MessageChannel();
mc1.port1.onmessage = async ({ data }) => {
console.log(await data.arrayBuffer());
mc1.port1.close();
};
mc2.port1.onmessage = async ({ data }) => {
await delay(1000);
console.log(await data.arrayBuffer());
mc2.port1.close();
};
mc1.port2.postMessage(blob);
mc2.port2.postMessage(blob);
// The Blob is still usable after posting.
blob.text().then(console.log);
const { Blob } = require('node:buffer');
const { setTimeout: delay } = require('node:timers/promises');
const blob = new Blob(['hello there']);
const mc1 = new MessageChannel();
const mc2 = new MessageChannel();
mc1.port1.onmessage = async ({ data }) => {
console.log(await data.arrayBuffer());
mc1.port1.close();
};
mc2.port1.onmessage = async ({ data }) => {
await delay(1000);
console.log(await data.arrayBuffer());
mc2.port1.close();
};
mc1.port2.postMessage(blob);
mc2.port2.postMessage(blob);
// The Blob is still usable after posting.
blob.text().then(console.log);
类:Buffer
#
Buffer
类是直接处理二进制数据的全局类型。它可以通过多种方式构造。
静态方法:Buffer.alloc(size[, fill[, encoding]])
#
size
<integer> 新Buffer
的期望长度。fill
<string> | <Buffer> | <Uint8Array> | <integer> 用于预填充新Buffer
的值。默认值:0
。encoding
<string> 如果fill
是一个字符串,这是它的编码。默认值:'utf8'
。- 返回:<Buffer>
分配一个大小为 size
字节的新 Buffer
。如果 fill
是 undefined
,Buffer
将被零填充。
import { Buffer } from 'node:buffer';
const buf = Buffer.alloc(5);
console.log(buf);
// Prints: <Buffer 00 00 00 00 00>
const { Buffer } = require('node:buffer');
const buf = Buffer.alloc(5);
console.log(buf);
// Prints: <Buffer 00 00 00 00 00>
如果 size
大于 buffer.constants.MAX_LENGTH
或小于 0,将抛出 ERR_OUT_OF_RANGE
。
如果指定了 fill
,分配的 Buffer
将通过调用 buf.fill(fill)
进行初始化。
import { Buffer } from 'node:buffer';
const buf = Buffer.alloc(5, 'a');
console.log(buf);
// Prints: <Buffer 61 61 61 61 61>
const { Buffer } = require('node:buffer');
const buf = Buffer.alloc(5, 'a');
console.log(buf);
// Prints: <Buffer 61 61 61 61 61>
如果同时指定了 fill
和 encoding
,分配的 Buffer
将通过调用 buf.fill(fill, encoding)
进行初始化。
import { Buffer } from 'node:buffer';
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
console.log(buf);
// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
const { Buffer } = require('node:buffer');
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
console.log(buf);
// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
调用 Buffer.alloc()
可能比其替代方案 Buffer.allocUnsafe()
慢得多,但能确保新创建的 Buffer
实例内容永远不会包含先前分配的敏感数据,包括可能不是为 Buffer
分配的数据。
如果 size
不是数字,将抛出 TypeError
。
静态方法:Buffer.allocUnsafe(size)
#
分配一个大小为 size
字节的新 Buffer
。如果 size
大于 buffer.constants.MAX_LENGTH
或小于 0,则会抛出 ERR_OUT_OF_RANGE
。
以此方式创建的 Buffer
实例的底层内存未初始化。新创建的 Buffer
的内容是未知的,并且可能包含敏感数据。请改用 Buffer.alloc()
来用零初始化 Buffer
实例。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(10);
console.log(buf);
// Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>
buf.fill(0);
console.log(buf);
// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(10);
console.log(buf);
// Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>
buf.fill(0);
console.log(buf);
// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>
如果 size
不是数字,将抛出 TypeError
。
Buffer
模块预分配一个大小为 Buffer.poolSize
的内部 Buffer
实例,该实例用作快速分配新 Buffer
实例的池,这些实例使用 Buffer.allocUnsafe()
、Buffer.from(array)
、Buffer.from(string)
和 Buffer.concat()
创建,仅当 size
小于 Buffer.poolSize >>> 1
(Buffer.poolSize
除以二的向下取整)时。
使用这个预分配的内部内存池是调用 Buffer.alloc(size, fill)
与 Buffer.allocUnsafe(size).fill(fill)
之间的关键区别。具体来说,Buffer.alloc(size, fill)
将永远不会使用内部 Buffer
池,而如果 size
小于或等于 Buffer.poolSize
的一半,Buffer.allocUnsafe(size).fill(fill)
将会使用内部 Buffer
池。这个差异很细微,但在应用程序需要 Buffer.allocUnsafe()
提供的额外性能时可能很重要。
静态方法:Buffer.allocUnsafeSlow(size)
#
分配一个大小为 size
字节的新 Buffer
。如果 size
大于 buffer.constants.MAX_LENGTH
或小于 0,则会抛出 ERR_OUT_OF_RANGE
。如果 size
为 0,则创建一个零长度的 Buffer
。
以此方式创建的 Buffer
实例的底层内存未初始化。新创建的 Buffer
的内容是未知的,并且可能包含敏感数据。使用 buf.fill(0)
将此类 Buffer
实例用零进行初始化。
当使用 Buffer.allocUnsafe()
分配新的 Buffer
实例时,小于 Buffer.poolSize >>> 1
(默认 poolSize 时为 4KiB)的分配是从单个预分配的 Buffer
中切片出来的。这使得应用程序可以避免因创建许多单独分配的 Buffer
实例而产生的垃圾回收开销。这种方法通过消除跟踪和清理大量单个 ArrayBuffer
对象的需要,提高了性能和内存使用率。
然而,在开发者可能需要在一个不确定的时间内保留一小块内存池的情况下,使用 Buffer.allocUnsafeSlow()
创建一个非池化的 Buffer
实例然后复制出相关位可能是合适的。
import { Buffer } from 'node:buffer';
// Need to keep around a few small chunks of memory.
const store = [];
socket.on('readable', () => {
let data;
while (null !== (data = readable.read())) {
// Allocate for retained data.
const sb = Buffer.allocUnsafeSlow(10);
// Copy the data into the new allocation.
data.copy(sb, 0, 0, 10);
store.push(sb);
}
});
const { Buffer } = require('node:buffer');
// Need to keep around a few small chunks of memory.
const store = [];
socket.on('readable', () => {
let data;
while (null !== (data = readable.read())) {
// Allocate for retained data.
const sb = Buffer.allocUnsafeSlow(10);
// Copy the data into the new allocation.
data.copy(sb, 0, 0, 10);
store.push(sb);
}
});
如果 size
不是数字,将抛出 TypeError
。
静态方法:Buffer.byteLength(string[, encoding])
#
string
<string> | <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <SharedArrayBuffer> 一个用于计算长度的值。encoding
<string> 如果string
是一个字符串,这是它的编码。默认值:'utf8'
。- 返回:<integer>
string
中包含的字节数。
返回一个字符串在使用 encoding
编码时的字节长度。这与 String.prototype.length
不同,后者不考虑用于将字符串转换为字节的编码。
对于 'base64'
、'base64url'
和 'hex'
,此函数假定输入有效。对于包含非 base64/hex 编码数据(例如空格)的字符串,返回值可能大于从该字符串创建的 Buffer
的长度。
import { Buffer } from 'node:buffer';
const str = '\u00bd + \u00bc = \u00be';
console.log(`${str}: ${str.length} characters, ` +
`${Buffer.byteLength(str, 'utf8')} bytes`);
// Prints: ½ + ¼ = ¾: 9 characters, 12 bytes
const { Buffer } = require('node:buffer');
const str = '\u00bd + \u00bc = \u00be';
console.log(`${str}: ${str.length} characters, ` +
`${Buffer.byteLength(str, 'utf8')} bytes`);
// Prints: ½ + ¼ = ¾: 9 characters, 12 bytes
当 string
是 <Buffer> | <DataView> | <TypedArray> | <ArrayBuffer> | <SharedArrayBuffer> 时,返回其 .byteLength
报告的字节长度。
静态方法:Buffer.compare(buf1, buf2)
#
buf1
<Buffer> | <Uint8Array>buf2
<Buffer> | <Uint8Array>- 返回:<integer>
-1
、0
或1
,取决于比较结果。详见buf.compare()
。
比较 buf1
和 buf2
,通常用于对 Buffer
实例数组进行排序。这等同于调用 buf1.compare(buf2)
。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('1234');
const buf2 = Buffer.from('0123');
const arr = [buf1, buf2];
console.log(arr.sort(Buffer.compare));
// Prints: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (This result is equal to: [buf2, buf1].)
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from('1234');
const buf2 = Buffer.from('0123');
const arr = [buf1, buf2];
console.log(arr.sort(Buffer.compare));
// Prints: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (This result is equal to: [buf2, buf1].)
静态方法:Buffer.concat(list[, totalLength])
#
list
<Buffer[]> | <Uint8Array[]> 要连接的Buffer
或 <Uint8Array> 实例列表。totalLength
<integer> 连接后list
中Buffer
实例的总长度。- 返回:<Buffer>
返回一个新的 Buffer
,它是将 list
中所有 Buffer
实例连接在一起的结果。
如果列表没有项目,或者 totalLength
为 0,则返回一个新的零长度 Buffer
。
如果未提供 totalLength
,则通过将 list
中 Buffer
实例的长度相加来计算它。
如果提供了 totalLength
,它会被强制转换为一个无符号整数。如果 list
中 Buffer
的组合长度超过 totalLength
,结果将被截断为 totalLength
。如果 list
中 Buffer
的组合长度小于 totalLength
,剩余的空间将用零填充。
import { Buffer } from 'node:buffer';
// Create a single `Buffer` from a list of three `Buffer` instances.
const buf1 = Buffer.alloc(10);
const buf2 = Buffer.alloc(14);
const buf3 = Buffer.alloc(18);
const totalLength = buf1.length + buf2.length + buf3.length;
console.log(totalLength);
// Prints: 42
const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);
console.log(bufA);
// Prints: <Buffer 00 00 00 00 ...>
console.log(bufA.length);
// Prints: 42
const { Buffer } = require('node:buffer');
// Create a single `Buffer` from a list of three `Buffer` instances.
const buf1 = Buffer.alloc(10);
const buf2 = Buffer.alloc(14);
const buf3 = Buffer.alloc(18);
const totalLength = buf1.length + buf2.length + buf3.length;
console.log(totalLength);
// Prints: 42
const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);
console.log(bufA);
// Prints: <Buffer 00 00 00 00 ...>
console.log(bufA.length);
// Prints: 42
Buffer.concat()
也可能像 Buffer.allocUnsafe()
一样使用内部的 Buffer
池。
静态方法:Buffer.copyBytesFrom(view[, offset[, length]])
#
view
<TypedArray> 要复制的 <TypedArray>。offset
<integer>view
内的起始偏移量。默认值:0
。length
<integer> 从view
复制的元素数量。默认值:view.length - offset
。- 返回:<Buffer>
将 view
的底层内存复制到一个新的 Buffer
中。
const u16 = new Uint16Array([0, 0xffff]);
const buf = Buffer.copyBytesFrom(u16, 1, 1);
u16[1] = 0;
console.log(buf.length); // 2
console.log(buf[0]); // 255
console.log(buf[1]); // 255
静态方法:Buffer.from(array)
#
array
<integer[]>- 返回:<Buffer>
使用一个范围在 0
– 255
之间的字节数组 array
来分配一个新的 Buffer
。超出该范围的数组条目将被截断以适应它。
import { Buffer } from 'node:buffer';
// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'.
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
const { Buffer } = require('node:buffer');
// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'.
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
如果 array
是一个类数组对象(即,具有 number
类型的 length
属性的对象),则它被视为一个数组,除非它是一个 Buffer
或 Uint8Array
。这意味着所有其他 TypedArray
变体都被视为一个 Array
。要从支持 TypedArray
的字节创建一个 Buffer
,请使用 Buffer.copyBytesFrom()
。
如果 array
不是一个 Array
或适用于 Buffer.from()
变体的其他类型,将抛出 TypeError
。
Buffer.from(array)
和 Buffer.from(string)
也可能像 Buffer.allocUnsafe()
一样使用内部的 Buffer
池。
静态方法:Buffer.from(arrayBuffer[, byteOffset[, length]])
#
arrayBuffer
<ArrayBuffer> | <SharedArrayBuffer> 一个 <ArrayBuffer>、<SharedArrayBuffer>,例如 <TypedArray> 的.buffer
属性。byteOffset
<integer> 要暴露的第一个字节的索引。默认值:0
。length
<integer> 要暴露的字节数。默认值:arrayBuffer.byteLength - byteOffset
。- 返回:<Buffer>
这将创建 <ArrayBuffer> 的视图,而不复制底层内存。例如,当传递一个对 <TypedArray> 实例的 .buffer
属性的引用时,新创建的 Buffer
将与 <TypedArray> 的底层 ArrayBuffer
共享相同的已分配内存。
import { Buffer } from 'node:buffer';
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;
// Shares memory with `arr`.
const buf = Buffer.from(arr.buffer);
console.log(buf);
// Prints: <Buffer 88 13 a0 0f>
// Changing the original Uint16Array changes the Buffer also.
arr[1] = 6000;
console.log(buf);
// Prints: <Buffer 88 13 70 17>
const { Buffer } = require('node:buffer');
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;
// Shares memory with `arr`.
const buf = Buffer.from(arr.buffer);
console.log(buf);
// Prints: <Buffer 88 13 a0 0f>
// Changing the original Uint16Array changes the Buffer also.
arr[1] = 6000;
console.log(buf);
// Prints: <Buffer 88 13 70 17>
可选的 byteOffset
和 length
参数指定 arrayBuffer
内的一个内存范围,该范围将由 Buffer
共享。
import { Buffer } from 'node:buffer';
const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);
console.log(buf.length);
// Prints: 2
const { Buffer } = require('node:buffer');
const ab = new ArrayBuffer(10);
const buf = Buffer.from(ab, 0, 2);
console.log(buf.length);
// Prints: 2
如果 arrayBuffer
不是 <ArrayBuffer> 或 <SharedArrayBuffer> 或其他适合 Buffer.from()
变体的类型,则会抛出 TypeError
。
重要的是要记住,一个后备的 ArrayBuffer
可以覆盖一个超出 TypedArray
视图边界的内存范围。使用 TypedArray
的 buffer
属性创建的新 Buffer
可能会超出 TypedArray
的范围
import { Buffer } from 'node:buffer';
const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 elements
const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 elements
console.log(arrA.buffer === arrB.buffer); // true
const buf = Buffer.from(arrB.buffer);
console.log(buf);
// Prints: <Buffer 63 64 65 66>
const { Buffer } = require('node:buffer');
const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]); // 4 elements
const arrB = new Uint8Array(arrA.buffer, 1, 2); // 2 elements
console.log(arrA.buffer === arrB.buffer); // true
const buf = Buffer.from(arrB.buffer);
console.log(buf);
// Prints: <Buffer 63 64 65 66>
静态方法:Buffer.from(buffer)
#
buffer
<Buffer> | <Uint8Array> 一个现有的Buffer
或 <Uint8Array>,从中复制数据。- 返回:<Buffer>
将传递的 buffer
数据复制到一个新的 Buffer
实例中。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);
buf1[0] = 0x61;
console.log(buf1.toString());
// Prints: auffer
console.log(buf2.toString());
// Prints: buffer
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);
buf1[0] = 0x61;
console.log(buf1.toString());
// Prints: auffer
console.log(buf2.toString());
// Prints: buffer
如果 buffer
不是一个 Buffer
或其他适合 Buffer.from()
变体的类型,将抛出 TypeError
。
静态方法:Buffer.from(object[, offsetOrEncoding[, length]])
#
object
<Object> 一个支持Symbol.toPrimitive
或valueOf()
的对象。offsetOrEncoding
<integer> | <string> 一个字节偏移量或编码。length
<integer> 一个长度。- 返回:<Buffer>
对于其 valueOf()
函数返回值不严格等于 object
的对象,返回 Buffer.from(object.valueOf(), offsetOrEncoding, length)
。
import { Buffer } from 'node:buffer';
const buf = Buffer.from(new String('this is a test'));
// Prints: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
const { Buffer } = require('node:buffer');
const buf = Buffer.from(new String('this is a test'));
// Prints: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
对于支持 Symbol.toPrimitive
的对象,返回 Buffer.from(object[Symbol.toPrimitive]('string'), offsetOrEncoding)
。
import { Buffer } from 'node:buffer';
class Foo {
[Symbol.toPrimitive]() {
return 'this is a test';
}
}
const buf = Buffer.from(new Foo(), 'utf8');
// Prints: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
const { Buffer } = require('node:buffer');
class Foo {
[Symbol.toPrimitive]() {
return 'this is a test';
}
}
const buf = Buffer.from(new Foo(), 'utf8');
// Prints: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>
如果 object
没有上述方法,或者不是适合 Buffer.from()
变体的其他类型,将抛出 TypeError
。
静态方法:Buffer.from(string[, encoding])
#
创建一个包含 string
的新 Buffer
。encoding
参数标识了将 string
转换为字节时要使用的字符编码。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést
如果 string
不是一个字符串或适用于 Buffer.from()
变体的其他类型,将抛出 TypeError
。
Buffer.from(string)
也可能像 Buffer.allocUnsafe()
一样使用内部的 Buffer
池。
静态方法:Buffer.isBuffer(obj)
#
如果 obj
是一个 Buffer
,则返回 true
,否则返回 false
。
import { Buffer } from 'node:buffer';
Buffer.isBuffer(Buffer.alloc(10)); // true
Buffer.isBuffer(Buffer.from('foo')); // true
Buffer.isBuffer('a string'); // false
Buffer.isBuffer([]); // false
Buffer.isBuffer(new Uint8Array(1024)); // false
const { Buffer } = require('node:buffer');
Buffer.isBuffer(Buffer.alloc(10)); // true
Buffer.isBuffer(Buffer.from('foo')); // true
Buffer.isBuffer('a string'); // false
Buffer.isBuffer([]); // false
Buffer.isBuffer(new Uint8Array(1024)); // false
静态方法:Buffer.isEncoding(encoding)
#
如果 encoding
是支持的字符编码的名称,则返回 true
,否则返回 false
。
import { Buffer } from 'node:buffer';
console.log(Buffer.isEncoding('utf8'));
// Prints: true
console.log(Buffer.isEncoding('hex'));
// Prints: true
console.log(Buffer.isEncoding('utf/8'));
// Prints: false
console.log(Buffer.isEncoding(''));
// Prints: false
const { Buffer } = require('node:buffer');
console.log(Buffer.isEncoding('utf8'));
// Prints: true
console.log(Buffer.isEncoding('hex'));
// Prints: true
console.log(Buffer.isEncoding('utf/8'));
// Prints: false
console.log(Buffer.isEncoding(''));
// Prints: false
buf[index]
#
index
<integer>
索引运算符 [index]
可用于获取和设置 buf
中位置 index
处的八位字节。这些值指的是单个字节,因此合法的值范围在 0x00
和 0xFF
(十六进制)或 0
和 255
(十进制)之间。
这个运算符继承自 Uint8Array
,因此它在越界访问时的行为与 Uint8Array
相同。换句话说,当 index
为负或大于等于 buf.length
时,buf[index]
返回 undefined
,而当 index
为负或 >= buf.length
时,buf[index] = value
不会修改缓冲区。
import { Buffer } from 'node:buffer';
// Copy an ASCII string into a `Buffer` one byte at a time.
// (This only works for ASCII-only strings. In general, one should use
// `Buffer.from()` to perform this conversion.)
const str = 'Node.js';
const buf = Buffer.allocUnsafe(str.length);
for (let i = 0; i < str.length; i++) {
buf[i] = str.charCodeAt(i);
}
console.log(buf.toString('utf8'));
// Prints: Node.js
const { Buffer } = require('node:buffer');
// Copy an ASCII string into a `Buffer` one byte at a time.
// (This only works for ASCII-only strings. In general, one should use
// `Buffer.from()` to perform this conversion.)
const str = 'Node.js';
const buf = Buffer.allocUnsafe(str.length);
for (let i = 0; i < str.length; i++) {
buf[i] = str.charCodeAt(i);
}
console.log(buf.toString('utf8'));
// Prints: Node.js
buf.buffer
#
- 类型:<ArrayBuffer> 创建此
Buffer
对象所基于的底层ArrayBuffer
对象。
不保证此 ArrayBuffer
与原始 Buffer
完全对应。详见关于 buf.byteOffset
的说明。
import { Buffer } from 'node:buffer';
const arrayBuffer = new ArrayBuffer(16);
const buffer = Buffer.from(arrayBuffer);
console.log(buffer.buffer === arrayBuffer);
// Prints: true
const { Buffer } = require('node:buffer');
const arrayBuffer = new ArrayBuffer(16);
const buffer = Buffer.from(arrayBuffer);
console.log(buffer.buffer === arrayBuffer);
// Prints: true
buf.byteOffset
#
- 类型:<integer>
Buffer
的底层ArrayBuffer
对象的byteOffset
。
当在 Buffer.from(ArrayBuffer, byteOffset, length)
中设置 byteOffset
时,或者有时在分配小于 Buffer.poolSize
的 Buffer
时,缓冲区不会从底层 ArrayBuffer
的零偏移量开始。
当使用 buf.buffer
直接访问底层 ArrayBuffer
时,这可能会导致问题,因为 ArrayBuffer
的其他部分可能与 Buffer
对象本身无关。
创建一个与 Buffer
共享内存的 TypedArray
对象时的一个常见问题是,在这种情况下,需要正确指定 byteOffset
import { Buffer } from 'node:buffer';
// Create a buffer smaller than `Buffer.poolSize`.
const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
// When casting the Node.js Buffer to an Int8Array, use the byteOffset
// to refer only to the part of `nodeBuffer.buffer` that contains the memory
// for `nodeBuffer`.
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);
const { Buffer } = require('node:buffer');
// Create a buffer smaller than `Buffer.poolSize`.
const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
// When casting the Node.js Buffer to an Int8Array, use the byteOffset
// to refer only to the part of `nodeBuffer.buffer` that contains the memory
// for `nodeBuffer`.
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);
buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])
#
target
<Buffer> | <Uint8Array> 一个与buf
进行比较的Buffer
或 <Uint8Array>。targetStart
<integer> 在target
中开始比较的偏移量。默认值:0
。targetEnd
<integer> 在target
中结束比较的偏移量(不包括)。默认值:target.length
。sourceStart
<integer> 在buf
中开始比较的偏移量。默认值:0
。sourceEnd
<integer> 在buf
中结束比较的偏移量(不包括)。默认值:buf.length
。- 返回:<integer>
将 buf
与 target
进行比较,并返回一个数字,指示 buf
在排序顺序中是位于 target
之前、之后还是与之相同。比较基于每个 Buffer
中的实际字节序列。
- 如果
target
与buf
相同,则返回0
。 - 如果排序时
target
应该排在buf
之前,则返回1
。 - 如果排序时
target
应该排在buf
之后,则返回-1
。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('BCD');
const buf3 = Buffer.from('ABCD');
console.log(buf1.compare(buf1));
// Prints: 0
console.log(buf1.compare(buf2));
// Prints: -1
console.log(buf1.compare(buf3));
// Prints: -1
console.log(buf2.compare(buf1));
// Prints: 1
console.log(buf2.compare(buf3));
// Prints: 1
console.log([buf1, buf2, buf3].sort(Buffer.compare));
// Prints: [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// (This result is equal to: [buf1, buf3, buf2].)
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('BCD');
const buf3 = Buffer.from('ABCD');
console.log(buf1.compare(buf1));
// Prints: 0
console.log(buf1.compare(buf2));
// Prints: -1
console.log(buf1.compare(buf3));
// Prints: -1
console.log(buf2.compare(buf1));
// Prints: 1
console.log(buf2.compare(buf3));
// Prints: 1
console.log([buf1, buf2, buf3].sort(Buffer.compare));
// Prints: [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// (This result is equal to: [buf1, buf3, buf2].)
可选的 targetStart
、targetEnd
、sourceStart
和 sourceEnd
参数可用于将比较限制在 target
和 buf
各自的特定范围内。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]);
const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]);
console.log(buf1.compare(buf2, 5, 9, 0, 4));
// Prints: 0
console.log(buf1.compare(buf2, 0, 6, 4));
// Prints: -1
console.log(buf1.compare(buf2, 5, 6, 5));
// Prints: 1
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8, 9]);
const buf2 = Buffer.from([5, 6, 7, 8, 9, 1, 2, 3, 4]);
console.log(buf1.compare(buf2, 5, 9, 0, 4));
// Prints: 0
console.log(buf1.compare(buf2, 0, 6, 4));
// Prints: -1
console.log(buf1.compare(buf2, 5, 6, 5));
// Prints: 1
如果 targetStart < 0
、sourceStart < 0
、targetEnd > target.byteLength
或 sourceEnd > source.byteLength
,则会抛出 ERR_OUT_OF_RANGE
。
buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])
#
target
<Buffer> | <Uint8Array> 要复制到的Buffer
或 <Uint8Array>。targetStart
<integer> 在target
中开始写入的偏移量。默认值:0
。sourceStart
<integer> 在buf
中开始复制的偏移量。默认值:0
。sourceEnd
<integer> 在buf
中停止复制的偏移量(不包括)。默认值:buf.length
。- 返回:<integer> 复制的字节数。
将数据从 buf
的一个区域复制到 target
的一个区域,即使 target
的内存区域与 buf
重叠。
TypedArray.prototype.set()
执行相同的操作,并且对所有 TypedArray(包括 Node.js 的 Buffer
)都可用,尽管它接受不同的函数参数。
import { Buffer } from 'node:buffer';
// Create two `Buffer` instances.
const buf1 = Buffer.allocUnsafe(26);
const buf2 = Buffer.allocUnsafe(26).fill('!');
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
// Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2`.
buf1.copy(buf2, 8, 16, 20);
// This is equivalent to:
// buf2.set(buf1.subarray(16, 20), 8);
console.log(buf2.toString('ascii', 0, 25));
// Prints: !!!!!!!!qrst!!!!!!!!!!!!!
const { Buffer } = require('node:buffer');
// Create two `Buffer` instances.
const buf1 = Buffer.allocUnsafe(26);
const buf2 = Buffer.allocUnsafe(26).fill('!');
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
// Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2`.
buf1.copy(buf2, 8, 16, 20);
// This is equivalent to:
// buf2.set(buf1.subarray(16, 20), 8);
console.log(buf2.toString('ascii', 0, 25));
// Prints: !!!!!!!!qrst!!!!!!!!!!!!!
import { Buffer } from 'node:buffer';
// Create a `Buffer` and copy data from one region to an overlapping region
// within the same `Buffer`.
const buf = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf[i] = i + 97;
}
buf.copy(buf, 0, 4, 10);
console.log(buf.toString());
// Prints: efghijghijklmnopqrstuvwxyz
const { Buffer } = require('node:buffer');
// Create a `Buffer` and copy data from one region to an overlapping region
// within the same `Buffer`.
const buf = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf[i] = i + 97;
}
buf.copy(buf, 0, 4, 10);
console.log(buf.toString());
// Prints: efghijghijklmnopqrstuvwxyz
buf.entries()
#
- 返回:<Iterator>
从 buf
的内容中创建并返回一个 [index, byte]
对的迭代器。
import { Buffer } from 'node:buffer';
// Log the entire contents of a `Buffer`.
const buf = Buffer.from('buffer');
for (const pair of buf.entries()) {
console.log(pair);
}
// Prints:
// [0, 98]
// [1, 117]
// [2, 102]
// [3, 102]
// [4, 101]
// [5, 114]
const { Buffer } = require('node:buffer');
// Log the entire contents of a `Buffer`.
const buf = Buffer.from('buffer');
for (const pair of buf.entries()) {
console.log(pair);
}
// Prints:
// [0, 98]
// [1, 117]
// [2, 102]
// [3, 102]
// [4, 101]
// [5, 114]
buf.equals(otherBuffer)
#
otherBuffer
<Buffer> | <Uint8Array> 一个与buf
进行比较的Buffer
或 <Uint8Array>。- 返回:<boolean>
如果 buf
和 otherBuffer
的字节完全相同,则返回 true
,否则返回 false
。等价于 buf.compare(otherBuffer) === 0
。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('414243', 'hex');
const buf3 = Buffer.from('ABCD');
console.log(buf1.equals(buf2));
// Prints: true
console.log(buf1.equals(buf3));
// Prints: false
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('414243', 'hex');
const buf3 = Buffer.from('ABCD');
console.log(buf1.equals(buf2));
// Prints: true
console.log(buf1.equals(buf3));
// Prints: false
buf.fill(value[, offset[, end]][, encoding])
#
value
<string> | <Buffer> | <Uint8Array> | <integer> 用于填充buf
的值。空值(字符串、Uint8Array、Buffer)被强制转换为0
。offset
<integer> 在开始填充buf
之前要跳过的字节数。默认值:0
。end
<integer> 在哪里停止填充buf
(不包括)。默认值:buf.length
。encoding
<string> 如果value
是字符串,则为其编码。默认值:'utf8'
。- 返回:<Buffer> 对
buf
的引用。
用指定的 value
填充 buf
。如果未给出 offset
和 end
,则将填充整个 buf
。
import { Buffer } from 'node:buffer';
// Fill a `Buffer` with the ASCII character 'h'.
const b = Buffer.allocUnsafe(50).fill('h');
console.log(b.toString());
// Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
// Fill a buffer with empty string
const c = Buffer.allocUnsafe(5).fill('');
console.log(c.fill(''));
// Prints: <Buffer 00 00 00 00 00>
const { Buffer } = require('node:buffer');
// Fill a `Buffer` with the ASCII character 'h'.
const b = Buffer.allocUnsafe(50).fill('h');
console.log(b.toString());
// Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
// Fill a buffer with empty string
const c = Buffer.allocUnsafe(5).fill('');
console.log(c.fill(''));
// Prints: <Buffer 00 00 00 00 00>
如果 value
不是字符串、Buffer
或整数,它会被强制转换为一个 uint32
值。如果结果整数大于 255
(十进制),buf
将被填充为 value & 255
。
如果 fill()
操作的最后一次写入落在一个多字节字符上,那么只有该字符中能放入 buf
的字节会被写入。
import { Buffer } from 'node:buffer';
// Fill a `Buffer` with character that takes up two bytes in UTF-8.
console.log(Buffer.allocUnsafe(5).fill('\u0222'));
// Prints: <Buffer c8 a2 c8 a2 c8>
const { Buffer } = require('node:buffer');
// Fill a `Buffer` with character that takes up two bytes in UTF-8.
console.log(Buffer.allocUnsafe(5).fill('\u0222'));
// Prints: <Buffer c8 a2 c8 a2 c8>
如果 value
包含无效字符,它将被截断;如果没有剩余的有效填充数据,则会抛出异常。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(5);
console.log(buf.fill('a'));
// Prints: <Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'));
// Prints: <Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'));
// Throws an exception.
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(5);
console.log(buf.fill('a'));
// Prints: <Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'));
// Prints: <Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'));
// Throws an exception.
buf.includes(value[, byteOffset][, encoding])
#
value
<string> | <Buffer> | <Uint8Array> | <integer> 要搜索的内容。byteOffset
<integer> 在buf
中开始搜索的位置。如果为负数,则偏移量从buf
的末尾计算。默认值:0
。encoding
<string> 如果value
是一个字符串,这是它的编码。默认值:'utf8'
。- 返回:<boolean> 如果在
buf
中找到value
,则为true
,否则为false
。
等价于 buf.indexOf() !== -1
。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('this is a buffer');
console.log(buf.includes('this'));
// Prints: true
console.log(buf.includes('is'));
// Prints: true
console.log(buf.includes(Buffer.from('a buffer')));
// Prints: true
console.log(buf.includes(97));
// Prints: true (97 is the decimal ASCII value for 'a')
console.log(buf.includes(Buffer.from('a buffer example')));
// Prints: false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)));
// Prints: true
console.log(buf.includes('this', 4));
// Prints: false
const { Buffer } = require('node:buffer');
const buf = Buffer.from('this is a buffer');
console.log(buf.includes('this'));
// Prints: true
console.log(buf.includes('is'));
// Prints: true
console.log(buf.includes(Buffer.from('a buffer')));
// Prints: true
console.log(buf.includes(97));
// Prints: true (97 is the decimal ASCII value for 'a')
console.log(buf.includes(Buffer.from('a buffer example')));
// Prints: false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)));
// Prints: true
console.log(buf.includes('this', 4));
// Prints: false
buf.indexOf(value[, byteOffset][, encoding])
#
value
<string> | <Buffer> | <Uint8Array> | <integer> 要搜索的内容。byteOffset
<integer> 在buf
中开始搜索的位置。如果为负数,则偏移量从buf
的末尾计算。默认值:0
。encoding
<string> 如果value
是一个字符串,这是用于确定将在buf
中搜索的字符串的二进制表示的编码。默认值:'utf8'
。- 返回:<integer>
buf
中第一次出现value
的索引,如果buf
不包含value
,则返回-1
。
如果 value
是
- 一个字符串,
value
根据encoding
中的字符编码进行解释。 - 一个
Buffer
或 <Uint8Array>,value
将被完整使用。要比较部分Buffer
,请使用buf.subarray
。 - 一个数字,
value
将被解释为0
到255
之间的无符号 8 位整数值。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('this is a buffer');
console.log(buf.indexOf('this'));
// Prints: 0
console.log(buf.indexOf('is'));
// Prints: 2
console.log(buf.indexOf(Buffer.from('a buffer')));
// Prints: 8
console.log(buf.indexOf(97));
// Prints: 8 (97 is the decimal ASCII value for 'a')
console.log(buf.indexOf(Buffer.from('a buffer example')));
// Prints: -1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)));
// Prints: 8
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');
console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'));
// Prints: 4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'));
// Prints: 6
const { Buffer } = require('node:buffer');
const buf = Buffer.from('this is a buffer');
console.log(buf.indexOf('this'));
// Prints: 0
console.log(buf.indexOf('is'));
// Prints: 2
console.log(buf.indexOf(Buffer.from('a buffer')));
// Prints: 8
console.log(buf.indexOf(97));
// Prints: 8 (97 is the decimal ASCII value for 'a')
console.log(buf.indexOf(Buffer.from('a buffer example')));
// Prints: -1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)));
// Prints: 8
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');
console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'));
// Prints: 4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'));
// Prints: 6
如果 value
不是字符串、数字或 Buffer
,此方法将抛出 TypeError
。如果 value
是一个数字,它将被强制转换为一个有效的字节值,即 0 到 255 之间的整数。
如果 byteOffset
不是数字,它将被强制转换为数字。如果强制转换的结果是 NaN
或 0
,则将搜索整个缓冲区。此行为与 String.prototype.indexOf()
匹配。
import { Buffer } from 'node:buffer';
const b = Buffer.from('abcdef');
// Passing a value that's a number, but not a valid byte.
// Prints: 2, equivalent to searching for 99 or 'c'.
console.log(b.indexOf(99.9));
console.log(b.indexOf(256 + 99));
// Passing a byteOffset that coerces to NaN or 0.
// Prints: 1, searching the whole buffer.
console.log(b.indexOf('b', undefined));
console.log(b.indexOf('b', {}));
console.log(b.indexOf('b', null));
console.log(b.indexOf('b', []));
const { Buffer } = require('node:buffer');
const b = Buffer.from('abcdef');
// Passing a value that's a number, but not a valid byte.
// Prints: 2, equivalent to searching for 99 or 'c'.
console.log(b.indexOf(99.9));
console.log(b.indexOf(256 + 99));
// Passing a byteOffset that coerces to NaN or 0.
// Prints: 1, searching the whole buffer.
console.log(b.indexOf('b', undefined));
console.log(b.indexOf('b', {}));
console.log(b.indexOf('b', null));
console.log(b.indexOf('b', []));
如果 value
是一个空字符串或空 Buffer
,并且 byteOffset
小于 buf.length
,则将返回 byteOffset
。如果 value
为空并且 byteOffset
至少为 buf.length
,则将返回 buf.length
。
buf.keys()
#
- 返回:<Iterator>
创建并返回一个 buf
键(索引)的迭代器。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('buffer');
for (const key of buf.keys()) {
console.log(key);
}
// Prints:
// 0
// 1
// 2
// 3
// 4
// 5
const { Buffer } = require('node:buffer');
const buf = Buffer.from('buffer');
for (const key of buf.keys()) {
console.log(key);
}
// Prints:
// 0
// 1
// 2
// 3
// 4
// 5
buf.lastIndexOf(value[, byteOffset][, encoding])
#
value
<string> | <Buffer> | <Uint8Array> | <integer> 要搜索的内容。byteOffset
<integer> 在buf
中开始搜索的位置。如果为负数,则偏移量从buf
的末尾计算。默认值:buf.length - 1
。encoding
<string> 如果value
是一个字符串,这是用于确定将在buf
中搜索的字符串的二进制表示的编码。默认值:'utf8'
。- 返回:<integer>
buf
中最后一次出现value
的索引,如果buf
不包含value
,则返回-1
。
与 buf.indexOf()
相同,只是找到的是 value
的最后一次出现,而不是第一次出现。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('this buffer is a buffer');
console.log(buf.lastIndexOf('this'));
// Prints: 0
console.log(buf.lastIndexOf('buffer'));
// Prints: 17
console.log(buf.lastIndexOf(Buffer.from('buffer')));
// Prints: 17
console.log(buf.lastIndexOf(97));
// Prints: 15 (97 is the decimal ASCII value for 'a')
console.log(buf.lastIndexOf(Buffer.from('yolo')));
// Prints: -1
console.log(buf.lastIndexOf('buffer', 5));
// Prints: 5
console.log(buf.lastIndexOf('buffer', 4));
// Prints: -1
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');
console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'));
// Prints: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'));
// Prints: 4
const { Buffer } = require('node:buffer');
const buf = Buffer.from('this buffer is a buffer');
console.log(buf.lastIndexOf('this'));
// Prints: 0
console.log(buf.lastIndexOf('buffer'));
// Prints: 17
console.log(buf.lastIndexOf(Buffer.from('buffer')));
// Prints: 17
console.log(buf.lastIndexOf(97));
// Prints: 15 (97 is the decimal ASCII value for 'a')
console.log(buf.lastIndexOf(Buffer.from('yolo')));
// Prints: -1
console.log(buf.lastIndexOf('buffer', 5));
// Prints: 5
console.log(buf.lastIndexOf('buffer', 4));
// Prints: -1
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le');
console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'));
// Prints: 6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'));
// Prints: 4
如果 value
不是字符串、数字或 Buffer
,此方法将抛出 TypeError
。如果 value
是一个数字,它将被强制转换为一个有效的字节值,即 0 到 255 之间的整数。
如果 byteOffset
不是一个数字,它将被强制转换为一个数字。任何强制转换为 NaN
的参数,如 {}
或 undefined
,都会搜索整个缓冲区。此行为与 String.prototype.lastIndexOf()
匹配。
import { Buffer } from 'node:buffer';
const b = Buffer.from('abcdef');
// Passing a value that's a number, but not a valid byte.
// Prints: 2, equivalent to searching for 99 or 'c'.
console.log(b.lastIndexOf(99.9));
console.log(b.lastIndexOf(256 + 99));
// Passing a byteOffset that coerces to NaN.
// Prints: 1, searching the whole buffer.
console.log(b.lastIndexOf('b', undefined));
console.log(b.lastIndexOf('b', {}));
// Passing a byteOffset that coerces to 0.
// Prints: -1, equivalent to passing 0.
console.log(b.lastIndexOf('b', null));
console.log(b.lastIndexOf('b', []));
const { Buffer } = require('node:buffer');
const b = Buffer.from('abcdef');
// Passing a value that's a number, but not a valid byte.
// Prints: 2, equivalent to searching for 99 or 'c'.
console.log(b.lastIndexOf(99.9));
console.log(b.lastIndexOf(256 + 99));
// Passing a byteOffset that coerces to NaN.
// Prints: 1, searching the whole buffer.
console.log(b.lastIndexOf('b', undefined));
console.log(b.lastIndexOf('b', {}));
// Passing a byteOffset that coerces to 0.
// Prints: -1, equivalent to passing 0.
console.log(b.lastIndexOf('b', null));
console.log(b.lastIndexOf('b', []));
如果 value
是一个空字符串或空 Buffer
,将返回 byteOffset
。
buf.length
#
- 类型:<integer>
返回 buf
中的字节数。
import { Buffer } from 'node:buffer';
// Create a `Buffer` and write a shorter string to it using UTF-8.
const buf = Buffer.alloc(1234);
console.log(buf.length);
// Prints: 1234
buf.write('some string', 0, 'utf8');
console.log(buf.length);
// Prints: 1234
const { Buffer } = require('node:buffer');
// Create a `Buffer` and write a shorter string to it using UTF-8.
const buf = Buffer.alloc(1234);
console.log(buf.length);
// Prints: 1234
buf.write('some string', 0, 'utf8');
console.log(buf.length);
// Prints: 1234
buf.readBigUInt64BE([offset])
#
从 buf
的指定 offset
处读取一个无符号、大端序的 64 位整数。
此函数也以 readBigUint64BE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);
console.log(buf.readBigUInt64BE(0));
// Prints: 4294967295n
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);
console.log(buf.readBigUInt64BE(0));
// Prints: 4294967295n
buf.readBigUInt64LE([offset])
#
从 buf
的指定 offset
处读取一个无符号、小端序的 64 位整数。
此函数也以 readBigUint64LE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);
console.log(buf.readBigUInt64LE(0));
// Prints: 18446744069414584320n
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);
console.log(buf.readBigUInt64LE(0));
// Prints: 18446744069414584320n
buf.readDoubleBE([offset])
#
从 buf
的指定 offset
处读取一个 64 位、大端序的双精度浮点数。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
console.log(buf.readDoubleBE(0));
// Prints: 8.20788039913184e-304
const { Buffer } = require('node:buffer');
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
console.log(buf.readDoubleBE(0));
// Prints: 8.20788039913184e-304
buf.readDoubleLE([offset])
#
从 buf
的指定 offset
处读取一个 64 位、小端序的双精度浮点数。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
console.log(buf.readDoubleLE(0));
// Prints: 5.447603722011605e-270
console.log(buf.readDoubleLE(1));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);
console.log(buf.readDoubleLE(0));
// Prints: 5.447603722011605e-270
console.log(buf.readDoubleLE(1));
// Throws ERR_OUT_OF_RANGE.
buf.readFloatBE([offset])
#
从 buf
的指定 offset
处读取一个 32 位、大端序的浮点数。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([1, 2, 3, 4]);
console.log(buf.readFloatBE(0));
// Prints: 2.387939260590663e-38
const { Buffer } = require('node:buffer');
const buf = Buffer.from([1, 2, 3, 4]);
console.log(buf.readFloatBE(0));
// Prints: 2.387939260590663e-38
buf.readFloatLE([offset])
#
从 buf
的指定 offset
处读取一个 32 位、小端序的浮点数。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([1, 2, 3, 4]);
console.log(buf.readFloatLE(0));
// Prints: 1.539989614439558e-36
console.log(buf.readFloatLE(1));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([1, 2, 3, 4]);
console.log(buf.readFloatLE(0));
// Prints: 1.539989614439558e-36
console.log(buf.readFloatLE(1));
// Throws ERR_OUT_OF_RANGE.
buf.readInt8([offset])
#
从 buf
的指定 offset
处读取一个有符号的 8 位整数。
从 Buffer
中读取的整数被解释为二进制补码有符号值。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([-1, 5]);
console.log(buf.readInt8(0));
// Prints: -1
console.log(buf.readInt8(1));
// Prints: 5
console.log(buf.readInt8(2));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([-1, 5]);
console.log(buf.readInt8(0));
// Prints: -1
console.log(buf.readInt8(1));
// Prints: 5
console.log(buf.readInt8(2));
// Throws ERR_OUT_OF_RANGE.
buf.readInt16BE([offset])
#
从 buf
的指定 offset
处读取一个有符号、大端序的 16 位整数。
从 Buffer
中读取的整数被解释为二进制补码有符号值。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0, 5]);
console.log(buf.readInt16BE(0));
// Prints: 5
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0, 5]);
console.log(buf.readInt16BE(0));
// Prints: 5
buf.readInt16LE([offset])
#
从 buf
的指定 offset
处读取一个有符号、小端序的 16 位整数。
从 Buffer
中读取的整数被解释为二进制补码有符号值。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0, 5]);
console.log(buf.readInt16LE(0));
// Prints: 1280
console.log(buf.readInt16LE(1));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0, 5]);
console.log(buf.readInt16LE(0));
// Prints: 1280
console.log(buf.readInt16LE(1));
// Throws ERR_OUT_OF_RANGE.
buf.readInt32BE([offset])
#
从 buf
的指定 offset
处读取一个有符号、大端序的 32 位整数。
从 Buffer
中读取的整数被解释为二进制补码有符号值。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0, 0, 0, 5]);
console.log(buf.readInt32BE(0));
// Prints: 5
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0, 0, 0, 5]);
console.log(buf.readInt32BE(0));
// Prints: 5
buf.readInt32LE([offset])
#
从 buf
的指定 offset
处读取一个有符号、小端序的 32 位整数。
从 Buffer
中读取的整数被解释为二进制补码有符号值。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0, 0, 0, 5]);
console.log(buf.readInt32LE(0));
// Prints: 83886080
console.log(buf.readInt32LE(1));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0, 0, 0, 5]);
console.log(buf.readInt32LE(0));
// Prints: 83886080
console.log(buf.readInt32LE(1));
// Throws ERR_OUT_OF_RANGE.
buf.readIntBE(offset, byteLength)
#
offset
<integer> 开始读取前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要读取的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
从 buf
的指定 offset
处读取 byteLength
个字节,并将结果解释为大端序、二进制补码的有符号值,支持高达 48 位的精度。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readIntBE(0, 6).toString(16));
// Prints: 1234567890ab
console.log(buf.readIntBE(1, 6).toString(16));
// Throws ERR_OUT_OF_RANGE.
console.log(buf.readIntBE(1, 0).toString(16));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readIntBE(0, 6).toString(16));
// Prints: 1234567890ab
console.log(buf.readIntBE(1, 6).toString(16));
// Throws ERR_OUT_OF_RANGE.
console.log(buf.readIntBE(1, 0).toString(16));
// Throws ERR_OUT_OF_RANGE.
buf.readIntLE(offset, byteLength)
#
offset
<integer> 开始读取前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要读取的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
从 buf
的指定 offset
处读取 byteLength
个字节,并将结果解释为小端序、二进制补码的有符号值,支持高达 48 位的精度。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readIntLE(0, 6).toString(16));
// Prints: -546f87a9cbee
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readIntLE(0, 6).toString(16));
// Prints: -546f87a9cbee
buf.readUInt8([offset])
#
从 buf
的指定 offset
处读取一个无符号 8 位整数。
此函数也以 readUint8
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([1, -2]);
console.log(buf.readUInt8(0));
// Prints: 1
console.log(buf.readUInt8(1));
// Prints: 254
console.log(buf.readUInt8(2));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([1, -2]);
console.log(buf.readUInt8(0));
// Prints: 1
console.log(buf.readUInt8(1));
// Prints: 254
console.log(buf.readUInt8(2));
// Throws ERR_OUT_OF_RANGE.
buf.readUInt16BE([offset])
#
从 buf
的指定 offset
处读取一个无符号、大端序的 16 位整数。
此函数也以 readUint16BE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56]);
console.log(buf.readUInt16BE(0).toString(16));
// Prints: 1234
console.log(buf.readUInt16BE(1).toString(16));
// Prints: 3456
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56]);
console.log(buf.readUInt16BE(0).toString(16));
// Prints: 1234
console.log(buf.readUInt16BE(1).toString(16));
// Prints: 3456
buf.readUInt16LE([offset])
#
从 buf
的指定 offset
处读取一个无符号、小端序的 16 位整数。
此函数也以 readUint16LE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56]);
console.log(buf.readUInt16LE(0).toString(16));
// Prints: 3412
console.log(buf.readUInt16LE(1).toString(16));
// Prints: 5634
console.log(buf.readUInt16LE(2).toString(16));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56]);
console.log(buf.readUInt16LE(0).toString(16));
// Prints: 3412
console.log(buf.readUInt16LE(1).toString(16));
// Prints: 5634
console.log(buf.readUInt16LE(2).toString(16));
// Throws ERR_OUT_OF_RANGE.
buf.readUInt32BE([offset])
#
从 buf
的指定 offset
处读取一个无符号、大端序的 32 位整数。
此函数也以 readUint32BE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);
console.log(buf.readUInt32BE(0).toString(16));
// Prints: 12345678
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);
console.log(buf.readUInt32BE(0).toString(16));
// Prints: 12345678
buf.readUInt32LE([offset])
#
从 buf
的指定 offset
处读取一个无符号、小端序的 32 位整数。
此函数也以 readUint32LE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);
console.log(buf.readUInt32LE(0).toString(16));
// Prints: 78563412
console.log(buf.readUInt32LE(1).toString(16));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);
console.log(buf.readUInt32LE(0).toString(16));
// Prints: 78563412
console.log(buf.readUInt32LE(1).toString(16));
// Throws ERR_OUT_OF_RANGE.
buf.readUIntBE(offset, byteLength)
#
offset
<integer> 开始读取前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要读取的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
从 buf
的指定 offset
处读取 byteLength
个字节,并将结果解释为支持高达 48 位精度的无符号大端序整数。
此函数也以 readUintBE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readUIntBE(0, 6).toString(16));
// Prints: 1234567890ab
console.log(buf.readUIntBE(1, 6).toString(16));
// Throws ERR_OUT_OF_RANGE.
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readUIntBE(0, 6).toString(16));
// Prints: 1234567890ab
console.log(buf.readUIntBE(1, 6).toString(16));
// Throws ERR_OUT_OF_RANGE.
buf.readUIntLE(offset, byteLength)
#
offset
<integer> 开始读取前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要读取的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
从 buf
的指定 offset
处读取 byteLength
个字节,并将结果解释为支持高达 48 位精度的无符号小端序整数。
此函数也以 readUintLE
别名提供。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readUIntLE(0, 6).toString(16));
// Prints: ab9078563412
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(buf.readUIntLE(0, 6).toString(16));
// Prints: ab9078563412
buf.subarray([start[, end]])
#
start
<integer> 新Buffer
的起始位置。默认值:0
。end
<integer> 新Buffer
的结束位置(不包括)。默认值:buf.length
。- 返回:<Buffer>
返回一个新的 Buffer
,它引用与原始缓冲区相同的内存,但通过 start
和 end
索引进行了偏移和裁剪。
指定 end
大于 buf.length
将返回与 end
等于 buf.length
相同的结果。
此方法继承自 TypedArray.prototype.subarray()
。
修改新的 Buffer
切片将会修改原始 Buffer
中的内存,因为这两个对象的已分配内存是重叠的。
import { Buffer } from 'node:buffer';
// Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte
// from the original `Buffer`.
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
const buf2 = buf1.subarray(0, 3);
console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: abc
buf1[0] = 33;
console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: !bc
const { Buffer } = require('node:buffer');
// Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte
// from the original `Buffer`.
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
const buf2 = buf1.subarray(0, 3);
console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: abc
buf1[0] = 33;
console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: !bc
指定负数索引会导致切片相对于 buf
的末尾而不是开头生成。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('buffer');
console.log(buf.subarray(-6, -1).toString());
// Prints: buffe
// (Equivalent to buf.subarray(0, 5).)
console.log(buf.subarray(-6, -2).toString());
// Prints: buff
// (Equivalent to buf.subarray(0, 4).)
console.log(buf.subarray(-5, -2).toString());
// Prints: uff
// (Equivalent to buf.subarray(1, 4).)
const { Buffer } = require('node:buffer');
const buf = Buffer.from('buffer');
console.log(buf.subarray(-6, -1).toString());
// Prints: buffe
// (Equivalent to buf.subarray(0, 5).)
console.log(buf.subarray(-6, -2).toString());
// Prints: buff
// (Equivalent to buf.subarray(0, 4).)
console.log(buf.subarray(-5, -2).toString());
// Prints: uff
// (Equivalent to buf.subarray(1, 4).)
buf.slice([start[, end]])
#
start
<integer> 新Buffer
的起始位置。默认值:0
。end
<integer> 新Buffer
的结束位置(不包括)。默认值:buf.length
。- 返回:<Buffer>
buf.subarray
。返回一个新的 Buffer
,它引用与原始缓冲区相同的内存,但通过 start
和 end
索引进行了偏移和裁剪。
此方法与 Buffer
的超类 Uint8Array.prototype.slice()
不兼容。要复制切片,请使用 Uint8Array.prototype.slice()
。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('buffer');
const copiedBuf = Uint8Array.prototype.slice.call(buf);
copiedBuf[0]++;
console.log(copiedBuf.toString());
// Prints: cuffer
console.log(buf.toString());
// Prints: buffer
// With buf.slice(), the original buffer is modified.
const notReallyCopiedBuf = buf.slice();
notReallyCopiedBuf[0]++;
console.log(notReallyCopiedBuf.toString());
// Prints: cuffer
console.log(buf.toString());
// Also prints: cuffer (!)
const { Buffer } = require('node:buffer');
const buf = Buffer.from('buffer');
const copiedBuf = Uint8Array.prototype.slice.call(buf);
copiedBuf[0]++;
console.log(copiedBuf.toString());
// Prints: cuffer
console.log(buf.toString());
// Prints: buffer
// With buf.slice(), the original buffer is modified.
const notReallyCopiedBuf = buf.slice();
notReallyCopiedBuf[0]++;
console.log(notReallyCopiedBuf.toString());
// Prints: cuffer
console.log(buf.toString());
// Also prints: cuffer (!)
buf.swap16()
#
- 返回:<Buffer> 对
buf
的引用。
将 buf
解释为无符号16位整数数组,并就地交换字节序。如果 buf.length
不是2的倍数,则抛出 ERR_INVALID_BUFFER_SIZE
。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);
console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap16();
console.log(buf1);
// Prints: <Buffer 02 01 04 03 06 05 08 07>
const buf2 = Buffer.from([0x1, 0x2, 0x3]);
buf2.swap16();
// Throws ERR_INVALID_BUFFER_SIZE.
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);
console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap16();
console.log(buf1);
// Prints: <Buffer 02 01 04 03 06 05 08 07>
const buf2 = Buffer.from([0x1, 0x2, 0x3]);
buf2.swap16();
// Throws ERR_INVALID_BUFFER_SIZE.
buf.swap16()
的一个便捷用途是执行 UTF-16 小端序和 UTF-16 大端序之间的快速就地转换。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('This is little-endian UTF-16', 'utf16le');
buf.swap16(); // Convert to big-endian UTF-16 text.
const { Buffer } = require('node:buffer');
const buf = Buffer.from('This is little-endian UTF-16', 'utf16le');
buf.swap16(); // Convert to big-endian UTF-16 text.
buf.swap32()
#
- 返回:<Buffer> 对
buf
的引用。
将 buf
解释为无符号32位整数数组,并就地交换字节序。如果 buf.length
不是4的倍数,则抛出 ERR_INVALID_BUFFER_SIZE
。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);
console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap32();
console.log(buf1);
// Prints: <Buffer 04 03 02 01 08 07 06 05>
const buf2 = Buffer.from([0x1, 0x2, 0x3]);
buf2.swap32();
// Throws ERR_INVALID_BUFFER_SIZE.
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);
console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap32();
console.log(buf1);
// Prints: <Buffer 04 03 02 01 08 07 06 05>
const buf2 = Buffer.from([0x1, 0x2, 0x3]);
buf2.swap32();
// Throws ERR_INVALID_BUFFER_SIZE.
buf.swap64()
#
- 返回:<Buffer> 对
buf
的引用。
将 buf
解释为64位数字数组,并就地交换字节序。如果 buf.length
不是8的倍数,则抛出 ERR_INVALID_BUFFER_SIZE
。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);
console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap64();
console.log(buf1);
// Prints: <Buffer 08 07 06 05 04 03 02 01>
const buf2 = Buffer.from([0x1, 0x2, 0x3]);
buf2.swap64();
// Throws ERR_INVALID_BUFFER_SIZE.
const { Buffer } = require('node:buffer');
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8]);
console.log(buf1);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap64();
console.log(buf1);
// Prints: <Buffer 08 07 06 05 04 03 02 01>
const buf2 = Buffer.from([0x1, 0x2, 0x3]);
buf2.swap64();
// Throws ERR_INVALID_BUFFER_SIZE.
buf.toJSON()
#
- 返回:<Object>
返回 buf
的 JSON 表示。当字符串化一个 Buffer
实例时,JSON.stringify()
会隐式调用此函数。
Buffer.from()
接受此方法返回格式的对象。特别是,Buffer.from(buf.toJSON())
的作用类似于 Buffer.from(buf)
。
import { Buffer } from 'node:buffer';
const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);
console.log(json);
// Prints: {"type":"Buffer","data":[1,2,3,4,5]}
const copy = JSON.parse(json, (key, value) => {
return value && value.type === 'Buffer' ?
Buffer.from(value) :
value;
});
console.log(copy);
// Prints: <Buffer 01 02 03 04 05>
const { Buffer } = require('node:buffer');
const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
const json = JSON.stringify(buf);
console.log(json);
// Prints: {"type":"Buffer","data":[1,2,3,4,5]}
const copy = JSON.parse(json, (key, value) => {
return value && value.type === 'Buffer' ?
Buffer.from(value) :
value;
});
console.log(copy);
// Prints: <Buffer 01 02 03 04 05>
buf.toString([encoding[, start[, end]]])
#
encoding
<string> 要使用的字符编码。默认值:'utf8'
。start
<integer> 开始解码的字节偏移量。默认值:0
。end
<integer> 停止解码的字节偏移量(不包含)。默认值:buf.length
。- 返回: <string>
根据 encoding
中指定的字符编码将 buf
解码为字符串。可以传递 start
和 end
来仅解码 buf
的一个子集。
如果 encoding
是 'utf8'
并且输入中的字节序列不是有效的 UTF-8,那么每个无效字节都将被替换为替换字符 U+FFFD
。
字符串实例的最大长度(以 UTF-16 代码单元为单位)可通过 buffer.constants.MAX_STRING_LENGTH
获取。
import { Buffer } from 'node:buffer';
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
const buf2 = Buffer.from('tést');
console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té
const { Buffer } = require('node:buffer');
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
const buf2 = Buffer.from('tést');
console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té
buf.values()
#
- 返回:<Iterator>
创建并返回一个用于 buf
值(字节)的迭代器。当在 for..of
语句中使用 Buffer
时,此函数会自动被调用。
import { Buffer } from 'node:buffer';
const buf = Buffer.from('buffer');
for (const value of buf.values()) {
console.log(value);
}
// Prints:
// 98
// 117
// 102
// 102
// 101
// 114
for (const value of buf) {
console.log(value);
}
// Prints:
// 98
// 117
// 102
// 102
// 101
// 114
const { Buffer } = require('node:buffer');
const buf = Buffer.from('buffer');
for (const value of buf.values()) {
console.log(value);
}
// Prints:
// 98
// 117
// 102
// 102
// 101
// 114
for (const value of buf) {
console.log(value);
}
// Prints:
// 98
// 117
// 102
// 102
// 101
// 114
buf.write(string[, offset[, length]][, encoding])
#
string
<string> 要写入buf
的字符串。offset
<integer> 在开始写入string
之前跳过的字节数。默认值:0
。length
<integer> 要写入的最大字节数(写入的字节数不会超过buf.length - offset
)。默认值:buf.length - offset
。encoding
<string>string
的字符编码。默认值:'utf8'
。- 返回:<integer> 写入的字节数。
根据 encoding
中的字符编码,在 offset
位置将 string
写入 buf
。length
参数是要写入的字节数。如果 buf
没有足够的空间来容纳整个字符串,则只会写入 string
的一部分。但是,不会写入部分编码的字符。
import { Buffer } from 'node:buffer';
const buf = Buffer.alloc(256);
const len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
// Prints: 12 bytes: ½ + ¼ = ¾
const buffer = Buffer.alloc(10);
const length = buffer.write('abcd', 8);
console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`);
// Prints: 2 bytes : ab
const { Buffer } = require('node:buffer');
const buf = Buffer.alloc(256);
const len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
// Prints: 12 bytes: ½ + ¼ = ¾
const buffer = Buffer.alloc(10);
const length = buffer.write('abcd', 8);
console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`);
// Prints: 2 bytes : ab
buf.writeBigInt64BE(value[, offset])
#
value
<bigint> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足:0 <= offset <= buf.length - 8
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。
value
被解释并作为二进制补码有符号整数写入。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(8);
buf.writeBigInt64BE(0x0102030405060708n, 0);
console.log(buf);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(8);
buf.writeBigInt64BE(0x0102030405060708n, 0);
console.log(buf);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
buf.writeBigInt64LE(value[, offset])
#
value
<bigint> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足:0 <= offset <= buf.length - 8
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。
value
被解释并作为二进制补码有符号整数写入。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(8);
buf.writeBigInt64LE(0x0102030405060708n, 0);
console.log(buf);
// Prints: <Buffer 08 07 06 05 04 03 02 01>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(8);
buf.writeBigInt64LE(0x0102030405060708n, 0);
console.log(buf);
// Prints: <Buffer 08 07 06 05 04 03 02 01>
buf.writeBigUInt64BE(value[, offset])
#
value
<bigint> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足:0 <= offset <= buf.length - 8
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。
此函数也可通过别名 writeBigUint64BE
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(8);
buf.writeBigUInt64BE(0xdecafafecacefaden, 0);
console.log(buf);
// Prints: <Buffer de ca fa fe ca ce fa de>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(8);
buf.writeBigUInt64BE(0xdecafafecacefaden, 0);
console.log(buf);
// Prints: <Buffer de ca fa fe ca ce fa de>
buf.writeBigUInt64LE(value[, offset])
#
value
<bigint> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足:0 <= offset <= buf.length - 8
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(8);
buf.writeBigUInt64LE(0xdecafafecacefaden, 0);
console.log(buf);
// Prints: <Buffer de fa ce ca fe fa ca de>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(8);
buf.writeBigUInt64LE(0xdecafafecacefaden, 0);
console.log(buf);
// Prints: <Buffer de fa ce ca fe fa ca de>
此函数也可通过别名 writeBigUint64LE
使用。
buf.writeDoubleBE(value[, offset])
#
value
<number> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 8
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。value
必须是 JavaScript 数字。当 value
不是 JavaScript 数字时,行为未定义。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(8);
buf.writeDoubleBE(123.456, 0);
console.log(buf);
// Prints: <Buffer 40 5e dd 2f 1a 9f be 77>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(8);
buf.writeDoubleBE(123.456, 0);
console.log(buf);
// Prints: <Buffer 40 5e dd 2f 1a 9f be 77>
buf.writeDoubleLE(value[, offset])
#
value
<number> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 8
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。value
必须是 JavaScript 数字。当 value
不是 JavaScript 数字时,行为未定义。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(8);
buf.writeDoubleLE(123.456, 0);
console.log(buf);
// Prints: <Buffer 77 be 9f 1a 2f dd 5e 40>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(8);
buf.writeDoubleLE(123.456, 0);
console.log(buf);
// Prints: <Buffer 77 be 9f 1a 2f dd 5e 40>
buf.writeFloatBE(value[, offset])
#
value
<number> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。当 value
不是 JavaScript 数字时,行为未定义。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeFloatBE(0xcafebabe, 0);
console.log(buf);
// Prints: <Buffer 4f 4a fe bb>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeFloatBE(0xcafebabe, 0);
console.log(buf);
// Prints: <Buffer 4f 4a fe bb>
buf.writeFloatLE(value[, offset])
#
value
<number> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。当 value
不是 JavaScript 数字时,行为未定义。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeFloatLE(0xcafebabe, 0);
console.log(buf);
// Prints: <Buffer bb fe 4a 4f>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeFloatLE(0xcafebabe, 0);
console.log(buf);
// Prints: <Buffer bb fe 4a 4f>
buf.writeInt8(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 1
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的有符号8位整数。当 value
不是有符号8位整数时,行为未定义。
value
被解释并作为二进制补码有符号整数写入。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(2);
buf.writeInt8(2, 0);
buf.writeInt8(-2, 1);
console.log(buf);
// Prints: <Buffer 02 fe>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(2);
buf.writeInt8(2, 0);
buf.writeInt8(-2, 1);
console.log(buf);
// Prints: <Buffer 02 fe>
buf.writeInt16BE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 2
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的有符号16位整数。当 value
不是有符号16位整数时,行为未定义。
value
被解释并作为二进制补码有符号整数写入。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(2);
buf.writeInt16BE(0x0102, 0);
console.log(buf);
// Prints: <Buffer 01 02>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(2);
buf.writeInt16BE(0x0102, 0);
console.log(buf);
// Prints: <Buffer 01 02>
buf.writeInt16LE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 2
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的有符号16位整数。当 value
不是有符号16位整数时,行为未定义。
value
被解释并作为二进制补码有符号整数写入。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(2);
buf.writeInt16LE(0x0304, 0);
console.log(buf);
// Prints: <Buffer 04 03>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(2);
buf.writeInt16LE(0x0304, 0);
console.log(buf);
// Prints: <Buffer 04 03>
buf.writeInt32BE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的有符号32位整数。当 value
不是有符号32位整数时,行为未定义。
value
被解释并作为二进制补码有符号整数写入。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeInt32BE(0x01020304, 0);
console.log(buf);
// Prints: <Buffer 01 02 03 04>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeInt32BE(0x01020304, 0);
console.log(buf);
// Prints: <Buffer 01 02 03 04>
buf.writeInt32LE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的有符号32位整数。当 value
不是有符号32位整数时,行为未定义。
value
被解释并作为二进制补码有符号整数写入。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeInt32LE(0x05060708, 0);
console.log(buf);
// Prints: <Buffer 08 07 06 05>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeInt32LE(0x05060708, 0);
console.log(buf);
// Prints: <Buffer 08 07 06 05>
buf.writeIntBE(value, offset, byteLength)
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要写入的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
的 byteLength
字节写入到 buf
中指定的 offset
位置。支持高达48位的精度。当 value
不是有符号整数时,行为未定义。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(6);
buf.writeIntBE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer 12 34 56 78 90 ab>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(6);
buf.writeIntBE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer 12 34 56 78 90 ab>
buf.writeIntLE(value, offset, byteLength)
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要写入的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
的 byteLength
字节写入到 buf
中指定的 offset
位置。支持高达48位的精度。当 value
不是有符号整数时,行为未定义。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(6);
buf.writeIntLE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer ab 90 78 56 34 12>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(6);
buf.writeIntLE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer ab 90 78 56 34 12>
buf.writeUInt8(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 1
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的无符号8位整数。当 value
不是无符号8位整数时,行为未定义。
此函数也可通过别名 writeUint8
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);
console.log(buf);
// Prints: <Buffer 03 04 23 42>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);
console.log(buf);
// Prints: <Buffer 03 04 23 42>
buf.writeUInt16BE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 2
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的无符号16位整数。当 value
不是无符号16位整数时,行为未定义。
此函数也可通过别名 writeUint16BE
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);
console.log(buf);
// Prints: <Buffer de ad be ef>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);
console.log(buf);
// Prints: <Buffer de ad be ef>
buf.writeUInt16LE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 2
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的无符号16位整数。当 value
不是无符号16位整数时,行为未定义。
此函数也可通过别名 writeUint16LE
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);
console.log(buf);
// Prints: <Buffer ad de ef be>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);
console.log(buf);
// Prints: <Buffer ad de ef be>
buf.writeUInt32BE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的无符号32位整数。当 value
不是无符号32位整数时,行为未定义。
此函数也可通过别名 writeUint32BE
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeUInt32BE(0xfeedface, 0);
console.log(buf);
// Prints: <Buffer fe ed fa ce>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeUInt32BE(0xfeedface, 0);
console.log(buf);
// Prints: <Buffer fe ed fa ce>
buf.writeUInt32LE(value[, offset])
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4
。默认值:0
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
写入到 buf
中指定的 offset
位置。value
必须是有效的无符号32位整数。当 value
不是无符号32位整数时,行为未定义。
此函数也可通过别名 writeUint32LE
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(4);
buf.writeUInt32LE(0xfeedface, 0);
console.log(buf);
// Prints: <Buffer ce fa ed fe>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(4);
buf.writeUInt32LE(0xfeedface, 0);
console.log(buf);
// Prints: <Buffer ce fa ed fe>
buf.writeUIntBE(value, offset, byteLength)
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要写入的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
offset
加上写入的字节数。
以大端序将 value
的 byteLength
字节写入到 buf
中指定的 offset
位置。支持高达48位的精度。当 value
不是无符号整数时,行为未定义。
此函数也可通过别名 writeUintBE
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(6);
buf.writeUIntBE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer 12 34 56 78 90 ab>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(6);
buf.writeUIntBE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer 12 34 56 78 90 ab>
buf.writeUIntLE(value, offset, byteLength)
#
value
<integer> 要写入buf
的数字。offset
<integer> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength
。byteLength
<integer> 要写入的字节数。必须满足0 < byteLength <= 6
。- 返回:<integer>
offset
加上写入的字节数。
以小端序将 value
的 byteLength
字节写入到 buf
中指定的 offset
位置。支持高达48位的精度。当 value
不是无符号整数时,行为未定义。
此函数也可通过别名 writeUintLE
使用。
import { Buffer } from 'node:buffer';
const buf = Buffer.allocUnsafe(6);
buf.writeUIntLE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer ab 90 78 56 34 12>
const { Buffer } = require('node:buffer');
const buf = Buffer.allocUnsafe(6);
buf.writeUIntLE(0x1234567890ab, 0, 6);
console.log(buf);
// Prints: <Buffer ab 90 78 56 34 12>
new Buffer(arrayBuffer[, byteOffset[, length]])
#
arrayBuffer
<ArrayBuffer> | <SharedArrayBuffer> 一个 <ArrayBuffer>、<SharedArrayBuffer> 或 <TypedArray> 的.buffer
属性。byteOffset
<integer> 要暴露的第一个字节的索引。默认值:0
。length
<integer> 要暴露的字节数。默认值:arrayBuffer.byteLength - byteOffset
。
new Buffer(buffer)
#
Buffer.from(buffer)
。buffer
<Buffer> | <Uint8Array> 一个现有的Buffer
或 <Uint8Array>,从中复制数据。
new Buffer(size)
#
size
<integer> 新Buffer
的期望长度。
参见 Buffer.alloc()
和 Buffer.allocUnsafe()
。此构造函数变体等同于 Buffer.alloc()
。
new Buffer(string[, encoding])
#
Buffer.from(string[, encoding])
。类:File
#
- 继承自:<Blob>
<File> 提供有关文件的信息。
new buffer.File(sources, fileName[, options])
#
sources
<string[]> | <ArrayBuffer[]> | <TypedArray[]> | <DataView[]> | <Blob[]> | <File[]> 一个由字符串、<ArrayBuffer>、<TypedArray>、<DataView>、<File> 或 <Blob> 对象组成的数组,或这些对象的任意混合,它们将被存储在File
中。fileName
<string> 文件名。options
<Object>
node:buffer
模块 API#
虽然 Buffer
对象可作为全局对象使用,但还有一些与 Buffer
相关的附加 API 只能通过 node:buffer
模块(使用 require('node:buffer')
访问)获得。
buffer.atob(data)
#
Buffer.from(data, 'base64')
。data
<any> Base64 编码的输入字符串。
将 Base64 编码的数据字符串解码为字节,并使用 Latin-1 (ISO-8859-1) 将这些字节编码为字符串。
data
可以是任何可以被强制转换为字符串的 JavaScript 值。
此函数仅为与旧版 Web 平台 API 兼容而提供,不应在任何新代码中使用,因为它们使用字符串来表示二进制数据,并且早于 JavaScript 中引入类型化数组。对于使用 Node.js API 运行的代码,应使用 Buffer.from(str, 'base64')
和 buf.toString('base64')
在 base64 编码的字符串和二进制数据之间进行转换。
buffer.btoa(data)
#
buf.toString('base64')
。data
<any> 一个 ASCII (Latin1) 字符串。
使用 Latin-1 (ISO-8859) 将字符串解码为字节,并使用 Base64 将这些字节编码为字符串。
data
可以是任何可以被强制转换为字符串的 JavaScript 值。
此函数仅为与旧版 Web 平台 API 兼容而提供,不应在任何新代码中使用,因为它们使用字符串来表示二进制数据,并且早于 JavaScript 中引入类型化数组。对于使用 Node.js API 运行的代码,应使用 Buffer.from(str, 'base64')
和 buf.toString('base64')
在 base64 编码的字符串和二进制数据之间进行转换。
buffer.isAscii(input)
#
input
<Buffer> | <ArrayBuffer> | <TypedArray> 要验证的输入。- 返回:<boolean>
如果 input
仅包含有效的 ASCII 编码数据,则此函数返回 true
,包括 input
为空的情况。
如果 input
是一个已分离的数组缓冲区,则抛出错误。
buffer.isUtf8(input)
#
input
<Buffer> | <ArrayBuffer> | <TypedArray> 要验证的输入。- 返回:<boolean>
如果 input
仅包含有效的 UTF-8 编码数据,则此函数返回 true
,包括 input
为空的情况。
如果 input
是一个已分离的数组缓冲区,则抛出错误。
buffer.INSPECT_MAX_BYTES
#
- 类型:<integer> 默认值:
50
返回调用 buf.inspect()
时将返回的最大字节数。这可以被用户模块覆盖。有关 buf.inspect()
行为的更多详细信息,请参见 util.inspect()
。
buffer.resolveObjectURL(id)
#
将一个 'blob:nodedata:...'
解析为先前通过调用 URL.createObjectURL()
注册的关联 <Blob> 对象。
buffer.transcode(source, fromEnc, toEnc)
#
source
<Buffer> | <Uint8Array> 一个Buffer
或Uint8Array
实例。fromEnc
<string> 当前编码。toEnc
<string> 目标编码。- 返回:<Buffer>
将给定的 Buffer
或 Uint8Array
实例从一种字符编码重新编码为另一种。返回一个新的 Buffer
实例。
如果 fromEnc
或 toEnc
指定了无效的字符编码,或者不允许从 fromEnc
转换为 toEnc
,则抛出错误。
buffer.transcode()
支持的编码有:'ascii'
、'utf8'
、'utf16le'
、'ucs2'
、'latin1'
和 'binary'
。
如果给定的字节序列无法在目标编码中充分表示,转码过程将使用替换字符。例如:
import { Buffer, transcode } from 'node:buffer';
const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii');
console.log(newBuf.toString('ascii'));
// Prints: '?'
const { Buffer, transcode } = require('node:buffer');
const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii');
console.log(newBuf.toString('ascii'));
// Prints: '?'
因为欧元符号(€
)在 US-ASCII 中无法表示,所以在转码后的 Buffer
中它被替换为 ?
。
Buffer 常量#
buffer.constants.MAX_LENGTH
#
- 类型:<integer> 单个
Buffer
实例允许的最大大小。
在 32 位架构上,此值当前为 230 - 1(约 1 GiB)。
在 64 位架构上,此值当前为 253 - 1(约 8 PiB)。
它在底层反映了 v8::TypedArray::kMaxLength
。
此值也可用作 buffer.kMaxLength
。
Buffer.from()
、Buffer.alloc()
和 Buffer.allocUnsafe()
#
在 6.0.0 之前的 Node.js 版本中,Buffer
实例是使用 Buffer
构造函数创建的,该函数会根据提供的参数以不同方式分配返回的 Buffer
。
- 将数字作为第一个参数传递给
Buffer()
(例如new Buffer(10)
)会分配一个指定大小的新Buffer
对象。在 Node.js 8.0.0 之前,为此类Buffer
实例分配的内存是未初始化的,并且可能包含敏感数据。此类Buffer
实例必须随后通过使用buf.fill(0)
或在从Buffer
读取数据之前写入整个Buffer
来进行初始化。虽然这种行为是有意为了提高性能,但开发经验表明,在创建快速但未初始化的Buffer
和创建较慢但更安全的Buffer
之间需要更明确的区分。自 Node.js 8.0.0 起,Buffer(num)
和new Buffer(num)
返回一个带有初始化内存的Buffer
。 - 将字符串、数组或
Buffer
作为第一个参数传递会将传递对象的数据复制到Buffer
中。 - 传递一个 <ArrayBuffer> 或 <SharedArrayBuffer> 会返回一个与给定数组缓冲区共享已分配内存的
Buffer
。
由于 new Buffer()
的行为根据第一个参数的类型而有所不同,因此当未执行参数验证或 Buffer
初始化时,可能会无意中给应用程序带来安全性和可靠性问题。
例如,如果攻击者可以使应用程序在期望字符串的地方接收到一个数字,应用程序可能会调用 new Buffer(100)
而不是 new Buffer("100")
,导致它分配一个 100 字节的缓冲区,而不是分配一个内容为 "100"
的 3 字节缓冲区。这通常可以通过 JSON API 调用实现。由于 JSON 区分数字和字符串类型,它允许在编写不当且未充分验证其输入的应用程序中注入数字,而该应用程序可能期望总是接收到一个字符串。在 Node.js 8.0.0 之前,100 字节的缓冲区可能包含任意已存在的内存数据,因此可能被用来向远程攻击者暴露内存中的秘密。自 Node.js 8.0.0 起,内存暴露不会发生,因为数据是零填充的。但是,其他攻击仍然可能发生,例如导致服务器分配非常大的缓冲区,从而导致性能下降或因内存耗尽而崩溃。
为了使 Buffer
实例的创建更加可靠且不易出错,各种形式的 new Buffer()
构造函数已被弃用,并由单独的 Buffer.from()
、Buffer.alloc()
和 Buffer.allocUnsafe()
方法取代。
开发者应将所有现有的 new Buffer()
构造函数用法迁移到这些新的 API 之一。
Buffer.from(array)
返回一个新的Buffer
,其中包含所提供八位字节的副本。Buffer.from(arrayBuffer[, byteOffset[, length]])
返回一个新的Buffer
,它与给定的 <ArrayBuffer> 共享相同的已分配内存。Buffer.from(buffer)
返回一个新的Buffer
,其中包含给定Buffer
内容的副本。Buffer.from(string[, encoding])
返回一个新的Buffer
,其中包含所提供字符串的副本。Buffer.alloc(size[, fill[, encoding]])
返回一个指定大小的新的已初始化Buffer
。此方法比Buffer.allocUnsafe(size)
慢,但保证新创建的Buffer
实例绝不包含可能敏感的旧数据。如果size
不是数字,则会抛出TypeError
。Buffer.allocUnsafe(size)
和Buffer.allocUnsafeSlow(size)
各返回一个指定size
的新的未初始化Buffer
。因为Buffer
是未初始化的,所以分配的内存段可能包含可能敏感的旧数据。
由 Buffer.allocUnsafe()
、Buffer.from(string)
、Buffer.concat()
和 Buffer.from(array)
返回的 Buffer
实例,如果 size
小于或等于 Buffer.poolSize
的一半,可能会从共享的内部内存池中分配。由 Buffer.allocUnsafeSlow()
返回的实例从不使用共享的内部内存池。
--zero-fill-buffers
命令行选项#
Node.js 可以使用 --zero-fill-buffers
命令行选项启动,以使所有新分配的 Buffer
实例在创建时默认进行零填充。如果没有该选项,用 Buffer.allocUnsafe()
和 Buffer.allocUnsafeSlow()
创建的缓冲区不会进行零填充。使用此标志可能会对性能产生可衡量的负面影响。仅在必要时使用 --zero-fill-buffers
选项,以强制新分配的 Buffer
实例不能包含可能敏感的旧数据。
$ node --zero-fill-buffers
> Buffer.allocUnsafe(5);
<Buffer 00 00 00 00 00>
是什么让 Buffer.allocUnsafe()
和 Buffer.allocUnsafeSlow()
“不安全”?#
当调用 Buffer.allocUnsafe()
和 Buffer.allocUnsafeSlow()
时,分配的内存段是未初始化的(它没有被清零)。虽然这种设计使得内存分配非常快,但分配的内存段可能包含可能敏感的旧数据。使用由 Buffer.allocUnsafe()
创建的 Buffer
而没有完全覆盖内存,可能会在读取 Buffer
内存时导致这些旧数据被泄露。
虽然使用 Buffer.allocUnsafe()
有明显的性能优势,但必须格外小心,以避免给应用程序引入安全漏洞。