Buffer
源代码: lib/buffer.js
Buffer 对象用于表示固定长度的字节序列。许多 Node.js API 都支持 Buffer。
Buffer 类是 JavaScript 的 Uint8Array 类的子类，并通过涵盖更多用例的方法对其进行了扩展。Node.js API 也可以在任何支持 Buffer 的地方接受普通的 Uint8Array。
虽然 Buffer 类可在全局范围内使用，但仍建议通过导入或 require 语句显式引用它。
js
import { Buffer } from 'node:buffer'
// 创建一个长度为 10 的、填充为零的 Buffer。
const buf1 = Buffer.alloc(10)
// 创建一个长度为 10 的 Buffer，
// 用所有值为 `1` 的字节填充。
const buf2 = Buffer.alloc(10, 1)
// 创建一个长度为 10 的未初始化的缓冲区。
// 这比调用 Buffer.alloc() 更快，但返回的
// Buffer 实例可能包含需要使用 fill()、write() 或其他填充 Buffer 内容的函数覆盖的旧数据。
const buf3 = Buffer.allocUnsafe(10)
// 创建一个包含字节 [1, 2, 3] 的 Buffer。
const buf4 = Buffer.from([1, 2, 3])
// 创建一个包含字节 [1, 1, 1, 1] 的 Buffer – 使用 `(value & 255)` 将所有条目截断以适合 0-255 的范围。
const buf5 = Buffer.from([257, 257.5, -255, '1'])
// 创建一个包含字符串 'tést' 的 UTF-8 编码字节的 Buffer：
// [0x74, 0xc3, 0xa9, 0x73, 0x74]（十六进制表示法）
// [116, 195, 169, 115, 116]（十进制表示法）
const buf6 = Buffer.from('tést')
// 创建一个包含 Latin-1 字节 [0x74, 0xe9, 0x73, 0x74] 的 Buffer。
const buf7 = Buffer.from('tést', 'latin1')js
const { Buffer } = require('node:buffer')
// 创建一个长度为 10 的、填充为零的 Buffer。
const buf1 = Buffer.alloc(10)
// 创建一个长度为 10 的 Buffer，
// 用所有值为 `1` 的字节填充。
const buf2 = Buffer.alloc(10, 1)
// 创建一个长度为 10 的未初始化的缓冲区。
// 这比调用 Buffer.alloc() 更快，但返回的
// Buffer 实例可能包含需要使用 fill()、write() 或其他填充 Buffer 内容的函数覆盖的旧数据。
const buf3 = Buffer.allocUnsafe(10)
// 创建一个包含字节 [1, 2, 3] 的 Buffer。
const buf4 = Buffer.from([1, 2, 3])
// 创建一个包含字节 [1, 1, 1, 1] 的 Buffer – 使用 `(value & 255)` 将所有条目截断以适合 0-255 的范围。
const buf5 = Buffer.from([257, 257.5, -255, '1'])
// 创建一个包含字符串 'tést' 的 UTF-8 编码字节的 Buffer：
// [0x74, 0xc3, 0xa9, 0x73, 0x74]（十六进制表示法）
// [116, 195, 169, 115, 116]（十进制表示法）
const buf6 = Buffer.from('tést')
// 创建一个包含 Latin-1 字节 [0x74, 0xe9, 0x73, 0x74] 的 Buffer。
const buf7 = Buffer.from('tést', 'latin1')缓冲区和字符编码
[历史]
| 版本 | 变更 |
|---|---|
| v15.7.0, v14.18.0 | 引入 base64url 编码。 |
| v6.4.0 | 引入 latin1 作为 binary 的别名。 |
| v5.0.0 | 删除了已弃用的 raw 和 raws 编码。 |
在 Buffer 和字符串之间转换时，可以指定字符编码。如果未指定字符编码，则将使用 UTF-8 作为默认编码。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('hello world', 'utf8')
console.log(buf.toString('hex'))
// 输出：68656c6c6f20776f726c64
console.log(buf.toString('base64'))
// 输出：aGVsbG8gd29ybGQ=
console.log(Buffer.from('fhqwhgads', 'utf8'))
// 输出：<Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'))
// 输出：<Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('hello world', 'utf8')
console.log(buf.toString('hex'))
// 输出：68656c6c6f20776f726c64
console.log(buf.toString('base64'))
// 输出：aGVsbG8gd29ybGQ=
console.log(Buffer.from('fhqwhgads', 'utf8'))
// 输出：<Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'))
// 输出：<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。这是默认字符编码。当将Buffer解码为不完全包含有效 UTF-8 数据的字符串时，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'：base64url 编码，如 RFC 4648，第 5 节 中所指定。从字符串创建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 用于指代不支持代码点大于 U+FFFF 的 UTF-16 变体。在 Node.js 中，始终支持这些代码点。
js
import { Buffer } from 'node:buffer'
Buffer.from('1ag123', 'hex')
// 输出 <Buffer 1a>，在遇到第一个非十六进制值 ('g') 时数据被截断。
Buffer.from('1a7', 'hex')
// 输出 <Buffer 1a>，在数据以单个数字 ('7') 结尾时数据被截断。
Buffer.from('1634', 'hex')
// 输出 <Buffer 16 34>，所有数据都被表示。js
const { Buffer } = require('node:buffer')
Buffer.from('1ag123', 'hex')
// 输出 <Buffer 1a>，在遇到第一个非十六进制值 ('g') 时数据被截断。
Buffer.from('1a7', 'hex')
// 输出 <Buffer 1a>，在数据以单个数字 ('7') 结尾时数据被截断。
Buffer.from('1634', 'hex')
// 输出 <Buffer 16 34>，所有数据都被表示。现代 Web 浏览器遵循 WHATWG 编码标准，该标准将 'latin1' 和 'ISO-8859-1' 都作为 'win-1252' 的别名。这意味着，在执行类似 http.get() 的操作时，如果返回的字符集是 WHATWG 规范中列出的字符集之一，则服务器可能实际返回了 'win-1252' 编码的数据，并且使用 'latin1' 编码可能会错误地解码字符。
缓冲区和类型化数组
[历史]
| 版本 | 变更 |
|---|---|
| v3.0.0 | Buffer 类现在继承自 Uint8Array。 |
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的内容，将其解释为整数数组，而不是目标类型的字节序列。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([1, 2, 3, 4])
const uint32array = new Uint32Array(buf)
console.log(uint32array)
// 输出：Uint32Array(4) [ 1, 2, 3, 4 ]js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([1, 2, 3, 4])
const uint32array = new Uint32Array(buf)
console.log(uint32array)
// 输出：Uint32Array(4) [ 1, 2, 3, 4 ]- 传递
Buffer的底层ArrayBuffer将创建一个与Buffer共享其内存的TypedArray。
js
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)
// 输出：Uint16Array(5) [ 104, 101, 108, 108, 111 ]js
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)
// 输出：Uint16Array(5) [ 104, 101, 108, 108, 111 ]可以使用 TypedArray 对象的 .buffer 属性以相同的方式创建一个新的 Buffer，该 Buffer 与 TypedArray 实例共享相同的已分配内存。在此上下文中，Buffer.from() 的行为类似于 new Uint8Array()。
js
import { Buffer } from 'node:buffer'
const arr = new Uint16Array(2)
arr[0] = 5000
arr[1] = 4000
// 复制 `arr` 的内容。
const buf1 = Buffer.from(arr)
// 与 `arr` 共享内存。
const buf2 = Buffer.from(arr.buffer)
console.log(buf1)
// 输出：<Buffer 88 a0>
console.log(buf2)
// 输出：<Buffer 88 13 a0 0f>
arr[1] = 6000
console.log(buf1)
// 输出：<Buffer 88 a0>
console.log(buf2)
// 输出：<Buffer 88 13 70 17>js
const { Buffer } = require('node:buffer')
const arr = new Uint16Array(2)
arr[0] = 5000
arr[1] = 4000
// 复制 `arr` 的内容。
const buf1 = Buffer.from(arr)
// 与 `arr` 共享内存。
const buf2 = Buffer.from(arr.buffer)
console.log(buf1)
// 输出：<Buffer 88 a0>
console.log(buf2)
// 输出：<Buffer 88 13 a0 0f>
arr[1] = 6000
console.log(buf1)
// 输出：<Buffer 88 a0>
console.log(buf2)
// 输出：<Buffer 88 13 70 17>使用 TypedArray 的 .buffer 创建 Buffer 时，可以通过传递 byteOffset 和 length 参数来仅使用底层 ArrayBuffer 的一部分。
js
import { Buffer } from 'node:buffer'
const arr = new Uint16Array(20)
const buf = Buffer.from(arr.buffer, 0, 16)
console.log(buf.length)
// 输出：16js
const { Buffer } = require('node:buffer')
const arr = new Uint16Array(20)
const buf = Buffer.from(arr.buffer, 0, 16)
console.log(buf.length)
// 输出：16Buffer.from() 和 TypedArray.from() 具有不同的签名和实现。具体来说，TypedArray 变体接受第二个参数，该参数是一个映射函数，该函数在类型化数组的每个元素上调用：
TypedArray.from(source[, mapFn[, thisArg]])
但是，Buffer.from() 方法不支持使用映射函数：
Buffer.from(array)Buffer.from(buffer)Buffer.from(arrayBuffer[, byteOffset[, length]])Buffer.from(string[, encoding])
缓冲区和迭代
可以使用 for..of 语法迭代 Buffer 实例：
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([1, 2, 3])
for (const b of buf) {
console.log(b)
}
// 输出：
// 1
// 2
// 3js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([1, 2, 3])
for (const b of buf) {
console.log(b)
}
// 输出：
// 1
// 2
// 3此外，可以使用 buf.values()、buf.keys() 和 buf.entries() 方法创建迭代器。
类：Blob
[历史]
| 版本 | 变更 |
|---|---|
| v18.0.0, v16.17.0 | 不再是实验性功能。 |
| v15.7.0, v14.18.0 | 新增于：v15.7.0, v14.18.0 |
Blob 封装了不可变的原始数据，可以在多个工作线程之间安全共享。
new buffer.Blob([sources[, options]])
[历史]
| 版本 | 变更 |
|---|---|
| v16.7.0 | 添加了标准的 endings 选项来替换换行符，并移除了非标准的 encoding 选项。 |
| v15.7.0, v14.18.0 | 新增于：v15.7.0, v14.18.0 |
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()
新增于：v15.7.0, v14.18.0
- 返回值： <Promise>
返回一个 Promise，该 Promise 解析为包含 Blob 数据副本的 <ArrayBuffer>。
blob.bytes()
新增于：v22.3.0, v20.16.0
blob.bytes() 方法返回 Blob 对象的字节，作为一个 Promise\<Uint8Array\>。
js
const blob = new Blob(['hello'])
blob.bytes().then(bytes => {
console.log(bytes) // 输出：Uint8Array(5) [ 104, 101, 108, 108, 111 ]
})blob.size
新增于：v15.7.0, v14.18.0
Blob 的总大小（以字节为单位）。
blob.slice([start[, end[, type]]])
新增于：v15.7.0, v14.18.0
创建一个新的 Blob，包含该 Blob 对象数据的一个子集。原始 Blob 不会被更改。
blob.stream()
新增于：v16.7.0
- 返回值：
<ReadableStream>
返回一个新的 ReadableStream，允许读取 Blob 的内容。
blob.text()
新增于：v15.7.0, v14.18.0
- 返回值：
<Promise>
返回一个 Promise，其结果为 Blob 内容解码后的 UTF-8 字符串。
blob.type
新增于：v15.7.0, v14.18.0
- 类型：
<string>
Blob 的内容类型。
Blob 对象和 MessageChannel
一旦创建了 <Blob> 对象，它就可以通过 MessagePort 发送到多个目的地，而无需传输或立即复制数据。只有当调用 arrayBuffer() 或 text() 方法时，才会复制 Blob 中包含的数据。
js
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)
// 发送后，Blob 仍然可用。
blob.text().then(console.log)js
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)
// 发送后，Blob 仍然可用。
blob.text().then(console.log)类: Buffer
Buffer 类是用于直接处理二进制数据的全局类型。它可以通过多种方式构造。
静态方法: Buffer.alloc(size[, fill[, encoding]])
[历史]
| 版本 | 变更 |
|---|---|
| v20.0.0 | 对无效输入参数抛出 ERR_INVALID_ARG_TYPE 或 ERR_OUT_OF_RANGE，而不是 ERR_INVALID_ARG_VALUE。 |
| v15.0.0 | 对无效输入参数抛出 ERR_INVALID_ARG_VALUE，而不是 ERR_INVALID_OPT_VALUE。 |
| v10.0.0 | 尝试用零长度缓冲区填充非零长度缓冲区会触发抛出异常。 |
| v10.0.0 | 为 fill 指定无效字符串会触发抛出异常。 |
| v8.9.3 | 为 fill 指定无效字符串现在会导致零填充缓冲区。 |
| v5.10.0 | 新增于：v5.10.0 |
size<整数> 新Buffer的所需长度。fill<字符串> | <Buffer> | <Uint8Array> | <整数> 用于预填充新Buffer的值。默认值：0。encoding<字符串> 如果fill是字符串，则为其编码。默认值：'utf8'。- 返回值: <Buffer>
分配一个大小为 size 字节的新 Buffer。如果 fill 未定义，则 Buffer 将被零填充。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.alloc(5)
console.log(buf)
// 输出：<Buffer 00 00 00 00 00>js
const { Buffer } = require('node:buffer')
const buf = Buffer.alloc(5)
console.log(buf)
// 输出：<Buffer 00 00 00 00 00>如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0，则会抛出 ERR_OUT_OF_RANGE 错误。
如果指定了 fill，则将通过调用 buf.fill(fill) 来初始化已分配的 Buffer。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.alloc(5, 'a')
console.log(buf)
// 输出：<Buffer 61 61 61 61 61>js
const { Buffer } = require('node:buffer')
const buf = Buffer.alloc(5, 'a')
console.log(buf)
// 输出：<Buffer 61 61 61 61 61>如果同时指定了 fill 和 encoding，则将通过调用 buf.fill(fill, encoding) 来初始化已分配的 Buffer。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64')
console.log(buf)
// 输出：<Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>js
const { Buffer } = require('node:buffer')
const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64')
console.log(buf)
// 输出：<Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>调用 Buffer.alloc() 的速度可能会比另一种方法 Buffer.allocUnsafe() 明显慢一些，但它可以确保新创建的 Buffer 实例内容绝不会包含来自先前分配的敏感数据，包括可能未为 Buffer 分配的数据。
如果 size 不是数字，则会抛出 TypeError。
静态方法: Buffer.allocUnsafe(size)
[历史]
| 版本 | 变更 |
|---|---|
| v20.0.0 | 对无效输入参数抛出 ERR_INVALID_ARG_TYPE 或 ERR_OUT_OF_RANGE，而不是 ERR_INVALID_ARG_VALUE。 |
| v15.0.0 | 对无效输入参数抛出 ERR_INVALID_ARG_VALUE，而不是 ERR_INVALID_OPT_VALUE。 |
| v7.0.0 | 传递负数 size 现在将抛出错误。 |
| v5.10.0 | v5.10.0 版本中添加 |
分配一个大小为 size 字节的新 Buffer。如果 size 大于 buffer.constants.MAX_LENGTH 或小于 0，则抛出 ERR_OUT_OF_RANGE 错误。
以这种方式创建的 Buffer 实例的基础内存未初始化。新创建的 Buffer 的内容未知，并且可能包含敏感数据。使用 Buffer.alloc() 来用零初始化 Buffer 实例。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(10)
console.log(buf)
// 打印 (内容可能不同): <Buffer a0 8b 28 3f 01 00 00 00 50 32>
buf.fill(0)
console.log(buf)
// 打印: <Buffer 00 00 00 00 00 00 00 00 00 00>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(10)
console.log(buf)
// 打印 (内容可能不同): <Buffer a0 8b 28 3f 01 00 00 00 50 32>
buf.fill(0)
console.log(buf)
// 打印: <Buffer 00 00 00 00 00 00 00 00 00 00>如果 size 不是数字，则会抛出 TypeError。
Buffer 模块预先分配一个大小为 Buffer.poolSize 的内部 Buffer 实例，该实例用作使用 Buffer.allocUnsafe()、Buffer.from(array)、Buffer.from(string) 和 Buffer.concat() 创建的新 Buffer 实例的快速分配池，仅当 size 小于 Buffer.poolSize \>\>\> 1（Buffer.poolSize 除以二的向下取整）时。
使用此预分配的内部内存池是调用 Buffer.alloc(size, fill) 与 Buffer.allocUnsafe(size).fill(fill) 之间的关键区别。具体来说，Buffer.alloc(size, fill) 永远不会使用内部 Buffer 池，而 Buffer.allocUnsafe(size).fill(fill) 将使用内部 Buffer 池，如果 size 小于或等于 Buffer.poolSize 的一半。这种差异很细微，但在应用程序需要 Buffer.allocUnsafe() 提供的额外性能时可能很重要。
静态方法：Buffer.allocUnsafeSlow(size)
[历史]
| 版本 | 变更 |
|---|---|
| v20.0.0 | 对于无效的输入参数，抛出 ERR_INVALID_ARG_TYPE 或 ERR_OUT_OF_RANGE，而不是 ERR_INVALID_ARG_VALUE。 |
| v15.0.0 | 对于无效的输入参数，抛出 ERR_INVALID_ARG_VALUE，而不是 ERR_INVALID_OPT_VALUE。 |
| v5.12.0 | v5.12.0 中添加 |
分配一个大小为 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 实例，然后复制相关的位。
js
import { Buffer } from 'node:buffer'
// 需要保留一些小的内存块。
const store = []
socket.on('readable', () => {
let data
while (null !== (data = readable.read())) {
// 为保留的数据分配内存。
const sb = Buffer.allocUnsafeSlow(10)
// 将数据复制到新的分配中。
data.copy(sb, 0, 0, 10)
store.push(sb)
}
})js
const { Buffer } = require('node:buffer')
// 需要保留一些小的内存块。
const store = []
socket.on('readable', () => {
let data
while (null !== (data = readable.read())) {
// 为保留的数据分配内存。
const sb = Buffer.allocUnsafeSlow(10)
// 将数据复制到新的分配中。
data.copy(sb, 0, 0, 10)
store.push(sb)
}
})如果 size 不是数字，则会抛出 TypeError。
静态方法: Buffer.byteLength(string[, encoding])
[历史]
| 版本 | 变更 |
|---|---|
| v7.0.0 | 传递无效输入现在将抛出错误。 |
| v5.10.0 | string 参数现在可以是任何 TypedArray、DataView 或 ArrayBuffer。 |
| v0.1.90 | 新增于: v0.1.90 |
string<字符串> | <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <SharedArrayBuffer> 要计算长度的值。encoding<字符串> 如果string是字符串，则这是其编码。默认值:'utf8'。- 返回值: <整数>
string中包含的字节数。
使用 encoding 编码时返回字符串的字节长度。这与 String.prototype.length 不同，后者不考虑用于将字符串转换为字节的编码。
对于 'base64'、'base64url' 和 'hex'，此函数假定输入有效。对于包含非 base64/十六进制编码数据（例如空格）的字符串，返回值可能大于由字符串创建的 Buffer 的长度。
js
import { Buffer } from 'node:buffer'
const str = '\u00bd + \u00bc = \u00be'
console.log(`${str}: ${str.length} characters, ` + `${Buffer.byteLength(str, 'utf8')} bytes`)
// 输出：½ + ¼ = ¾: 9 characters, 12 bytesjs
const { Buffer } = require('node:buffer')
const str = '\u00bd + \u00bc = \u00be'
console.log(`${str}: ${str.length} characters, ` + `${Buffer.byteLength(str, 'utf8')} bytes`)
// 输出：½ + ¼ = ¾: 9 characters, 12 bytes当 string 是 Buffer/DataView/TypedArray/ArrayBuffer/SharedArrayBuffer 时，将返回 .byteLength 报告的字节长度。
静态方法：Buffer.compare(buf1, buf2)
[历史]
| 版本 | 变更 |
|---|---|
| v8.0.0 | 参数现在可以是 Uint8Array。 |
| v0.11.13 | 新增于：v0.11.13 |
buf1<Buffer> | <Uint8Array>buf2<Buffer> | <Uint8Array>- 返回值：<整数>
-1、0或1之一，取决于比较的结果。详情请参见buf.compare()。
比较 buf1 和 buf2，通常用于对 Buffer 实例数组进行排序。这等效于调用 buf1.compare(buf2)。
js
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))
// 输出： [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (此结果等于：[buf2, buf1]。)js
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))
// 输出： [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (此结果等于：[buf2, buf1]。)静态方法：Buffer.concat(list[, totalLength])
[历史]
| 版本 | 变更 |
|---|---|
| v8.0.0 | list 的元素现在可以是 Uint8Array。 |
| v0.7.11 | 在 v0.7.11 中添加 |
list<Buffer[]> | <Uint8Array[]> 要连接的Buffer或Uint8Array实例列表。totalLength<整数> 连接后list中Buffer实例的总长度。- 返回值: <Buffer>
返回一个新的 Buffer，它是将 list 中所有 Buffer 实例连接在一起的结果。
如果列表中没有项目，或者 totalLength 为 0，则返回一个新的零长度 Buffer。
如果没有提供 totalLength，则通过添加 list 中 Buffer 实例的长度来计算它。
如果提供了 totalLength，则将其强制转换为无符号整数。如果 list 中 Buffer 的组合长度超过 totalLength，则结果将被截断为 totalLength。如果 list 中 Buffer 的组合长度小于 totalLength，则剩余空间将填充零。
js
import { Buffer } from 'node:buffer'
// 从三个 `Buffer` 实例的列表创建一个单个 `Buffer`。
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)
// 输出：42
const bufA = Buffer.concat([buf1, buf2, buf3], totalLength)
console.log(bufA)
// 输出：<Buffer 00 00 00 00 ...>
console.log(bufA.length)
// 输出：42js
const { Buffer } = require('node:buffer')
// 从三个 `Buffer` 实例的列表创建一个单个 `Buffer`。
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)
// 输出：42
const bufA = Buffer.concat([buf1, buf2, buf3], totalLength)
console.log(bufA)
// 输出：<Buffer 00 00 00 00 ...>
console.log(bufA.length)
// 输出：42Buffer.concat() 也可能像 Buffer.allocUnsafe() 一样使用内部 Buffer 池。
静态方法: Buffer.copyBytesFrom(view[, offset[, length]])
新增于: v19.8.0, v18.16.0
view<TypedArray> 要复制的 <TypedArray>。offset<整数>view中的起始偏移量。默认值:0。length<整数> 要从view复制的元素数量。默认值:view.length - offset。- 返回值: <Buffer>
将 view 的底层内存复制到一个新的 Buffer 中。
js
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)
新增于：v5.10.0
array<integer[]>- 返回值：<Buffer>
使用 0 – 255 范围内的字节 array 分配一个新的 Buffer。超出该范围的数组条目将被截断以适应该范围。
js
import { Buffer } from 'node:buffer'
// 创建一个新的 Buffer，包含字符串 'buffer' 的 UTF-8 字节。
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72])js
const { Buffer } = require('node:buffer')
// 创建一个新的 Buffer，包含字符串 'buffer' 的 UTF-8 字节。
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]])
新增于: v5.10.0
arrayBuffer<ArrayBuffer> | <SharedArrayBuffer> 一个ArrayBuffer，SharedArrayBuffer，例如TypedArray的.buffer属性。byteOffset<整数> 要公开的第一个字节的索引。默认值:0。length<整数> 要公开的字节数。默认值:arrayBuffer.byteLength - byteOffset。- 返回值: <Buffer>
这会创建一个 ArrayBuffer 的视图，而不会复制底层内存。例如，当传递对 TypedArray 实例的 .buffer 属性的引用时，新创建的 Buffer 将与 TypedArray 的底层 ArrayBuffer 共享相同的已分配内存。
js
import { Buffer } from 'node:buffer'
const arr = new Uint16Array(2)
arr[0] = 5000
arr[1] = 4000
// 与 `arr` 共享内存。
const buf = Buffer.from(arr.buffer)
console.log(buf)
// 输出: <Buffer 88 13 a0 0f>
// 更改原始 Uint16Array 也更改了 Buffer。
arr[1] = 6000
console.log(buf)
// 输出: <Buffer 88 13 70 17>js
const { Buffer } = require('node:buffer')
const arr = new Uint16Array(2)
arr[0] = 5000
arr[1] = 4000
// 与 `arr` 共享内存。
const buf = Buffer.from(arr.buffer)
console.log(buf)
// 输出: <Buffer 88 13 a0 0f>
// 更改原始 Uint16Array 也更改了 Buffer。
arr[1] = 6000
console.log(buf)
// 输出: <Buffer 88 13 70 17>可选的 byteOffset 和 length 参数指定 arrayBuffer 内将由 Buffer 共享的内存范围。
js
import { Buffer } from 'node:buffer'
const ab = new ArrayBuffer(10)
const buf = Buffer.from(ab, 0, 2)
console.log(buf.length)
// 输出: 2js
const { Buffer } = require('node:buffer')
const ab = new ArrayBuffer(10)
const buf = Buffer.from(ab, 0, 2)
console.log(buf.length)
// 输出: 2如果 arrayBuffer 不是 ArrayBuffer 或 SharedArrayBuffer 或不适合 Buffer.from() 变体的其他类型，则会抛出 TypeError。
重要的是要记住，底层 ArrayBuffer 可以覆盖超出 TypedArray 视图范围的内存范围。使用 TypedArray 的 buffer 属性创建的新 Buffer 可能会超出 TypedArray 的范围：
js
import { Buffer } from 'node:buffer'
const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]) // 4 个元素
const arrB = new Uint8Array(arrA.buffer, 1, 2) // 2 个元素
console.log(arrA.buffer === arrB.buffer) // true
const buf = Buffer.from(arrB.buffer)
console.log(buf)
// 输出: <Buffer 63 64 65 66>js
const { Buffer } = require('node:buffer')
const arrA = Uint8Array.from([0x63, 0x64, 0x65, 0x66]) // 4 个元素
const arrB = new Uint8Array(arrA.buffer, 1, 2) // 2 个元素
console.log(arrA.buffer === arrB.buffer) // true
const buf = Buffer.from(arrB.buffer)
console.log(buf)
// 输出: <Buffer 63 64 65 66>静态方法: Buffer.from(buffer)
新增于: v5.10.0
buffer<Buffer> | <Uint8Array> 一个现有的Buffer或Uint8Array，从中复制数据。- 返回值: <Buffer>
将传入的 buffer 数据复制到一个新的 Buffer 实例。
js
import { Buffer } from 'node:buffer'
const buf1 = Buffer.from('buffer')
const buf2 = Buffer.from(buf1)
buf1[0] = 0x61
console.log(buf1.toString())
// 打印: auffer
console.log(buf2.toString())
// 打印: bufferjs
const { Buffer } = require('node:buffer')
const buf1 = Buffer.from('buffer')
const buf2 = Buffer.from(buf1)
buf1[0] = 0x61
console.log(buf1.toString())
// 打印: auffer
console.log(buf2.toString())
// 打印: buffer如果 buffer 不是 Buffer 或其他适合 Buffer.from() 变体的类型，则会抛出 TypeError。
静态方法：Buffer.from(object[, offsetOrEncoding[, length]])
新增于：v8.2.0
object<Object> 支持Symbol.toPrimitive或valueOf()的对象。offsetOrEncoding<integer> | <string> 字节偏移量或编码。length<integer> 长度。- 返回值：<Buffer>
对于 valueOf() 函数返回的值与 object 不严格相等的对象，返回 Buffer.from(object.valueOf(), offsetOrEncoding, length)。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from(new String('this is a test'))
// 打印：<Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>js
const { Buffer } = require('node:buffer')
const buf = Buffer.from(new String('this is a test'))
// 打印：<Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>对于支持 Symbol.toPrimitive 的对象，返回 Buffer.from(object[Symbol.toPrimitive]('string'), offsetOrEncoding)。
js
import { Buffer } from 'node:buffer'
class Foo {
[Symbol.toPrimitive]() {
return 'this is a test'
}
}
const buf = Buffer.from(new Foo(), 'utf8')
// 打印：<Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>js
const { Buffer } = require('node:buffer')
class Foo {
[Symbol.toPrimitive]() {
return 'this is a test'
}
}
const buf = Buffer.from(new Foo(), 'utf8')
// 打印：<Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74>如果 object 不具有上述方法或不是 Buffer.from() 变体适用的其他类型，则会抛出 TypeError。
静态方法：Buffer.from(string[, encoding])
新增于：v5.10.0
创建一个包含 string 的新 Buffer。encoding 参数标识将 string 转换为字节时要使用的字符编码。
js
import { Buffer } from 'node:buffer'
const buf1 = Buffer.from('this is a tést')
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex')
console.log(buf1.toString())
// 打印：this is a tést
console.log(buf2.toString())
// 打印：this is a tést
console.log(buf1.toString('latin1'))
// 打印：this is a téstjs
const { Buffer } = require('node:buffer')
const buf1 = Buffer.from('this is a tést')
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex')
console.log(buf1.toString())
// 打印：this is a tést
console.log(buf2.toString())
// 打印：this is a tést
console.log(buf1.toString('latin1'))
// 打印：this is a tést如果 string 不是字符串或不适合 Buffer.from() 变体的其他类型，则会抛出 TypeError。
Buffer.from(string) 也可能像 Buffer.allocUnsafe() 一样使用内部 Buffer 池。
静态方法: Buffer.isBuffer(obj)
新增于: v0.1.101
如果 obj 是一个 Buffer，则返回 true，否则返回 false。
js
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)) // falsejs
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)
新增于: v0.9.1
如果 encoding 是受支持的字符编码名称，则返回 true，否则返回 false。
js
import { Buffer } from 'node:buffer'
console.log(Buffer.isEncoding('utf8'))
// 输出: true
console.log(Buffer.isEncoding('hex'))
// 输出: true
console.log(Buffer.isEncoding('utf/8'))
// 输出: false
console.log(Buffer.isEncoding(''))
// 输出: falsejs
const { Buffer } = require('node:buffer')
console.log(Buffer.isEncoding('utf8'))
// 输出: true
console.log(Buffer.isEncoding('hex'))
// 输出: true
console.log(Buffer.isEncoding('utf/8'))
// 输出: false
console.log(Buffer.isEncoding(''))
// 输出: false类属性：Buffer.poolSize
新增于：v0.11.3
- <整数> 默认值：
8192
这是用于池化的预分配内部 Buffer 实例的大小（以字节为单位）。此值可以修改。
buf[index]
index<整数>
索引运算符 [index] 可用于获取和设置 buf 中位置 index 处的八位字节。这些值指的是单个字节，因此合法值范围在 0x00 和 0xFF（十六进制）或 0 和 255（十进制）之间。
此运算符继承自 Uint8Array，因此其越界访问的行为与 Uint8Array 相同。换句话说，当 index 为负数或大于等于 buf.length 时，buf[index] 返回 undefined，而如果 index 为负数或 \>= buf.length，则 buf[index] = value 不会修改缓冲区。
js
import { Buffer } from 'node:buffer'
// 将 ASCII 字符串逐字节复制到 `Buffer` 中。
// （这仅适用于仅包含 ASCII 字符的字符串。一般情况下，应使用
// `Buffer.from()` 来执行此转换。）
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'))
// 输出：Node.jsjs
const { Buffer } = require('node:buffer')
// 将 ASCII 字符串逐字节复制到 `Buffer` 中。
// （这仅适用于仅包含 ASCII 字符的字符串。一般情况下，应使用
// `Buffer.from()` 来执行此转换。）
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'))
// 输出：Node.jsbuf.buffer
- <ArrayBuffer> 基于其创建此
Buffer对象的基础ArrayBuffer对象。
此 ArrayBuffer 不保证与原始 Buffer 完全对应。有关详细信息，请参阅有关 buf.byteOffset 的说明。
js
import { Buffer } from 'node:buffer'
const arrayBuffer = new ArrayBuffer(16)
const buffer = Buffer.from(arrayBuffer)
console.log(buffer.buffer === arrayBuffer)
// 输出：truejs
const { Buffer } = require('node:buffer')
const arrayBuffer = new ArrayBuffer(16)
const buffer = Buffer.from(arrayBuffer)
console.log(buffer.buffer === arrayBuffer)
// 输出：truebuf.byteOffset
- <整数>
Buffer的基础ArrayBuffer对象的byteOffset。
在 Buffer.from(ArrayBuffer, byteOffset, length) 中设置 byteOffset 时，或者有时在分配小于 Buffer.poolSize 的 Buffer 时，缓冲区不会从基础 ArrayBuffer 的零偏移量开始。
当使用 buf.buffer 直接访问基础 ArrayBuffer 时，这可能会导致问题，因为 ArrayBuffer 的其他部分可能与 Buffer 对象本身无关。
创建与 Buffer 共享其内存的 TypedArray 对象时的一个常见问题是，在这种情况下，需要正确指定 byteOffset：
js
import { Buffer } from 'node:buffer'
// 创建一个小于 `Buffer.poolSize` 的缓冲区。
const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
// 将 Node.js Buffer 转换为 Int8Array 时，使用 byteOffset
// 只引用包含 nodeBuffer 内存的 nodeBuffer.buffer 部分。
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length)js
const { Buffer } = require('node:buffer')
// 创建一个小于 `Buffer.poolSize` 的缓冲区。
const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
// 将 Node.js Buffer 转换为 Int8Array 时，使用 byteOffset
// 只引用包含 nodeBuffer 内存的 nodeBuffer.buffer 部分。
new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length)buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])
[历史]
| 版本 | 变更 |
|---|---|
| v8.0.0 | target 参数现在可以是 Uint8Array。 |
| v5.11.0 | 现在支持用于指定偏移量的附加参数。 |
| v0.11.13 | 添加于：v0.11.13 |
target<Buffer> | <Uint8Array> 用于与buf进行比较的Buffer或Uint8Array。targetStart<整数> 在target中开始比较的偏移量。默认值：0。targetEnd<整数> 在target中结束比较的偏移量（不包含）。默认值：target.length。sourceStart<整数> 在buf中开始比较的偏移量。默认值：0。sourceEnd<整数> 在buf中结束比较的偏移量（不包含）。默认值：buf.length。- 返回值: <整数>
比较 buf 与 target，并返回一个数字，指示 buf 在排序顺序中是在 target 之前、之后还是与之相同。比较基于每个 Buffer 中实际的字节序列。
- 如果
target与buf相同，则返回0 - 如果
target在排序时应该在buf之前，则返回1。 - 如果
target在排序时应该在buf之后，则返回-1。
js
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))
// 打印：0
console.log(buf1.compare(buf2))
// 打印：-1
console.log(buf1.compare(buf3))
// 打印：-1
console.log(buf2.compare(buf1))
// 打印：1
console.log(buf2.compare(buf3))
// 打印：1
console.log([buf1, buf2, buf3].sort(Buffer.compare))
// 打印： [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// （此结果等于：[buf1, buf3, buf2]。）js
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))
// 打印：0
console.log(buf1.compare(buf2))
// 打印：-1
console.log(buf1.compare(buf3))
// 打印：-1
console.log(buf2.compare(buf1))
// 打印：1
console.log(buf2.compare(buf3))
// 打印：1
console.log([buf1, buf2, buf3].sort(Buffer.compare))
// 打印： [ <Buffer 41 42 43>, <Buffer 41 42 43 44>, <Buffer 42 43 44> ]
// （此结果等于：[buf1, buf3, buf2]。）可选的 targetStart、targetEnd、sourceStart 和 sourceEnd 参数可用于将比较限制在 target 和 buf 中的特定范围内。
js
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))
// 打印：0
console.log(buf1.compare(buf2, 0, 6, 4))
// 打印：-1
console.log(buf1.compare(buf2, 5, 6, 5))
// 打印：1js
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))
// 打印：0
console.log(buf1.compare(buf2, 0, 6, 4))
// 打印：-1
console.log(buf1.compare(buf2, 5, 6, 5))
// 打印：1如果 targetStart < 0、sourceStart \< 0、targetEnd > target.byteLength 或 sourceEnd > source.byteLength，则会抛出 ERR_OUT_OF_RANGE。
buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])
新增于: v0.1.90
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() 执行相同的操作，并且可用于所有 TypedArrays，包括 Node.js Buffer，尽管它采用不同的函数参数。
js
import { Buffer } from 'node:buffer'
// 创建两个 `Buffer` 实例。
const buf1 = Buffer.allocUnsafe(26)
const buf2 = Buffer.allocUnsafe(26).fill('!')
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf1[i] = i + 97
}
// 将 `buf1` 的第 16 到 19 字节复制到 `buf2`，从 `buf2` 的第 8 个字节开始。
buf1.copy(buf2, 8, 16, 20)
// 等同于：
// buf2.set(buf1.subarray(16, 20), 8);
console.log(buf2.toString('ascii', 0, 25))
// 输出：!!!!!!!qrst!!!!!!!!!!!!!js
const { Buffer } = require('node:buffer')
// 创建两个 `Buffer` 实例。
const buf1 = Buffer.allocUnsafe(26)
const buf2 = Buffer.allocUnsafe(26).fill('!')
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf1[i] = i + 97
}
// 将 `buf1` 的第 16 到 19 字节复制到 `buf2`，从 `buf2` 的第 8 个字节开始。
buf1.copy(buf2, 8, 16, 20)
// 等同于：
// buf2.set(buf1.subarray(16, 20), 8);
console.log(buf2.toString('ascii', 0, 25))
// 输出：!!!!!!!qrst!!!!!!!!!!!!!js
import { Buffer } from 'node:buffer'
// 创建一个 `Buffer` 并将数据从一个区域复制到同一 `Buffer` 内的重叠区域。
const buf = Buffer.allocUnsafe(26)
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf[i] = i + 97
}
buf.copy(buf, 0, 4, 10)
console.log(buf.toString())
// 输出：efghijklmnopqrstuvwxyzjs
const { Buffer } = require('node:buffer')
// 创建一个 `Buffer` 并将数据从一个区域复制到同一 `Buffer` 内的重叠区域。
const buf = Buffer.allocUnsafe(26)
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf[i] = i + 97
}
buf.copy(buf, 0, 4, 10)
console.log(buf.toString())
// 输出：efghijklmnopqrstuvwxyzbuf.entries()
新增于: v1.1.0
- 返回值: <迭代器>
创建并返回一个包含 buf 内容中 [index, byte] 对的迭代器。
js
import { Buffer } from 'node:buffer'
// 打印 `Buffer` 的全部内容。
const buf = Buffer.from('buffer')
for (const pair of buf.entries()) {
console.log(pair)
}
// 打印结果：
// [0, 98]
// [1, 117]
// [2, 102]
// [3, 102]
// [4, 101]
// [5, 114]js
const { Buffer } = require('node:buffer')
// 打印 `Buffer` 的全部内容。
const buf = Buffer.from('buffer')
for (const pair of buf.entries()) {
console.log(pair)
}
// 打印结果：
// [0, 98]
// [1, 117]
// [2, 102]
// [3, 102]
// [4, 101]
// [5, 114]buf.equals(otherBuffer)
[历史]
| 版本 | 变更 |
|---|---|
| v8.0.0 | 参数现在可以是 Uint8Array。 |
| v0.11.13 | 新增于: v0.11.13 |
otherBuffer<Buffer> | <Uint8Array> 用于与buf进行比较的Buffer或Uint8Array。- 返回值: <布尔值>
如果 buf 和 otherBuffer 的字节完全相同，则返回 true，否则返回 false。 等同于 buf.compare(otherBuffer) === 0。
js
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))
// 打印结果： true
console.log(buf1.equals(buf3))
// 打印结果： falsejs
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))
// 打印结果： true
console.log(buf1.equals(buf3))
// 打印结果： falsebuf.fill(value[, offset[, end]][, encoding])
[历史记录]
| 版本 | 变更 |
|---|---|
| v11.0.0 | 抛出 ERR_OUT_OF_RANGE 而不是 ERR_INDEX_OUT_OF_RANGE。 |
| v10.0.0 | 负数的 end 值会抛出 ERR_INDEX_OUT_OF_RANGE 错误。 |
| v10.0.0 | 尝试使用长度为零的缓冲区填充非零长度的缓冲区将触发异常。 |
| v10.0.0 | 为 value 指定无效字符串将触发异常。 |
| v5.7.0 | 现在支持 encoding 参数。 |
| v0.5.0 | v0.5.0 版本中添加 |
value<字符串> | <Buffer> | <Uint8Array> | <整数> 用于填充buf的值。空值（字符串、Uint8Array、Buffer）将强制转换为0。offset<整数> 开始填充buf之前要跳过的字节数。默认值：0。end<整数> 停止填充buf的位置（不包含该位置）。默认值：buf.length。encoding<字符串> 如果value是字符串，则为value的编码。默认值：'utf8'。- 返回值： <Buffer>
buf的引用。
使用指定的 value 填充 buf。如果没有给出 offset 和 end，则将填充整个 buf：
js
import { Buffer } from 'node:buffer'
// 使用 ASCII 字符 'h' 填充 `Buffer`。
const b = Buffer.allocUnsafe(50).fill('h')
console.log(b.toString())
// 输出：hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
// 使用空字符串填充缓冲区
const c = Buffer.allocUnsafe(5).fill('')
console.log(c.fill(''))
// 输出：<Buffer 00 00 00 00 00>js
const { Buffer } = require('node:buffer')
// 使用 ASCII 字符 'h' 填充 `Buffer`。
const b = Buffer.allocUnsafe(50).fill('h')
console.log(b.toString())
// 输出：hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
// 使用空字符串填充缓冲区
const c = Buffer.allocUnsafe(5).fill('')
console.log(c.fill(''))
// 输出：<Buffer 00 00 00 00 00>如果 value 不是字符串、Buffer 或整数，则将其强制转换为 uint32 值。如果生成的整数大于 255（十进制），则 buf 将填充 value & 255。
如果 fill() 操作的最后一次写入落在多字节字符上，则只有适合 buf 的字符字节才会被写入：
js
import { Buffer } from 'node:buffer'
// 使用在 UTF-8 中占用两个字节的字符填充 `Buffer`。
console.log(Buffer.allocUnsafe(5).fill('\u0222'))
// 输出：<Buffer c8 a2 c8 a2 c8>js
const { Buffer } = require('node:buffer')
// 使用在 UTF-8 中占用两个字节的字符填充 `Buffer`。
console.log(Buffer.allocUnsafe(5).fill('\u0222'))
// 输出：<Buffer c8 a2 c8 a2 c8>如果 value 包含无效字符，则将其截断；如果没有剩余有效的填充数据，则会抛出异常：
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(5)
console.log(buf.fill('a'))
// 输出：<Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'))
// 输出：<Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'))
// 抛出异常。js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(5)
console.log(buf.fill('a'))
// 输出：<Buffer 61 61 61 61 61>
console.log(buf.fill('aazz', 'hex'))
// 输出：<Buffer aa aa aa aa aa>
console.log(buf.fill('zz', 'hex'))
// 抛出异常。buf.includes(value[, byteOffset][, encoding])
新增于：v5.3.0
value<字符串> | <Buffer> | <Uint8Array> | <整数> 搜索内容。byteOffset<整数> 在buf中开始搜索的位置。如果为负数，则偏移量从buf的末尾计算。默认值：0。encoding<字符串> 如果value是字符串，则指定其编码。默认值：'utf8'。- 返回值： <布尔值> 如果在
buf中找到value，则返回true，否则返回false。
等同于 buf.indexOf() !== -1。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('this is a buffer')
console.log(buf.includes('this'))
// 输出：true
console.log(buf.includes('is'))
// 输出：true
console.log(buf.includes(Buffer.from('a buffer')))
// 输出：true
console.log(buf.includes(97))
// 输出：true (97 是 'a' 的十进制 ASCII 值)
console.log(buf.includes(Buffer.from('a buffer example')))
// 输出：false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)))
// 输出：true
console.log(buf.includes('this', 4))
// 输出：falsejs
const { Buffer } = require('node:buffer')
const buf = Buffer.from('this is a buffer')
console.log(buf.includes('this'))
// 输出：true
console.log(buf.includes('is'))
// 输出：true
console.log(buf.includes(Buffer.from('a buffer')))
// 输出：true
console.log(buf.includes(97))
// 输出：true (97 是 'a' 的十进制 ASCII 值)
console.log(buf.includes(Buffer.from('a buffer example')))
// 输出：false
console.log(buf.includes(Buffer.from('a buffer example').slice(0, 8)))
// 输出：true
console.log(buf.includes('this', 4))
// 输出：falsebuf.indexOf(value[, byteOffset][, encoding])
[历史]
| 版本 | 变更 |
|---|---|
| v8.0.0 | value 现在可以是 Uint8Array。 |
| v5.7.0, v4.4.0 | 当传递 encoding 时，byteOffset 参数不再是必需的。 |
| v1.5.0 | 在 v1.5.0 版本中添加 |
value<字符串> | <Buffer> | <Uint8Array> | <整数> 要搜索的内容。byteOffset<整数> 在buf中开始搜索的位置。如果为负数，则偏移量从buf的末尾计算。默认值：0。encoding<字符串> 如果value是字符串，则这是用于确定将在buf中搜索的字符串的二进制表示的编码。默认值：'utf8'。- 返回值： <整数>
value在buf中首次出现的位置索引，如果buf不包含value，则返回-1。
如果 value 是：
- 字符串，则根据
encoding中的字符编码解释value。 Buffer或Uint8Array，则将完整使用value。要比较部分Buffer，请使用buf.subarray。- 数字，则将
value解释为0到255之间的无符号 8 位整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('this is a buffer')
console.log(buf.indexOf('this'))
// 输出：0
console.log(buf.indexOf('is'))
// 输出：2
console.log(buf.indexOf(Buffer.from('a buffer')))
// 输出：8
console.log(buf.indexOf(97))
// 输出：8 (97 是 'a' 的十进制 ASCII 值)
console.log(buf.indexOf(Buffer.from('a buffer example')))
// 输出：-1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)))
// 输出：8
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')
console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'))
// 输出：4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'))
// 输出：6js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('this is a buffer')
console.log(buf.indexOf('this'))
// 输出：0
console.log(buf.indexOf('is'))
// 输出：2
console.log(buf.indexOf(Buffer.from('a buffer')))
// 输出：8
console.log(buf.indexOf(97))
// 输出：8 (97 是 'a' 的十进制 ASCII 值)
console.log(buf.indexOf(Buffer.from('a buffer example')))
// 输出：-1
console.log(buf.indexOf(Buffer.from('a buffer example').slice(0, 8)))
// 输出：8
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')
console.log(utf16Buffer.indexOf('\u03a3', 0, 'utf16le'))
// 输出：4
console.log(utf16Buffer.indexOf('\u03a3', -4, 'utf16le'))
// 输出：6如果 value 不是字符串、数字或 Buffer，则此方法将抛出 TypeError。如果 value 是数字，它将被强制转换为有效的字节值，即 0 到 255 之间的整数。
如果 byteOffset 不是数字，它将被强制转换为数字。如果强制转换的结果为 NaN 或 0，则将搜索整个缓冲区。此行为与 String.prototype.indexOf() 匹配。
js
import { Buffer } from 'node:buffer'
const b = Buffer.from('abcdef')
// 传递一个数值，但不是有效的字节。
// 输出：2，相当于搜索 99 或 'c'。
console.log(b.indexOf(99.9))
console.log(b.indexOf(256 + 99))
// 传递一个 byteOffset，强制转换为 NaN 或 0。
// 输出：1，搜索整个缓冲区。
console.log(b.indexOf('b', undefined))
console.log(b.indexOf('b', {}))
console.log(b.indexOf('b', null))
console.log(b.indexOf('b', []))js
const { Buffer } = require('node:buffer')
const b = Buffer.from('abcdef')
// 传递一个数值，但不是有效的字节。
// 输出：2，相当于搜索 99 或 'c'。
console.log(b.indexOf(99.9))
console.log(b.indexOf(256 + 99))
// 传递一个 byteOffset，强制转换为 NaN 或 0。
// 输出：1，搜索整个缓冲区。
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()
新增于：v1.1.0
- 返回值：
<Iterator>
创建并返回一个 buf 键（索引）的 迭代器。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('buffer')
for (const key of buf.keys()) {
console.log(key)
}
// 输出：
// 0
// 1
// 2
// 3
// 4
// 5js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('buffer')
for (const key of buf.keys()) {
console.log(key)
}
// 输出：
// 0
// 1
// 2
// 3
// 4
// 5buf.lastIndexOf(value[, byteOffset][, encoding])
[历史]
| 版本 | 变更 |
|---|---|
| v8.0.0 | value 现在可以是 Uint8Array。 |
| v6.0.0 | 新增于：v6.0.0 |
value<字符串> | <Buffer> | <Uint8Array> | <整数> 搜索目标。byteOffset<整数> 在buf中开始搜索的位置。如果为负数，则偏移量从buf的末尾计算。默认值：buf.length - 1。encoding<字符串> 如果value是字符串，则这是用于确定将在buf中搜索的字符串的二进制表示的编码。默认值：'utf8'。- 返回值：<整数>
value在buf中最后一次出现的索引，如果buf不包含value，则返回-1。
与 buf.indexOf() 相同，只是查找 value 的最后一次出现而不是第一次出现。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('this buffer is a buffer')
console.log(buf.lastIndexOf('this'))
// 输出：0
console.log(buf.lastIndexOf('buffer'))
// 输出：17
console.log(buf.lastIndexOf(Buffer.from('buffer')))
// 输出：17
console.log(buf.lastIndexOf(97))
// 输出：15 (97 是 'a' 的十进制 ASCII 值)
console.log(buf.lastIndexOf(Buffer.from('yolo')))
// 输出：-1
console.log(buf.lastIndexOf('buffer', 5))
// 输出：5
console.log(buf.lastIndexOf('buffer', 4))
// 输出：-1
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')
console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'))
// 输出：6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'))
// 输出：4js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('this buffer is a buffer')
console.log(buf.lastIndexOf('this'))
// 输出：0
console.log(buf.lastIndexOf('buffer'))
// 输出：17
console.log(buf.lastIndexOf(Buffer.from('buffer')))
// 输出：17
console.log(buf.lastIndexOf(97))
// 输出：15 (97 是 'a' 的十进制 ASCII 值)
console.log(buf.lastIndexOf(Buffer.from('yolo')))
// 输出：-1
console.log(buf.lastIndexOf('buffer', 5))
// 输出：5
console.log(buf.lastIndexOf('buffer', 4))
// 输出：-1
const utf16Buffer = Buffer.from('\u039a\u0391\u03a3\u03a3\u0395', 'utf16le')
console.log(utf16Buffer.lastIndexOf('\u03a3', undefined, 'utf16le'))
// 输出：6
console.log(utf16Buffer.lastIndexOf('\u03a3', -5, 'utf16le'))
// 输出：4如果 value 不是字符串、数字或 Buffer，则此方法将抛出 TypeError。如果 value 是数字，它将被强制转换为有效的字节值，即 0 到 255 之间的整数。
如果 byteOffset 不是数字，它将被强制转换为数字。任何强制转换为 NaN 的参数，例如 {} 或 undefined，都将搜索整个缓冲区。此行为与 String.prototype.lastIndexOf() 相匹配。
js
import { Buffer } from 'node:buffer'
const b = Buffer.from('abcdef')
// 传递一个数值，但不是有效的字节。
// 输出：2，等同于搜索 99 或 'c'。
console.log(b.lastIndexOf(99.9))
console.log(b.lastIndexOf(256 + 99))
// 传递一个强制转换为 NaN 的 byteOffset。
// 输出：1，搜索整个缓冲区。
console.log(b.lastIndexOf('b', undefined))
console.log(b.lastIndexOf('b', {}))
// 传递一个强制转换为 0 的 byteOffset。
// 输出：-1，等同于传递 0。
console.log(b.lastIndexOf('b', null))
console.log(b.lastIndexOf('b', []))js
const { Buffer } = require('node:buffer')
const b = Buffer.from('abcdef')
// 传递一个数值，但不是有效的字节。
// 输出：2，等同于搜索 99 或 'c'。
console.log(b.lastIndexOf(99.9))
console.log(b.lastIndexOf(256 + 99))
// 传递一个强制转换为 NaN 的 byteOffset。
// 输出：1，搜索整个缓冲区。
console.log(b.lastIndexOf('b', undefined))
console.log(b.lastIndexOf('b', {}))
// 传递一个强制转换为 0 的 byteOffset。
// 输出：-1，等同于传递 0。
console.log(b.lastIndexOf('b', null))
console.log(b.lastIndexOf('b', []))如果 value 是空字符串或空 Buffer，则返回 byteOffset。
buf.length
新增于: v0.1.90
返回 buf 中的字节数。
js
import { Buffer } from 'node:buffer'
// 创建一个 `Buffer` 并使用 UTF-8 向其中写入一个较短的字符串。
const buf = Buffer.alloc(1234)
console.log(buf.length)
// 打印：1234
buf.write('some string', 0, 'utf8')
console.log(buf.length)
// 打印：1234js
const { Buffer } = require('node:buffer')
// 创建一个 `Buffer` 并使用 UTF-8 向其中写入一个较短的字符串。
const buf = Buffer.alloc(1234)
console.log(buf.length)
// 打印：1234
buf.write('some string', 0, 'utf8')
console.log(buf.length)
// 打印：1234buf.parent
自 v8.0.0 起已弃用
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用：请改用 buf.buffer。
buf.parent 属性是 buf.buffer 的已弃用别名。
buf.readBigInt64BE([offset])
新增于：v12.0.0, v10.20.0
从指定 offset 位置的 buf 中读取一个带符号的大端序 64 位整数。
从 Buffer 读取的整数被解释为二进制补码带符号值。
buf.readBigInt64LE([offset])
新增于：v12.0.0, v10.20.0
从指定 offset 位置的 buf 中读取一个带符号的小端序 64 位整数。
从 Buffer 读取的整数被解释为二进制补码带符号值。
buf.readBigUInt64BE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.10.0, v12.19.0 | 此函数也可用作 buf.readBigUint64BE()。 |
| v12.0.0, v10.20.0 | 新增于：v12.0.0, v10.20.0 |
从 buf 中指定的 offset 位置读取一个无符号的大端序 64 位整数。
此函数也可使用 readBigUint64BE 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])
console.log(buf.readBigUInt64BE(0))
// 打印：4294967295njs
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])
console.log(buf.readBigUInt64BE(0))
// 打印：4294967295nbuf.readBigUInt64LE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.10.0, v12.19.0 | 此函数也可用作 buf.readBigUint64LE()。 |
| v12.0.0, v10.20.0 | v12.0.0, v10.20.0 版本中添加 |
从指定 offset 处的 buf 中读取一个无符号的小端序 64 位整数。
此函数也可使用 readBigUint64LE 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])
console.log(buf.readBigUInt64LE(0))
// 输出：18446744069414584320njs
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff])
console.log(buf.readBigUInt64LE(0))
// 输出：18446744069414584320nbuf.readDoubleBE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制转换 offset 为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
从 buf 中指定 offset 位置读取一个 64 位大端序双精度浮点数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])
console.log(buf.readDoubleBE(0))
// 打印：8.20788039913184e-304js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])
console.log(buf.readDoubleBE(0))
// 打印：8.20788039913184e-304buf.readDoubleLE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
从 buf 中指定 offset 位置读取一个 64 位小端序双精度浮点数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])
console.log(buf.readDoubleLE(0))
// 打印：5.447603722011605e-270
console.log(buf.readDoubleLE(1))
// 抛出 ERR_OUT_OF_RANGE。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8])
console.log(buf.readDoubleLE(0))
// 打印：5.447603722011605e-270
console.log(buf.readDoubleLE(1))
// 抛出 ERR_OUT_OF_RANGE。buf.readFloatBE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.11.15 | 添加于：v0.11.15 |
从 buf 中指定 offset 位置读取一个 32 位大端序浮点数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([1, 2, 3, 4])
console.log(buf.readFloatBE(0))
// 打印：2.387939260590663e-38js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([1, 2, 3, 4])
console.log(buf.readFloatBE(0))
// 打印：2.387939260590663e-38buf.readFloatLE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.11.15 | 添加于：v0.11.15 |
从 buf 中指定 offset 位置读取一个 32 位小端序浮点数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([1, 2, 3, 4])
console.log(buf.readFloatLE(0))
// 打印：1.539989614439558e-36
console.log(buf.readFloatLE(1))
// 抛出 ERR_OUT_OF_RANGE 错误。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([1, 2, 3, 4])
console.log(buf.readFloatLE(0))
// 打印：1.539989614439558e-36
console.log(buf.readFloatLE(1))
// 抛出 ERR_OUT_OF_RANGE 错误。buf.readInt8([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.0 | v0.5.0 版本中添加 |
从指定 offset 位置的 buf 中读取一个带符号的 8 位整数。
从 Buffer 读取的整数被解释为二进制补码带符号值。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([-1, 5])
console.log(buf.readInt8(0))
// 输出： -1
console.log(buf.readInt8(1))
// 输出： 5
console.log(buf.readInt8(2))
// 抛出 ERR_OUT_OF_RANGE 错误。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([-1, 5])
console.log(buf.readInt8(0))
// 输出： -1
console.log(buf.readInt8(1))
// 输出： 5
console.log(buf.readInt8(2))
// 抛出 ERR_OUT_OF_RANGE 错误。buf.readInt16BE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
从 buf 中指定的 offset 位置读取一个有符号的大端序 16 位整数。
从 Buffer 读取的整数被解释为二进制补码的有符号值。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0, 5])
console.log(buf.readInt16BE(0))
// 打印：5js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0, 5])
console.log(buf.readInt16BE(0))
// 打印：5buf.readInt16LE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再对 offset 进行隐式强制转换为 uint32。 |
| v0.5.5 | v0.5.5 中添加 |
从 buf 中指定的 offset 位置读取一个带符号的小端序 16 位整数。
从 Buffer 读取的整数被解释为二进制补码带符号值。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0, 5])
console.log(buf.readInt16LE(0))
// 打印：1280
console.log(buf.readInt16LE(1))
// 抛出 ERR_OUT_OF_RANGE。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0, 5])
console.log(buf.readInt16LE(0))
// 打印：1280
console.log(buf.readInt16LE(1))
// 抛出 ERR_OUT_OF_RANGE。buf.readInt32BE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | 在 v0.5.5 中添加 |
从指定 offset 处的 buf 读取一个带符号的大端 32 位整数。
从 Buffer 读取的整数被解释为二进制补码带符号值。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0, 0, 0, 5])
console.log(buf.readInt32BE(0))
// 打印：5js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0, 0, 0, 5])
console.log(buf.readInt32BE(0))
// 打印：5buf.readInt32LE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制转换 offset 为 uint32。 |
| v0.5.5 | 在 v0.5.5 中添加 |
从指定 offset 处的 buf 中读取一个带符号的小端序 32 位整数。
从 Buffer 读取的整数被解释为二进制补码的带符号值。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0, 0, 0, 5])
console.log(buf.readInt32LE(0))
// 打印：83886080
console.log(buf.readInt32LE(1))
// 抛出 ERR_OUT_OF_RANGE。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0, 0, 0, 5])
console.log(buf.readInt32LE(0))
// 打印：83886080
console.log(buf.readInt32LE(1))
// 抛出 ERR_OUT_OF_RANGE。buf.readIntBE(offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将 offset 和 byteLength 转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
offset<整数> 开始读取前要跳过的字节数。必须满足0 \<= offset \<= buf.length - byteLength。byteLength<整数> 要读取的字节数。必须满足0 \< byteLength \<= 6。- 返回值: <整数>
从 buf 中指定 offset 位置读取 byteLength 个字节，并将结果解释为大端序、二进制补码的有符号值，支持高达 48 位的精度。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readIntBE(0, 6).toString(16))
// 打印：1234567890ab
console.log(buf.readIntBE(1, 6).toString(16))
// 抛出 ERR_OUT_OF_RANGE。
console.log(buf.readIntBE(1, 0).toString(16))
// 抛出 ERR_OUT_OF_RANGE。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readIntBE(0, 6).toString(16))
// 打印：1234567890ab
console.log(buf.readIntBE(1, 6).toString(16))
// 抛出 ERR_OUT_OF_RANGE。
console.log(buf.readIntBE(1, 0).toString(16))
// 抛出 ERR_OUT_OF_RANGE。buf.readIntLE(offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式强制转换 offset 和 byteLength 为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
offset<整数> 开始读取前要跳过的字节数。必须满足0 \<= offset \<= buf.length - byteLength。byteLength<整数> 要读取的字节数。必须满足0 \< byteLength \<= 6。- 返回值： <整数>
从 buf 中指定的 offset 位置读取 byteLength 个字节，并将结果解释为一个最多支持 48 位精度的、小端序、二进制补码的有符号值。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readIntLE(0, 6).toString(16))
// 输出：-546f87a9cbeejs
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readIntLE(0, 6).toString(16))
// 输出：-546f87a9cbeebuf.readUInt8([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.readUint8() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.0 | 新增于：v0.5.0 |
从指定 offset 处的 buf 中读取一个无符号的 8 位整数。
此函数也可使用 readUint8 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([1, -2])
console.log(buf.readUInt8(0))
// 打印：1
console.log(buf.readUInt8(1))
// 打印：254
console.log(buf.readUInt8(2))
// 抛出 ERR_OUT_OF_RANGE 错误。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([1, -2])
console.log(buf.readUInt8(0))
// 打印：1
console.log(buf.readUInt8(1))
// 打印：254
console.log(buf.readUInt8(2))
// 抛出 ERR_OUT_OF_RANGE 错误。buf.readUInt16BE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.readUint16BE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式将偏移量强制转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
从 buf 中指定 offset 位置读取一个无符号大端序 16 位整数。
此函数也可通过 readUint16BE 别名使用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56])
console.log(buf.readUInt16BE(0).toString(16))
// 输出：1234
console.log(buf.readUInt16BE(1).toString(16))
// 输出：3456js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56])
console.log(buf.readUInt16BE(0).toString(16))
// 输出：1234
console.log(buf.readUInt16BE(1).toString(16))
// 输出：3456buf.readUInt16LE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.readUint16LE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
从 buf 中指定的 offset 位置读取一个无符号的小端序 16 位整数。
此函数也可使用 readUint16LE 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56])
console.log(buf.readUInt16LE(0).toString(16))
// 输出：3412
console.log(buf.readUInt16LE(1).toString(16))
// 输出：5634
console.log(buf.readUInt16LE(2).toString(16))
// 抛出 ERR_OUT_OF_RANGE 错误。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56])
console.log(buf.readUInt16LE(0).toString(16))
// 输出：3412
console.log(buf.readUInt16LE(1).toString(16))
// 输出：5634
console.log(buf.readUInt16LE(2).toString(16))
// 抛出 ERR_OUT_OF_RANGE 错误。buf.readUInt32BE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.readUint32BE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
从 buf 中指定 offset 位置读取一个无符号大端序 32 位整数。
此函数也可通过别名 readUint32BE 使用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])
console.log(buf.readUInt32BE(0).toString(16))
// 打印：12345678js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])
console.log(buf.readUInt32BE(0).toString(16))
// 打印：12345678buf.readUInt32LE([offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.readUint32LE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
从 buf 中指定的 offset 位置读取一个无符号的小端序 32 位整数。
此函数也可使用别名 readUint32LE。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])
console.log(buf.readUInt32LE(0).toString(16))
// 输出：78563412
console.log(buf.readUInt32LE(1).toString(16))
// 抛出 ERR_OUT_OF_RANGE 错误。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78])
console.log(buf.readUInt32LE(0).toString(16))
// 输出：78563412
console.log(buf.readUInt32LE(1).toString(16))
// 抛出 ERR_OUT_OF_RANGE 错误。buf.readUIntBE(offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可用作 buf.readUintBE()。 |
| v10.0.0 | 删除了 noAssert，并且不再隐式强制将 offset 和 byteLength 转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
offset<整数> 开始读取前要跳过的字节数。必须满足0 \<= offset \<= buf.length - byteLength。byteLength<整数> 要读取的字节数。必须满足0 \< byteLength \<= 6。- 返回值: <整数>
从指定 offset 处的 buf 读取 byteLength 个字节，并将结果解释为一个支持最多 48 位精度的无符号大端整数。
此函数也可用 readUintBE 别名调用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readUIntBE(0, 6).toString(16))
// 输出：1234567890ab
console.log(buf.readUIntBE(1, 6).toString(16))
// 抛出 ERR_OUT_OF_RANGE。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readUIntBE(0, 6).toString(16))
// 输出：1234567890ab
console.log(buf.readUIntBE(1, 6).toString(16))
// 抛出 ERR_OUT_OF_RANGE。buf.readUIntLE(offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.readUintLE() 使用。 |
| v10.0.0 | 移除 noAssert，不再隐式强制将 offset 和 byteLength 转换为 uint32。 |
| v0.11.15 | v0.11.15 版本中添加 |
offset<整数> 开始读取前要跳过的字节数。必须满足0 \<= offset \<= buf.length - byteLength。byteLength<整数> 要读取的字节数。必须满足0 \< byteLength \<= 6。- 返回值: <整数>
从指定 offset 处的 buf 读取 byteLength 个字节，并将结果解释为一个无符号的小端序整数，支持最多 48 位精度。
此函数也可通过 readUintLE 别名使用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readUIntLE(0, 6).toString(16))
// 输出：ab9078563412js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab])
console.log(buf.readUIntLE(0, 6).toString(16))
// 输出：ab9078563412buf.subarray([start[, end]])
新增于：v3.0.0
start<整数> 新Buffer的起始位置。默认值：0。end<整数> 新Buffer的结束位置（不包含结束位置）。默认值：buf.length。- 返回值: <Buffer>
返回一个新的 Buffer，它引用与原始 Buffer 相同的内存，但其偏移量和大小由 start 和 end 索引裁剪。
指定 end 大于 buf.length 将返回与 end 等于 buf.length 相同的结果。
此方法继承自 TypedArray.prototype.subarray()。
修改新的 Buffer 切片将修改原始 Buffer 中的内存，因为这两个对象的已分配内存重叠。
js
import { Buffer } from 'node:buffer'
// 使用 ASCII 字母表创建一个 `Buffer`，截取一部分，然后修改原始 `Buffer` 中的一个字节。
const buf1 = Buffer.allocUnsafe(26)
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf1[i] = i + 97
}
const buf2 = buf1.subarray(0, 3)
console.log(buf2.toString('ascii', 0, buf2.length))
// 输出：abc
buf1[0] = 33
console.log(buf2.toString('ascii', 0, buf2.length))
// 输出：!bcjs
const { Buffer } = require('node:buffer')
// 使用 ASCII 字母表创建一个 `Buffer`，截取一部分，然后修改原始 `Buffer` 中的一个字节。
const buf1 = Buffer.allocUnsafe(26)
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf1[i] = i + 97
}
const buf2 = buf1.subarray(0, 3)
console.log(buf2.toString('ascii', 0, buf2.length))
// 输出：abc
buf1[0] = 33
console.log(buf2.toString('ascii', 0, buf2.length))
// 输出：!bc指定负索引会导致切片相对于 buf 的结尾而不是开头生成。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('buffer')
console.log(buf.subarray(-6, -1).toString())
// 输出：buffe
// (等效于 buf.subarray(0, 5)。)
console.log(buf.subarray(-6, -2).toString())
// 输出：buff
// (等效于 buf.subarray(0, 4)。)
console.log(buf.subarray(-5, -2).toString())
// 输出：uff
// (等效于 buf.subarray(1, 4)。)js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('buffer')
console.log(buf.subarray(-6, -1).toString())
// 输出：buffe
// (等效于 buf.subarray(0, 5)。)
console.log(buf.subarray(-6, -2).toString())
// 输出：buff
// (等效于 buf.subarray(0, 4)。)
console.log(buf.subarray(-5, -2).toString())
// 输出：uff
// (等效于 buf.subarray(1, 4)。)buf.slice([start[, end]])
[历史]
| 版本 | 变更 |
|---|---|
| v17.5.0, v16.15.0 | buf.slice() 方法已弃用。 |
| v7.0.0 | 所有偏移量现在在进行任何计算之前都被强制转换为整数。 |
| v7.1.0, v6.9.2 | 将偏移量强制转换为整数现在可以正确处理 32 位整数范围之外的值。 |
| v0.3.0 | 添加于：v0.3.0 |
start<整数> 新Buffer的起始位置。默认值：0。end<整数> 新Buffer的结束位置（不包含）。默认值：buf.length。- 返回值：<Buffer>
[稳定性：0 - 已弃用]
稳定性：0 稳定性：0 - 已弃用：请改用 buf.subarray。
返回一个新的 Buffer，它引用与原始 Buffer 相同的内存，但其偏移量和大小由 start 和 end 索引裁剪。
此方法与 Uint8Array.prototype.slice() 不兼容，后者是 Buffer 的超类。要复制切片，请使用 Uint8Array.prototype.slice()。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('buffer')
const copiedBuf = Uint8Array.prototype.slice.call(buf)
copiedBuf[0]++
console.log(copiedBuf.toString())
// 输出：cuffer
console.log(buf.toString())
// 输出：buffer
// 使用 buf.slice()，原始缓冲区会被修改。
const notReallyCopiedBuf = buf.slice()
notReallyCopiedBuf[0]++
console.log(notReallyCopiedBuf.toString())
// 输出：cuffer
console.log(buf.toString())
// 也输出：cuffer (!)js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('buffer')
const copiedBuf = Uint8Array.prototype.slice.call(buf)
copiedBuf[0]++
console.log(copiedBuf.toString())
// 输出：cuffer
console.log(buf.toString())
// 输出：buffer
// 使用 buf.slice()，原始缓冲区会被修改。
const notReallyCopiedBuf = buf.slice()
notReallyCopiedBuf[0]++
console.log(notReallyCopiedBuf.toString())
// 输出：cuffer
console.log(buf.toString())
// 也输出：cuffer (!)buf.swap16()
新增于：v5.10.0
- 返回值：
<Buffer>buf的引用。
将 buf 解释为一个无符号 16 位整数数组，并就地交换字节顺序。如果 buf.length 不是 2 的倍数，则抛出 ERR_INVALID_BUFFER_SIZE 错误。
js
import { Buffer } from 'node:buffer'
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])
console.log(buf1)
// 打印：<Buffer 01 02 03 04 05 06 07 08>
buf1.swap16()
console.log(buf1)
// 打印：<Buffer 02 01 04 03 06 05 08 07>
const buf2 = Buffer.from([0x1, 0x2, 0x3])
buf2.swap16()
// 抛出 ERR_INVALID_BUFFER_SIZE 错误。js
const { Buffer } = require('node:buffer')
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])
console.log(buf1)
// 打印：<Buffer 01 02 03 04 05 06 07 08>
buf1.swap16()
console.log(buf1)
// 打印：<Buffer 02 01 04 03 06 05 08 07>
const buf2 = Buffer.from([0x1, 0x2, 0x3])
buf2.swap16()
// 抛出 ERR_INVALID_BUFFER_SIZE 错误。buf.swap16() 的一个便利用途是执行 UTF-16 小端序和 UTF-16 大端序之间的快速就地转换：
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('This is little-endian UTF-16', 'utf16le')
buf.swap16() // 转换为大端序 UTF-16 文本。js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('This is little-endian UTF-16', 'utf16le')
buf.swap16() // 转换为大端序 UTF-16 文本。buf.swap32()
新增于: v5.10.0
- 返回值: <Buffer>
buf的引用。
将 buf 解释为一个无符号 32 位整数数组，并 就地 交换字节序。如果 buf.length 不是 4 的倍数，则抛出 ERR_INVALID_BUFFER_SIZE 错误。
js
import { Buffer } from 'node:buffer'
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])
console.log(buf1)
// 输出: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap32()
console.log(buf1)
// 输出: <Buffer 04 03 02 01 08 07 06 05>
const buf2 = Buffer.from([0x1, 0x2, 0x3])
buf2.swap32()
// 抛出 ERR_INVALID_BUFFER_SIZE 错误。js
const { Buffer } = require('node:buffer')
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])
console.log(buf1)
// 输出: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap32()
console.log(buf1)
// 输出: <Buffer 04 03 02 01 08 07 06 05>
const buf2 = Buffer.from([0x1, 0x2, 0x3])
buf2.swap32()
// 抛出 ERR_INVALID_BUFFER_SIZE 错误。buf.swap64()
新增于: v6.3.0
- 返回值: <Buffer>
buf的引用。
将 buf 解释为一个 64 位数字数组，并就地交换字节序。如果 buf.length 不是 8 的倍数，则抛出 ERR_INVALID_BUFFER_SIZE 错误。
js
import { Buffer } from 'node:buffer'
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])
console.log(buf1)
// 输出: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap64()
console.log(buf1)
// 输出: <Buffer 08 07 06 05 04 03 02 01>
const buf2 = Buffer.from([0x1, 0x2, 0x3])
buf2.swap64()
// 抛出 ERR_INVALID_BUFFER_SIZE 错误。js
const { Buffer } = require('node:buffer')
const buf1 = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8])
console.log(buf1)
// 输出: <Buffer 01 02 03 04 05 06 07 08>
buf1.swap64()
console.log(buf1)
// 输出: <Buffer 08 07 06 05 04 03 02 01>
const buf2 = Buffer.from([0x1, 0x2, 0x3])
buf2.swap64()
// 抛出 ERR_INVALID_BUFFER_SIZE 错误。buf.toJSON()
新增于：v0.9.2
- 返回值：<Object>
返回 buf 的 JSON 表示形式。JSON.stringify() 在序列化 Buffer 实例时会隐式调用此函数。
Buffer.from() 接受从此方法返回的格式的对象。特别是，Buffer.from(buf.toJSON()) 的作用类似于 Buffer.from(buf)。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5])
const json = JSON.stringify(buf)
console.log(json)
// 打印：{"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)
// 打印：<Buffer 01 02 03 04 05>js
const { Buffer } = require('node:buffer')
const buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5])
const json = JSON.stringify(buf)
console.log(json)
// 打印：{"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)
// 打印：<Buffer 01 02 03 04 05>buf.toString([encoding[, start[, end]]])
新增于: v0.1.90
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 中获取。
js
import { Buffer } from 'node:buffer'
const buf1 = Buffer.allocUnsafe(26)
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf1[i] = i + 97
}
console.log(buf1.toString('utf8'))
// 输出: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5))
// 输出: abcde
const buf2 = Buffer.from('tést')
console.log(buf2.toString('hex'))
// 输出: 74c3a97374
console.log(buf2.toString('utf8', 0, 3))
// 输出: té
console.log(buf2.toString(undefined, 0, 3))
// 输出: téjs
const { Buffer } = require('node:buffer')
const buf1 = Buffer.allocUnsafe(26)
for (let i = 0; i < 26; i++) {
// 97 是 'a' 的十进制 ASCII 值。
buf1[i] = i + 97
}
console.log(buf1.toString('utf8'))
// 输出: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5))
// 输出: abcde
const buf2 = Buffer.from('tést')
console.log(buf2.toString('hex'))
// 输出: 74c3a97374
console.log(buf2.toString('utf8', 0, 3))
// 输出: té
console.log(buf2.toString(undefined, 0, 3))
// 输出: tébuf.values()
新增于: v1.1.0
- 返回值: <迭代器>
创建并返回 buf 值（字节）的 迭代器。当 Buffer 用于 for..of 语句时，此函数会自动调用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.from('buffer')
for (const value of buf.values()) {
console.log(value)
}
// 输出：
// 98
// 117
// 102
// 102
// 101
// 114
for (const value of buf) {
console.log(value)
}
// 输出：
// 98
// 117
// 102
// 102
// 101
// 114js
const { Buffer } = require('node:buffer')
const buf = Buffer.from('buffer')
for (const value of buf.values()) {
console.log(value)
}
// 输出：
// 98
// 117
// 102
// 102
// 101
// 114
for (const value of buf) {
console.log(value)
}
// 输出：
// 98
// 117
// 102
// 102
// 101
// 114buf.write(string[, offset[, length]][, encoding])
Added in: v0.1.90
string<string> 写入buf的字符串。offset<integer> 开始写入string之前要跳过的字节数。默认值:0。length<integer> 要写入的最大字节数（写入的字节数不会超过buf.length - offset）。默认值:buf.length - offset。encoding<string>string的字符编码。默认值:'utf8'。- 返回值: <integer> 写入的字节数。
根据 encoding 中的字符编码，将 string 写入 buf 的 offset 位置。length 参数是要写入的字节数。如果 buf 中没有足够的空间容纳整个字符串，则只写入 string 的一部分。但是，不会写入部分编码的字符。
js
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 : abjs
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 : abbuf.writeBigInt64BE(value[, offset])
新增于：v12.0.0, v10.20.0
value<bigint> 将写入buf的数字。offset<integer> 开始写入前要跳过的字节数。必须满足：0 \<= offset \<= buf.length - 8。默认值：0。- 返回值: <integer>
offset加上写入的字节数。
以大端序将 value 写入 buf 中指定的 offset 位置。
value 被解释并写入为二进制补码有符号整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(8)
buf.writeBigInt64BE(0x0102030405060708n, 0)
console.log(buf)
// 输出：<Buffer 01 02 03 04 05 06 07 08>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(8)
buf.writeBigInt64BE(0x0102030405060708n, 0)
console.log(buf)
// 输出：<Buffer 01 02 03 04 05 06 07 08>buf.writeBigInt64LE(value[, offset])
新增于: v12.0.0, v10.20.0
value<bigint> 将写入buf的数字。offset<integer> 开始写入前跳过的字节数。必须满足：0 \<= offset \<= buf.length - 8。默认值：0。- 返回值: <integer>
offset加上写入的字节数。
以小端序将 value 写入 buf 指定的 offset 处。
value 被解释并写入为二进制补码有符号整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(8)
buf.writeBigInt64LE(0x0102030405060708n, 0)
console.log(buf)
// 打印：<Buffer 08 07 06 05 04 03 02 01>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(8)
buf.writeBigInt64LE(0x0102030405060708n, 0)
console.log(buf)
// 打印：<Buffer 08 07 06 05 04 03 02 01>buf.writeBigUInt64BE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.10.0, v12.19.0 | 此函数也可作为 buf.writeBigUint64BE() 使用。 |
| v12.0.0, v10.20.0 | v12.0.0, v10.20.0 版本中添加 |
value<bigint> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足：0 \<= offset \<= buf.length - 8。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 写入 buf 的指定 offset 位置。
此函数也可通过 writeBigUint64BE 别名使用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(8)
buf.writeBigUInt64BE(0xdecafafecacefaden, 0)
console.log(buf)
// 输出：<Buffer de ca fa fe ca ce fa de>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(8)
buf.writeBigUInt64BE(0xdecafafecacefaden, 0)
console.log(buf)
// 输出：<Buffer de ca fa fe ca ce fa de>buf.writeBigUInt64LE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.10.0, v12.19.0 | 此函数也可作为 buf.writeBigUint64LE() 使用。 |
| v12.0.0, v10.20.0 | v12.0.0, v10.20.0 版本中添加 |
value<bigint> 将写入buf的数字。offset<整数> 开始写入前跳过的字节数。必须满足：0 \<= offset \<= buf.length - 8。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
将 value 以小端序写入 buf 的指定 offset 位置
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(8)
buf.writeBigUInt64LE(0xdecafafecacefaden, 0)
console.log(buf)
// 输出：<Buffer de fa ce ca fe fa ca de>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(8)
buf.writeBigUInt64LE(0xdecafafecacefaden, 0)
console.log(buf)
// 输出：<Buffer de fa ce ca fe fa ca de>此函数也可通过 writeBigUint64LE 别名使用。
buf.writeDoubleBE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式强制将偏移量转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
value<数字> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 8。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 写入 buf 的指定 offset 位置。value 必须是 JavaScript 数字。当 value 不是 JavaScript 数字时，行为未定义。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(8)
buf.writeDoubleBE(123.456, 0)
console.log(buf)
// 输出：<Buffer 40 5e dd 2f 1a 9f be 77>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(8)
buf.writeDoubleBE(123.456, 0)
console.log(buf)
// 输出：<Buffer 40 5e dd 2f 1a 9f be 77>buf.writeDoubleLE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式强制将偏移量转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
value<数字> 要写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 8。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以小端序将 value 写入 buf 的指定 offset 位置。value 必须是 JavaScript 数字。当 value 不是 JavaScript 数字时，行为未定义。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(8)
buf.writeDoubleLE(123.456, 0)
console.log(buf)
// 输出：<Buffer 77 be 9f 1a 2f dd 5e 40>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(8)
buf.writeDoubleLE(123.456, 0)
console.log(buf)
// 输出：<Buffer 77 be 9f 1a 2f dd 5e 40>buf.writeFloatBE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式强制将 offset 转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
value<数字> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 写入 buf 的指定 offset 处。当 value 不是 JavaScript 数字时，行为未定义。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeFloatBE(0xcafebabe, 0)
console.log(buf)
// 打印：<Buffer 4f 4a fe bb>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeFloatBE(0xcafebabe, 0)
console.log(buf)
// 打印：<Buffer 4f 4a fe bb>buf.writeFloatLE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式强制将偏移量转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
value<数字> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - 4。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以小端序将 value 写入 buf 的指定 offset 位置。当 value 不是 JavaScript 数字时，行为未定义。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeFloatLE(0xcafebabe, 0)
console.log(buf)
// 打印：<Buffer bb fe 4a 4f>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeFloatLE(0xcafebabe, 0)
console.log(buf)
// 打印：<Buffer bb fe 4a 4f>buf.writeInt8(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式地将偏移量强制转换为 uint32。 |
| v0.5.0 | 在 v0.5.0 中添加 |
value<整数> 将写入buf的数字。offset<整数> 开始写入之前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 1。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
将 value 写入 buf 中指定的 offset 位置。value 必须是有效的带符号 8 位整数。当 value 不是带符号 8 位整数时，行为未定义。
value 被解释并写入为二进制补码带符号整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(2)
buf.writeInt8(2, 0)
buf.writeInt8(-2, 1)
console.log(buf)
// 输出：<Buffer 02 fe>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(2)
buf.writeInt8(2, 0)
buf.writeInt8(-2, 1)
console.log(buf)
// 输出：<Buffer 02 fe>buf.writeInt16BE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert 并且不再隐式将偏移量强制转换为 uint32。 |
| v0.5.5 | 新增于：v0.5.5 |
value<整数> 将写入buf的数字。offset<整数> 开始写入前跳过的字节数。必须满足0 \<= offset \<= buf.length - 2。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 写入 buf 中指定的 offset 位置。value 必须是有效的 16 位有符号整数。当 value 不是 16 位有符号整数时，行为未定义。
value 被解释并写入为二进制补码有符号整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(2)
buf.writeInt16BE(0x0102, 0)
console.log(buf)
// 输出：<Buffer 01 02>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(2)
buf.writeInt16BE(0x0102, 0)
console.log(buf)
// 输出：<Buffer 01 02>buf.writeInt16LE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再对 offset 进行隐式强制转换为 uint32。 |
| v0.5.5 | 新增于：v0.5.5 |
value<整数> 将写入buf的数字。offset<整数> 开始写入前跳过的字节数。必须满足0 \<= offset \<= buf.length - 2。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以小端序方式将 value 写入 buf 的指定 offset 位置。value 必须是有效的 16 位有符号整数。当 value 不是 16 位有符号整数时，行为未定义。
value 被解释并写入为二进制补码有符号整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(2)
buf.writeInt16LE(0x0304, 0)
console.log(buf)
// 打印：<Buffer 04 03>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(2)
buf.writeInt16LE(0x0304, 0)
console.log(buf)
// 打印：<Buffer 04 03>buf.writeInt32BE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
value<整数> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 4。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 写入 buf 中指定的 offset 位置。value 必须是有效的 32 位有符号整数。当 value 不是 32 位有符号整数时，行为未定义。
value 被解释并写入为二进制补码有符号整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeInt32BE(0x01020304, 0)
console.log(buf)
// 输出：<Buffer 01 02 03 04>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeInt32BE(0x01020304, 0)
console.log(buf)
// 输出：<Buffer 01 02 03 04>buf.writeInt32LE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | 新增于：v0.5.5 |
value<整数> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 4。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
将 value 以小端序写入 buf 的指定 offset 处。value 必须是有效的 32 位有符号整数。当 value 不是 32 位有符号整数时，行为未定义。
value 被解释并写入为二进制补码有符号整数。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeInt32LE(0x05060708, 0)
console.log(buf)
// 打印：<Buffer 08 07 06 05>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeInt32LE(0x05060708, 0)
console.log(buf)
// 打印：<Buffer 08 07 06 05>buf.writeIntBE(value, offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将 offset 和 byteLength 转换为 uint32。 |
| v0.11.15 | 新增于：v0.11.15 |
value<整数> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength。byteLength<整数> 要写入的字节数。必须满足0 < byteLength <= 6。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 的 byteLength 字节写入 buf 的指定 offset 位置。支持高达 48 位的精度。当 value 不是有符号整数时，行为未定义。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(6)
buf.writeIntBE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer 12 34 56 78 90 ab>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(6)
buf.writeIntBE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer 12 34 56 78 90 ab>buf.writeIntLE(value, offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 移除了 noAssert，并且不再隐式地将 offset 和 byteLength 强制转换为 uint32。 |
| v0.11.15 | v0.11.15 版本中添加 |
value<整数> 要写入buf的数字。offset<整数> 开始写入之前要跳过的字节数。必须满足0 \<= offset \<= buf.length - byteLength。byteLength<整数> 要写入的字节数。必须满足0 \< byteLength \<= 6。- 返回值: <整数>
offset加上写入的字节数。
将 value 的 byteLength 个字节以小端序写入 buf 的指定 offset 位置。支持高达 48 位的精度。当 value 不是有符号整数时，行为未定义。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(6)
buf.writeIntLE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer ab 90 78 56 34 12>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(6)
buf.writeIntLE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer ab 90 78 56 34 12>buf.writeUInt8(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.writeUint8() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.0 | 新增于：v0.5.0 |
value<整数> 将写入buf的数字。offset<整数> 开始写入之前要跳过的字节数。必须满足0 <= offset <= buf.length - 1。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
将 value 写入 buf 中指定的 offset 位置。value 必须是有效的无符号 8 位整数。当 value 不是无符号 8 位整数时，行为未定义。
此函数也可通过 writeUint8 别名使用。
js
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)
// 输出：<Buffer 03 04 23 42>js
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)
// 输出：<Buffer 03 04 23 42>buf.writeUInt16BE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可用作 buf.writeUint16BE()。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | 在 v0.5.5 中添加 |
value<整数> 要写入buf的数字。offset<整数> 开始写入之前要跳过的字节数。必须满足0 <= offset <= buf.length - 2。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 写入指定 offset 处的 buf。value 必须是有效的无符号 16 位整数。当 value 不是无符号 16 位整数时，行为未定义。
此函数也可使用 writeUint16BE 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeUInt16BE(0xdead, 0)
buf.writeUInt16BE(0xbeef, 2)
console.log(buf)
// 输出：<Buffer de ad be ef>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeUInt16BE(0xdead, 0)
buf.writeUInt16BE(0xbeef, 2)
console.log(buf)
// 输出：<Buffer de ad be ef>buf.writeUInt16LE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.writeUint16LE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式将偏移量强制转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
value<整数> 写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 2。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以小端序方式将 value 写入 buf 指定的 offset 位置。value 必须是有效的无符号 16 位整数。当 value 不是无符号 16 位整数时，行为未定义。
此函数也可通过 writeUint16LE 别名使用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeUInt16LE(0xdead, 0)
buf.writeUInt16LE(0xbeef, 2)
console.log(buf)
// 输出：<Buffer ad de ef be>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeUInt16LE(0xdead, 0)
buf.writeUInt16LE(0xbeef, 2)
console.log(buf)
// 输出：<Buffer ad de ef be>buf.writeUInt32BE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.writeUint32BE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | 新增于：v0.5.5 |
value<整数> 将写入buf的数字。offset<整数> 开始写入之前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 4。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 写入 buf 的指定 offset 处。value 必须是有效的无符号 32 位整数。当 value 不是无符号 32 位整数时，行为未定义。
此函数也可使用 writeUint32BE 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeUInt32BE(0xfeedface, 0)
console.log(buf)
// 打印：<Buffer fe ed fa ce>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeUInt32BE(0xfeedface, 0)
console.log(buf)
// 打印：<Buffer fe ed fa ce>buf.writeUInt32LE(value[, offset])
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.writeUint32LE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将偏移量转换为 uint32。 |
| v0.5.5 | 新增于：v0.5.5 |
value<整数> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 \<= offset \<= buf.length - 4。默认值：0。- 返回值: <整数>
offset加上写入的字节数。
以小端序方式将 value 写入 buf 指定的 offset 处。value 必须是有效的无符号 32 位整数。当 value 不是无符号 32 位整数时，行为未定义。
此函数也可通过 writeUint32LE 别名使用。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(4)
buf.writeUInt32LE(0xfeedface, 0)
console.log(buf)
// 输出：<Buffer ce fa ed fe>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(4)
buf.writeUInt32LE(0xfeedface, 0)
console.log(buf)
// 输出：<Buffer ce fa ed fe>buf.writeUIntBE(value, offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.writeUintBE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将 offset 和 byteLength 转换为 uint32。 |
| v0.5.5 | 新增于：v0.5.5 |
value<整数> 将写入buf的数字。offset<整数> 开始写入前要跳过的字节数。必须满足0 <= offset <= buf.length - byteLength。byteLength<整数> 要写入的字节数。必须满足0 < byteLength <= 6。- 返回值: <整数>
offset加上写入的字节数。
以大端序将 value 的 byteLength 字节写入 buf 的指定 offset 位置。支持高达 48 位的精度。当 value 不是无符号整数时，行为未定义。
此函数也可使用 writeUintBE 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(6)
buf.writeUIntBE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer 12 34 56 78 90 ab>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(6)
buf.writeUIntBE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer 12 34 56 78 90 ab>buf.writeUIntLE(value, offset, byteLength)
[历史]
| 版本 | 变更 |
|---|---|
| v14.9.0, v12.19.0 | 此函数也可作为 buf.writeUintLE() 使用。 |
| v10.0.0 | 移除了 noAssert，并且不再隐式强制将 offset 和 byteLength 转换为 uint32。 |
| v0.5.5 | v0.5.5 版本中添加 |
value<整数> 要写入buf的数字。offset<整数> 开始写入之前要跳过的字节数。必须满足0 \<= offset \<= buf.length - byteLength。byteLength<整数> 要写入的字节数。必须满足0 \< byteLength \<= 6。- 返回值: <整数>
offset加上写入的字节数。
将 value 的 byteLength 字节以小端序写入 buf 中指定的 offset 处。支持最多 48 位精度。当 value 为非无符号整数时，行为未定义。
此函数也可使用 writeUintLE 别名。
js
import { Buffer } from 'node:buffer'
const buf = Buffer.allocUnsafe(6)
buf.writeUIntLE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer ab 90 78 56 34 12>js
const { Buffer } = require('node:buffer')
const buf = Buffer.allocUnsafe(6)
buf.writeUIntLE(0x1234567890ab, 0, 6)
console.log(buf)
// 输出：<Buffer ab 90 78 56 34 12>new Buffer(array)
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 从 node_modules 目录之外的代码调用此构造函数会发出弃用警告。 |
| v7.2.1 | 调用此构造函数不再发出弃用警告。 |
| v7.0.0 | 调用此构造函数现在会发出弃用警告。 |
| v6.0.0 | 自 v6.0.0 起已弃用 |
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用：请改用 Buffer.from(array)。
array<整数数组> 要从中复制的字节数组。
new Buffer(arrayBuffer[, byteOffset[, length]])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 从 node_modules 目录之外的代码调用此构造函数会发出弃用警告。 |
| v7.2.1 | 调用此构造函数不再发出弃用警告。 |
| v7.0.0 | 调用此构造函数现在会发出弃用警告。 |
| v6.0.0 | 现在支持 byteOffset 和 length 参数。 |
| v6.0.0 | 自 v6.0.0 起已弃用 |
| v3.0.0 | 新增于: v3.0.0 |
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用：请改用 Buffer.from(arrayBuffer[, byteOffset[, length]])。
arrayBuffer<ArrayBuffer> | <SharedArrayBuffer> 一个ArrayBuffer，SharedArrayBuffer或TypedArray的.buffer属性。byteOffset<整数> 要公开的第一个字节的索引。默认值:0。length<整数> 要公开的字节数。默认值:arrayBuffer.byteLength - byteOffset。
参见 Buffer.from(arrayBuffer[, byteOffset[, length]])。
new Buffer(buffer)
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 当从 node_modules 目录之外的代码中运行此构造函数时，会发出弃用警告。 |
| v7.2.1 | 调用此构造函数不再发出弃用警告。 |
| v7.0.0 | 调用此构造函数现在会发出弃用警告。 |
| v6.0.0 | 自 v6.0.0 起已弃用 |
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用：请改用 Buffer.from(buffer)。
buffer<Buffer> | <Uint8Array> 用于复制数据的现有Buffer或Uint8Array。
new Buffer(size)
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 当从 node_modules 目录之外的代码中运行此构造函数时，会发出弃用警告。 |
| v8.0.0 | new Buffer(size) 默认将返回零填充的内存。 |
| v7.2.1 | 调用此构造函数不再发出弃用警告。 |
| v7.0.0 | 调用此构造函数现在会发出弃用警告。 |
| v6.0.0 | 自 v6.0.0 起已弃用 |
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用：请改用 Buffer.alloc()（另请参见 Buffer.allocUnsafe()）。
size<整数> 新Buffer的所需长度。
参见 Buffer.alloc() 和 Buffer.allocUnsafe()。此构造函数变体等效于 Buffer.alloc()。
new Buffer(string[, encoding])
[历史]
| 版本 | 变更 |
|---|---|
| v10.0.0 | 从 node_modules 目录之外的代码调用此构造函数会发出弃用警告。 |
| v7.2.1 | 调用此构造函数不再发出弃用警告。 |
| v7.0.0 | 调用此构造函数现在会发出弃用警告。 |
| v6.0.0 | 自 v6.0.0 起已弃用 |
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用：请改用 Buffer.from(string[, encoding])。
参见 Buffer.from(string[, encoding])。
类: File
[历史]
| 版本 | 变更 |
|---|---|
| v23.0.0 | 使 File 实例可克隆。 |
| v20.0.0 | 不再是实验性功能。 |
| v19.2.0, v18.13.0 | 新增于：v19.2.0, v18.13.0 |
- 扩展自：<Blob>
File 提供有关文件的信息。
new buffer.File(sources, fileName[, options])
新增于：v19.2.0, v18.13.0
sources<string[]> | <ArrayBuffer[]> | <TypedArray[]> | <DataView[]> | <Blob[]> | <File[]> 一个字符串、<ArrayBuffer>、<TypedArray>、<DataView>、<File> 或 <Blob> 对象的数组，或这些对象的任意组合，将存储在File中。fileName<string> 文件名。options<Object>
file.name
新增于：v19.2.0, v18.13.0
- 类型： <string>
File 的名称。
file.lastModified
新增于：v19.2.0, v18.13.0
- 类型： <number>
File 的最后修改日期。
node:buffer 模块 API
虽然 Buffer 对象作为全局对象可用，但还有一些与 Buffer 相关的 API 只能通过使用 require('node:buffer') 访问的 node:buffer 模块获得。
buffer.atob(data)
新增于：v15.13.0, v14.17.0
data<any> Base64 编码的输入字符串。
将 Base64 编码的数据字符串解码为字节，并使用 Latin-1 (ISO-8859-1) 将这些字节编码为字符串。
data 可以是任何可以强制转换为字符串的 JavaScript 值。
此函数仅为了与旧版 Web 平台 API 保持兼容而提供，不应在新的代码中使用，因为它们使用字符串来表示二进制数据，并且早于 JavaScript 中类型化数组的引入。对于使用 Node.js API 运行的代码，Base64 编码字符串和二进制数据之间的转换应使用 Buffer.from(str, 'base64') 和 buf.toString('base64') 执行。
buffer.btoa(data)
新增于：v15.13.0, v14.17.0
[稳定性：3 - 遗留]
稳定性：3 - 遗留。请改用 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)
新增于：v19.6.0, v18.15.0
- input <Buffer> | <ArrayBuffer> | <TypedArray> 要验证的输入。
- 返回值：<boolean>
如果 input 只包含有效的 ASCII 编码数据（包括 input 为空的情况），则此函数返回 true。
如果 input 是一个分离的数组缓冲区，则抛出异常。
buffer.isUtf8(input)
新增于: v19.4.0, v18.14.0
- input <Buffer> | <ArrayBuffer> | <TypedArray> 待验证的输入。
- 返回值: <boolean>
如果 input 只包含有效的 UTF-8 编码数据，则此函数返回 true，包括 input 为空的情况。
如果 input 是一个分离的数组缓冲区，则抛出错误。
buffer.INSPECT_MAX_BYTES
新增于: v0.5.4
- <integer> 默认值:
50
返回调用 buf.inspect() 时将返回的字节最大数量。用户模块可以覆盖此值。有关 buf.inspect() 行为的更多详细信息，请参阅 util.inspect()。
buffer.kMaxLength
新增于: v3.0.0
- <整数> 单个
Buffer实例允许的最大大小。
[buffer.constants.MAX_LENGTH](/zh/api/buffer#bufferconstantsmax_length) 的别名。
buffer.kStringMaxLength
新增于: v3.0.0
- <整数> 单个
string实例允许的最大长度。
[buffer.constants.MAX_STRING_LENGTH](/zh/api/buffer#bufferconstantsmax_string_length) 的别名。
buffer.resolveObjectURL(id)
新增于: v16.7.0
解析 'blob:nodedata:...' 为使用先前调用 URL.createObjectURL() 注册的关联 <Blob> 对象。
buffer.transcode(source, fromEnc, toEnc)
[历史]
| 版本 | 变更 |
|---|---|
| v8.0.0 | source 参数现在可以是 Uint8Array。 |
| v7.1.0 | v7.1.0 版本中添加 |
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'。
如果给定的字节序列无法在目标编码中充分表示，则转换过程将使用替换字符。例如：
js
import { Buffer, transcode } from 'node:buffer'
const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii')
console.log(newBuf.toString('ascii'))
// 输出：'?'js
const { Buffer, transcode } = require('node:buffer')
const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii')
console.log(newBuf.toString('ascii'))
// 输出：'?'由于欧元符号 (€) 在 US-ASCII 中无法表示，因此它在转换后的 Buffer 中被替换为 ?。
类: SlowBuffer
已弃用自: v6.0.0
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用: 请改用 Buffer.allocUnsafeSlow()。
参见 Buffer.allocUnsafeSlow()。这从某种意义上说从未是一个类，因为构造函数始终返回一个 Buffer 实例，而不是 SlowBuffer 实例。
new SlowBuffer(size)
已弃用自: v6.0.0
[稳定性: 0 - 已弃用]
稳定性: 0 稳定性: 0 - 已弃用: 请改用 Buffer.allocUnsafeSlow()。
size<整数> 新SlowBuffer的所需长度。
Buffer 常量
新增于：v8.2.0
buffer.constants.MAX_LENGTH
[历史记录]
| 版本 | 变更 |
|---|---|
| v22.0.0 | 在 64 位架构上，值更改为 2 - 1。 |
| v15.0.0 | 在 64 位架构上，值更改为 2。 |
| v14.0.0 | 在 64 位架构上，值从 2 - 1 更改为 2 - 1。 |
| v8.2.0 | 新增于：v8.2.0 |
- <整数> 单个
Buffer实例允许的最大大小。
在 32 位架构上，此值当前为 2 - 1（约 1 GiB）。
在 64 位架构上，此值当前为 2 - 1（约 8 PiB）。
它反映了底层的 v8::TypedArray::kMaxLength。
此值也可作为 buffer.kMaxLength 使用。
buffer.constants.MAX_STRING_LENGTH
新增于：v8.2.0
- <整数> 单个
string实例允许的最大长度。
表示 string 原型可以拥有的最大 length，以 UTF-16 代码单元计。
此值可能取决于正在使用的 JS 引擎。
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 命令行选项
新增于：v5.10.0
Node.js 可以使用 --zero-fill-buffers 命令行选项启动，使所有新分配的 Buffer 实例在创建时默认填充零。如果没有此选项，使用 Buffer.allocUnsafe()、Buffer.allocUnsafeSlow() 和 new SlowBuffer(size) 创建的缓冲区不会填充零。使用此标志可能会对性能产生可衡量的负面影响。仅在需要强制新分配的 Buffer 实例不能包含可能敏感的旧数据时才使用 --zero-fill-buffers 选项。
bash
$ 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() 具有明显的性能优势，但必须格外小心，以避免在应用程序中引入安全漏洞。