Buffer
History
稳定性：2 - 稳定
Buffer 对象用于表示固定长度的字节序列。许多 Node.js API 支持 Buffer。
Buffer 类是 JavaScript 的 Uint8Array 类的子类，并使用涵盖额外用例的方法扩展了它。只要支持 Buffer 的地方，Node.js API 也接受普通的 Uint8Array。
虽然 Buffer 类在全局作用域内可用，但仍建议通过 import 或 require 语句显式引用它。
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');
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');
在 Buffer 和字符串之间转换时，可以指定字符编码。如果未指定字符编码，将使用 UTF-8 作为默认值。
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>
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 buffer 接受它们接收到的编码字符串的所有大小写变体。例如，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, Section 5 中指定的"URL 和文件名安全字母表"。base64 编码字符串中包含的空格字符（如空格、制表符和换行符）将被忽略。 -
'base64url'：RFC 4648, Section 5 中指定的 base64url 编码。当从字符串创建Buffer时，此编码还将正确接受常规 base64 编码的字符串。当将Buffer编码为字符串时，此编码将省略填充。 -
'hex'：将每个字节编码为两个十六进制字符。当解码不完全由偶数个十六进制字符组成的字符串时，可能会发生数据截断。参见下面的示例。
还支持以下遗留字符编码：
-
'ascii'：仅用于 7 位 ASCII 数据。当将字符串编码为Buffer时，这等同于使用'latin1'。当将Buffer解码为字符串时，使用此编码将在作为'latin1'解码之前额外取消设置每个字节的最高位。通常，没有理由使用此编码，因为'utf8'（或者，如果已知数据始终仅为 ASCII，则'latin1'）在编码或解码仅 ASCII 文本时将是更好的选择。它仅提供用于遗留兼容性。 -
'binary'：'latin1'的别名。此编码的名称可能具有误导性，因为此处列出的所有编码都在字符串和二进制数据之间转换。对于字符串和Buffer之间的转换，通常'utf8'是正确的选择。 -
'ucs2'、'ucs-2'：'utf16le'的别名。UCS-2 曾经指代不支持码点大于 U+FFFF 的字符的 UTF-16 变体。在 Node.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>，所有数据均已表示。
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' 编码可能会错误地解码字符。
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); // 输出：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); // 输出：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); // 输出：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); // 输出：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; // 复制 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>
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 的一部分。
import { Buffer } from 'node:buffer'; const arr = new Uint16Array(20); const buf = Buffer.from(arr.buffer, 0, 16); console.log(buf.length); // 输出：16
const { Buffer } = require('node:buffer'); const arr = new Uint16Array(20); const buf = Buffer.from(arr.buffer, 0, 16); console.log(buf.length); // 输出：16
Buffer.from() 和 TypedArray.from() 具有不同的签名和实现。具体来说，TypedArray 变体接受第二个参数，这是一个映射函数，在类型化数组的每个元素上调用：
但是，Buffer.from() 方法不支持使用映射函数：
- [
Buffer.from(array][] Buffer.from(buffer)Buffer.from(arrayBuffer[, byteOffset[, length]])Buffer.from(string[, encoding])
Buffer 原型上的所有方法都可以与 Uint8Array 实例一起调用。
const { toString, write } = Buffer.prototype; const uint8array = new Uint8Array(5); write.call(uint8array, 'hello', 0, 5, 'utf8'); // 5 // <Uint8Array 68 65 6c 6c 6f> toString.call(uint8array, 'utf8'); // 'hello'
Buffer 实例可以使用 for..of 语法进行迭代：
import { Buffer } from 'node:buffer'; const buf = Buffer.from([1, 2, 3]); for (const b of buf) { console.log(b); } // 输出： // 1 // 2 // 3
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
History
不再是实验性的。
Blob 封装了不可变的原始数据，可以安全地在多个工作线程之间共享。
buffer.Blob Constructor
History
添加了标准的 endings 选项以替换行尾，并移除了非标准的 encoding 选项。
new buffer.Blob(sources?, options?): void
string[] | ArrayBuffer[] | TypedArray[] | DataView[] | Blob[]创建一个新的 Blob 对象，包含给定源的连接。
ArrayBuffer、TypedArray、DataView 和 Buffer 源被复制到
'Blob' 中，因此可以在创建 'Blob' 后安全地修改它们。
字符串源被编码为 UTF-8 字节序列并复制到 Blob 中。 每个字符串部分中不匹配的代理对将被 Unicode U+FFFD 替换字符替换。
blob.arrayBuffer(): void
- 返回：
Promise
返回一个 promise，该 promise 履行时包含 Blob 数据副本的 ArrayBuffer。
blob.bytes(): void
- 返回：
Promise
blob.bytes() 方法以 Promise<Uint8Array> 的形式返回 Blob 对象的字节。
const blob = new Blob(['hello']); blob.bytes().then((bytes) => { console.log(bytes); // 输出：Uint8Array(5) [ 104, 101, 108, 108, 111 ] });
大小
History
Blob 的总大小（以字节为单位）。
切片
History
创建并返回一个新的 Blob，包含此 Blob 对象
数据的子集。原始 Blob 不会被更改。
流
History
返回一个新的 ReadableStream，允许读取 Blob 的内容。
文本
History
- 返回：
Promise
返回一个 promise，该 promise 履行时包含解码为
UTF-8 字符串的 Blob 内容。
流文本
History
返回一个新的 ReadableStream，允许将 Blob 的内容作为 UTF-8 解码字符串的流来读取。它等同于通过一个设置为 UTF-8 的 TextDecoderStream 对 blob.stream() 进行管道传输。
类型
History
- 类型：
string
Blob 的内容类型。
一旦创建了 Blob 对象，就可以通过 MessagePort 发送到多个
目的地，而无需传输或立即复制数据。Blob 包含的数据仅在调用 arrayBuffer() 或 text()
方法时复制。
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);
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 类是一个用于直接处理二进制数据的全局类型。
它可以通过多种方式构造。
分配一个 size 字节的新 Buffer。如果 fill 是 undefined，
Buffer 将被零填充。
import { Buffer } from 'node:buffer'; const buf = Buffer.alloc(5); console.log(buf); // 输出：<Buffer 00 00 00 00 00>
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，分配的 Buffer 将通过调用
buf.fill(fill) 进行初始化。
import { Buffer } from 'node:buffer'; const buf = Buffer.alloc(5, 'a'); console.log(buf); // 输出：<Buffer 61 61 61 61 61>
const { Buffer } = require('node:buffer'); const buf = Buffer.alloc(5, 'a'); console.log(buf); // 输出：<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); // 输出：<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); // 输出：<Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
调用 Buffer.alloc() 可能比替代方案
Buffer.allocUnsafe() 明显更慢，但能确保新创建的 Buffer 实例
内容永远不会包含来自先前分配的敏感数据，包括
可能未为 Buffer 分配的数据。
如果 size 不是数字，将抛出 TypeError。
分配一个 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); // 输出（内容可能不同）：<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>
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 实例，
大小为 Buffer.poolSize，用作快速分配新
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
池，而 Buffer.allocUnsafe(size).fill(fill) 会 使用内部
Buffer 池，如果 size 小于或等于 Buffer.poolSize 的一半。这
区别很微妙，但当应用程序需要
Buffer.allocUnsafe() 提供的额外性能时可能很重要。
分配一个 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 时为 32KiB）会从单个预分配的
Buffer 中切片获得。这使应用程序能够避免创建许多单独分配的
Buffer 实例所带来的垃圾回收开销。通过消除跟踪和清理大量单独的
ArrayBuffer 对象的需要，这种方法同时提升了性能和内存使用效率。
但是，如果开发者可能需要保留池中一小块
内存不确定的时间，使用 Buffer.allocUnsafeSlow() 创建未池化的 Buffer 实例
然后复制出相关的位可能是合适的。
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); } });
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])
History
传递无效的输入现在将抛出错误。
string 参数现在可以是任何 TypedArray、DataView或 ArrayBuffer。
string | Buffer | TypedArray | DataView | ArrayBuffer | SharedArrayBufferstringstring
是字符串，这是它的编码。
默认值：
'utf8'
。返回使用 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`); // 输出：½ + ¼ = ¾: 9 个字符，12 个字节
const { Buffer } = require('node:buffer'); const str = '\u00bd + \u00bc = \u00be'; console.log(`${str}: ${str.length} characters, ` + `${Buffer.byteLength(str, 'utf8')} bytes`); // 输出：½ + ¼ = ¾: 9 个字符，12 个字节
当 string 是 Buffer | DataView | TypedArray | ArrayBuffer | SharedArrayBuffer 时，
返回 .byteLength 报告的字节长度。
静态方法：Buffer.stringLength(input[, encoding])
History
返回对相同字节调用 buf.toString(encoding) 将生成的字符串的 UTF-16 代码单元长度，而不对其进行解码。这是 Buffer.byteLength() 的对应方法，后者返回字符串编码后所需的字节数。
对于 'utf8'，无效字节序列按照解码时的方式计数：每个最长的无效子序列会变成一个 U+FFFD 替换字符。对于所有其他编码，结果仅根据 input.byteLength 计算。
已分离的 ArrayBuffer 或由其支持的 TypedArray 会被视为空值。
结果不会被限制：解码前请将其与 buffer.constants.MAX_STRING_LENGTH 比较，以判断解码是否能够成功。包含 n 个代码单元的字符串占用 n 到 2 * n 字节的内存。
import { Buffer, constants } from 'node:buffer'; const buf = Buffer.from('€ 100', 'utf8'); console.log(Buffer.stringLength(buf)); // 打印：5 console.log(Buffer.stringLength(buf, 'hex')); // 打印：14 console.log(Buffer.stringLength(buf) <= constants.MAX_STRING_LENGTH); // 打印：true
const { Buffer, constants } = require('node:buffer'); const buf = Buffer.from('€ 100', 'utf8'); console.log(Buffer.stringLength(buf)); // 打印：5 console.log(Buffer.stringLength(buf, 'hex')); // 打印：14 console.log(Buffer.stringLength(buf) <= constants.MAX_STRING_LENGTH); // 打印：true
静态方法：Buffer.compare(buf1, buf2)
History
参数现在可以是 Uint8Array。
比较 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)); // 输出：[ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ] // (此结果等于：[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)); // 输出：[ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ] // (此结果等于：[buf2, buf1]。)
静态方法：Buffer.concat(list[, totalLength])
History
list 的元素现在可以是 Uint8Array。
Buffer[] | Uint8Array[]Buffer
或
Uint8Array
实例列表。integerlist
中
Buffer
实例连接后的总长度。返回一个新的 Buffer，它是连接 list 中所有 Buffer
实例的结果。
如果列表没有项，或者 totalLength 为 0，则返回一个新的零长度
Buffer。
如果未提供 totalLength，它是通过相加 list 中 Buffer 实例
的长度计算得出的。
如果提供了 totalLength，它必须是无符号整数。如果
list 中 Buffer 的组合长度超过 totalLength，结果将被
截断为 totalLength。如果 list 中 Buffer 的组合长度
小于 totalLength，剩余空间将填充零。
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); // 输出：42
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); // 输出：42
Buffer.concat() 也可能像
Buffer.allocUnsafe() 一样使用内部 Buffer 池。
静态方法：Buffer.copyBytesFrom(view[, offset[, length]])
History
TypedArrayTypedArray
。integerview
内的起始偏移量。
默认值：
0
。integerview
复制的元素数量。
默认值：
view.length - offset
。将 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)
History
integer[]使用范围在 0 – 255 的字节 array 分配一个新的 Buffer。
超出该范围的数组条目将被截断以适应。
import { Buffer } from 'node:buffer'; // 创建一个新的 Buffer，包含字符串 'buffer' 的 UTF-8 字节。 const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
const { Buffer } = require('node:buffer'); // 创建一个新的 Buffer，包含字符串 'buffer' 的 UTF-8 字节。 const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
如果 array 是类 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]])
History
ArrayBuffer | SharedArrayBufferinteger0
。integerarrayBuffer.byteLength - byteOffset
。这会创建 ArrayBuffer 的视图，而不会复制底层
内存。例如，当传递 TypedArray 实例的 .buffer 属性的引用时，新创建的 Buffer 将与 TypedArray 的底层 ArrayBuffer 共享相同的
分配内存。
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>
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 共享的内存范围。
import { Buffer } from 'node:buffer'; const ab = new ArrayBuffer(10); const buf = Buffer.from(ab, 0, 2); console.log(buf.length); // 输出：2
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 的范围：
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>
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)
History
Buffer | Uint8ArrayBuffer
或
Uint8Array
，从中
复制数据。将传入的 buffer 数据复制到新的 Buffer 实例。
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()); // 输出：buffer
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]])
History
对于 valueOf() 函数返回值不严格等于
object 的对象，返回 Buffer.from(object.valueOf(), offsetOrEncoding, length)。
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>
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)。
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>
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])
History
创建一个新的包含 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()); // 输出：this is a tést console.log(buf2.toString()); // 输出：this is a tést console.log(buf1.toString('latin1')); // 输出：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()); // 输出：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)
History
Object如果 obj 是 Buffer，则返回 true，否则返回 false。
import { Buffer } from 'node:buffer'; Buffer.isBuffer(Buffer.alloc(10)); // 真 Buffer.isBuffer(Buffer.from('foo')); // 真 Buffer.isBuffer('a string'); // 假 Buffer.isBuffer([]); // 假 Buffer.isBuffer(new Uint8Array(1024)); // 假
const { Buffer } = require('node:buffer'); Buffer.isBuffer(Buffer.alloc(10)); // 真 Buffer.isBuffer(Buffer.from('foo')); // 真 Buffer.isBuffer('a string'); // 真 Buffer.isBuffer([]); // 假 Buffer.isBuffer(new Uint8Array(1024)); // 假
静态方法：Buffer.isEncoding(encoding)
History
string如果 encoding 是受支持的字符编码名称，则返回 true，
否则返回 false。
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('')); // 输出：false
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
16 位整数数组
History
默认值已从 8192 提高到 65536。
- 类型：
integer默认值：65536
这是用于池化的预分配内部 Buffer 实例的大小（以字节为单位）。此值可以被修改。
integer索引运算符 [index] 可用于获取和设置 buf 中位置
index 处的字节。值指单个字节，因此合法值
范围在 0x00 和 0xFF（十六进制）或 0 和 255（十进制）之间。
此运算符继承自 Uint8Array，因此其越界
访问的行为与 Uint8Array 相同。换句话说，当 index 为负数或大于或等于 buf.length 时，buf[index] 返回
undefined，如果 index 为负数或
>= buf.length，buf[index] = value 不会修改 buffer。
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.js
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.js
- 类型：
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); // 输出：true
const { Buffer } = require('node:buffer'); const arrayBuffer = new ArrayBuffer(16); const buffer = Buffer.from(arrayBuffer); console.log(buffer.buffer === arrayBuffer); // 输出：true
- 类型：
integerBuffer底层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'; // 创建一个小于 `Buffer.poolSize` 的 buffer。 const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // 当将 Node.js Buffer 转换为 Int8Array 时，使用 byteOffset // 仅引用 `nodeBuffer.buffer` 中包含 // `nodeBuffer` 内存的部分。 new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);
const { Buffer } = require('node:buffer'); // 创建一个小于 `Buffer.poolSize` 的 buffer。 const nodeBuffer = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // 当将 Node.js Buffer 转换为 Int8Array 时，使用 byteOffset // 仅引用 `nodeBuffer.buffer` 中包含 // `nodeBuffer` 内存的部分。 new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);
buf.compare(target, targetStart?, targetEnd?, sourceStart?, sourceEnd?): void
Buffer | Uint8Arrayintegertarget
内开始比较的偏移量。
默认值：
0
。integertarget
内结束比较的偏移量
（不包含）。
默认值：
target.length
。integerbuf
内开始比较的偏移量。
默认值：
0
。integerbuf
内结束比较的偏移量
（不包含）。
默认值：
buf.length
。比较 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)); // 输出：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]。)
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 内的特定范围。
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)); // 输出：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)); // 输出：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?): void
Buffer | Uint8ArrayBuffer
或
Uint8Array
。integertarget
内开始写入的偏移量。
默认值：
0
。integerbuf
内开始复制的偏移量。
默认值：
0
。integerbuf
内停止复制的偏移量（不
包含）。
默认值：
buf.length
。将数据从 buf 的一个区域复制到 target 中的一个区域，即使 target
内存区域与 buf 重叠。
TypedArray.prototype.set() 执行相同的操作，并且可用于
所有 TypedArrays，包括 Node.js Buffer，尽管它采用
不同的函数参数。
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!!!!!!!!!!!!!
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!!!!!!!!!!!!!
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()); // 输出：efghijghijklmnopqrstuvwxyz
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()); // 输出：efghijghijklmnopqrstuvwxyz
buf.entries(): void
- 返回：
Iterator
从 buf 的内容创建并返回一个 [index, byte] 对的 [迭代器][]。
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]
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): void
Buffer | Uint8Array如果 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)); // 输出：true console.log(buf1.equals(buf3)); // 输出：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)); // 输出：true console.log(buf1.equals(buf3)); // 输出：false
buf.fill(value, offset?, end?, encoding?): void
string | Buffer | Uint8Array | integerbuf
的值。
空值（字符串、Uint8Array、Buffer）被强制转换为
0
。integerbuf
之前要跳过的字节数。
默认值：
0
。integerbuf
的位置（不包含）。
默认值：
buf.length
。stringvalue
是字符串，这是它的编码。
默认值：
'utf8'
。使用指定的 value 填充 buf。如果未提供 offset 和 end，
整个 buf 将被填充：
import { Buffer } from 'node:buffer'; // 用 ASCII 字符 'h' 填充 `Buffer`。 const b = Buffer.allocUnsafe(50).fill('h'); console.log(b.toString()); // 输出：hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh // 用空字符串填充 buffer const c = Buffer.allocUnsafe(5).fill(''); console.log(c.fill('')); // 输出：<Buffer 00 00 00 00 00>
const { Buffer } = require('node:buffer'); // 用 ASCII 字符 'h' 填充 `Buffer`。 const b = Buffer.allocUnsafe(50).fill('h'); console.log(b.toString()); // 输出：hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh // 用空字符串填充 buffer 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 的字节：
import { Buffer } from 'node:buffer'; // 用 UTF-8 中占用两个字节的字符填充 `Buffer`。 console.log(Buffer.allocUnsafe(5).fill('\u0222')); // 输出：<Buffer c8 a2 c8 a2 c8>
const { Buffer } = require('node:buffer'); // 用 UTF-8 中占用两个字节的字符填充 `Buffer`。 console.log(Buffer.allocUnsafe(5).fill('\u0222')); // 输出：<Buffer c8 a2 c8 a2 c8>
如果 value 包含无效字符，它将被截断；如果没有剩余的有效
填充数据，将抛出异常：
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')); // 抛出异常。
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, start?, end?, encoding?): void
等同于 buf.indexOf() !== -1。
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)); // 输出：false
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)); // 输出：false
buf.indexOf(value, start?, end?, encoding?): void
如果 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')); // 输出：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
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，则将搜索整个 buffer。此
行为与 String.prototype.indexOf() 相匹配。
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)); // 传递一个强制转换为 NaN 或 0 的 byteOffset。 // 输出：1，搜索整个 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'); // 传递一个数字值，但不是有效的字节。 // 打印：2，相当于搜索 99 或 'c'。 console.log(b.indexOf(99.9)); console.log(b.indexOf(256 + 99)); // 传递一个被强制转换为 NaN 或 0 的 byteOffset。 // 打印：1，搜索整个 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(): void
- 返回值：
Iterator
创建并返回一个 [迭代器][]，其中包含 buf 的键（索引）。
import { Buffer } from 'node:buffer'; const buf = Buffer.from('buffer'); for (const key of buf.keys()) { console.log(key); } // 打印： // 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); } // 打印： // 0 // 1 // 2 // 3 // 4 // 5
buf.lastIndexOf(value, start?, end?, encoding?): void
与 buf.indexOf() 相同，只不过找到的是 value 的最后一次出现而不是第一次出现。
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')); // 打印：4
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() 匹配。
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，搜索整个 buffer。 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', []));
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，搜索整个 buffer。 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。
- 类型：
integer
返回 buf 中的字节数。
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); // 打印：1234
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); // 打印：1234
稳定性：0 - 已弃用：请改用
buf.buffer。
buf.parent 属性是 buf.buffer 的已弃用别名。
buf.readBigInt64BE(offset?): void
整数0 <= offset <= buf.length - 8
。
默认值：
0
。从 buf 中指定的 offset 处读取一个有符号的大端 64 位整数。
从 Buffer 读取的整数被解释为二进制补码有符号值。
buf.readBigInt64LE(offset?): void
integer0 <= offset <= buf.length - 8
。
默认值：
0
。从 buf 中指定的 offset 处读取一个有符号的小端 64 位整数。
从 Buffer 读取的整数被解释为二进制补码有符号值。
buf.readBigUInt64BE
History
此函数也可通过 buf.readBigUint64BE() 使用。
buf.readBigUInt64BE(offset?): void
integer0 <= offset <= buf.length - 8
。
默认值：
0
。从 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)); // 输出：4294967295n
const { Buffer } = require('node:buffer'); const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]); console.log(buf.readBigUInt64BE(0)); // 输出：4294967295n
buf.readBigUInt64LE
History
此函数也可作为 buf.readBigUint64LE() 使用。
buf.readBigUInt64LE(offset?): void
整数0 <= offset <= buf.length - 8
。
默认值：
0
。从 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)); // 打印：18446744069414584320n
const { Buffer } = require('node:buffer'); const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]); console.log(buf.readBigUInt64LE(0)); // 打印：18446744069414584320n
Buffer.prototype.readDoubleBE
History
移除了 noAssert，并且不再隐式地将 offset 强制转换为 uint32。
integer0 <= offset <= buf.length - 8
。
默认值：
0
。从 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)); // 输出：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)); // 输出：8.20788039913184e-304
buf.readDoubleLE(offset?): void
integer0 <= offset <= buf.length - 8
。
默认值：
0
。从 buf 中指定的 offset 处读取一个 64 位小端 double 值。
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。
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?): void
integer0 <= offset <= buf.length - 4
。
默认值：
0
。从 buf 中指定的 offset 处读取一个 32 位大端浮点数。
import { Buffer } from 'node:buffer'; const buf = Buffer.from([1, 2, 3, 4]); console.log(buf.readFloatBE(0)); // 打印：2.387939260590663e-38
const { Buffer } = require('node:buffer'); const buf = Buffer.from([1, 2, 3, 4]); console.log(buf.readFloatBE(0)); // 打印：2.387939260590663e-38
buffer.readFloatLE
History
移除了 noAssert，并且不再将 offset 隐式强制转换为 uint32。
buffer.readFloatLE(offset): void
integer0 <= offset <= buf.length - 4
。
默认值：
0
。从 buf 中指定的 offset 处读取一个 32 位小端浮点值。
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。
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?): void
integer0 <= offset <= buf.length - 1
。
默认值：
0
。从 buf 中指定的 offset 处读取一个有符号 8 位整数。
从 Buffer 读取的整数被解释为二进制补码有符号值。
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。
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?): void
integer0 <= offset <= buf.length - 2
。
默认值：
0
。从 buf 中指定的 offset 处读取一个有符号的大端序 16 位整数。
从 Buffer 中读取的整数将被解释为二进制补码有符号值。
import { Buffer } from 'node:buffer'; const buf = Buffer.from([0, 5]); console.log(buf.readInt16BE(0)); // 输出：5
const { Buffer } = require('node:buffer'); const buf = Buffer.from([0, 5]); console.log(buf.readInt16BE(0)); // 输出：5
buf.readInt16LE(offset?): void
整数0 <= offset <= buf.length - 2
。
默认值：
0
。从 buf 中指定的 offset 处读取一个有符号的小端 16 位整数。
从 Buffer 读取的整数被解释为二进制补码有符号值。
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。
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?): void
integer0 <= offset <= buf.length - 4
。
默认值：
0
。从 buf 中指定的 offset 处读取一个有符号的大端序 32 位整数。
从 Buffer 中读取的整数将被解释为二进制补码有符号值。
import { Buffer } from 'node:buffer'; const buf = Buffer.from([0, 0, 0, 5]); console.log(buf.readInt32BE(0)); // 输出：5
const { Buffer } = require('node:buffer'); const buf = Buffer.from([0, 0, 0, 5]); console.log(buf.readInt32BE(0)); // 输出：5
buf.readInt32LE(offset?): void
integer0 <= offset <= buf.length - 4
。
默认值：
0
。从 buf 中指定的 offset 处读取一个有符号的小端 32 位整数。
从 Buffer 读取的整数被解释为二进制补码有符号值。
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。
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
History
支持 Uint8Array 作为 this 值。
移除了 noAssert，并且不再将 offset 和 byteLength 隐式强制转换为 uint32。
buf.readIntBE(offset, byteLength): void
整数0 <= offset <= buf.length - byteLength
。整数0 < byteLength <= 6
。从 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)); // 输出：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。
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
History
支持 Uint8Array 作为 this 值。
移除了 noAssert，并且不再将 offset 和 byteLength 隐式强制转换为 uint32。
buf.readIntLE(offset, byteLength): void
整数0 <= offset <= buf.length - byteLength
。整数0 < byteLength <= 6
。从 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)); // 输出：-546f87a9cbee
const { Buffer } = require('node:buffer'); const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); console.log(buf.readIntLE(0, 6).toString(16)); // 输出：-546f87a9cbee
buf.readUInt8(offset?): void
整数0 <= offset <= buf.length - 1
。
默认值：
0
。从 buf 中指定的 offset 处读取一个无符号 8 位整数。
此函数也可通过 readUint8 别名使用。
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。
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?): void
整数0 <= offset <= buf.length - 2
。
默认值：
0
。从 buf 中指定的 offset 处读取一个无符号的大端 16 位整数。
此函数也可通过 readUint16BE 别名使用。
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)); // 输出：3456
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)); // 输出：3456
buf.readUInt16LE(offset?): void
整数0 <= offset <= buf.length - 2
。
默认值：
0
。从 buf 中指定的 offset 处读取一个无符号的小端 16 位整数。
此函数也可通过 readUint16LE 别名使用。
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。
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?): void
整数0 <= offset <= buf.length - 4
。
默认值：
0
。从 buf 中指定的 offset 处读取一个无符号的大端 32 位整数。
此函数也可通过 readUint32BE 别名使用。
import { Buffer } from 'node:buffer'; const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]); console.log(buf.readUInt32BE(0).toString(16)); // 输出：12345678
const { Buffer } = require('node:buffer'); const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]); console.log(buf.readUInt32BE(0).toString(16)); // 输出：12345678
buf.readUInt32LE(offset?): void
整数0 <= offset <= buf.length - 4
。
默认值：
0
。从 buf 中指定的 offset 处读取一个无符号的小端 32 位整数。
此函数也可通过 readUint32LE 别名使用。
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。
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): void
整数0 <= offset <= buf.length - byteLength
。整数0 < byteLength <= 6
。从 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)); // 输出：1234567890ab console.log(buf.readUIntBE(1, 6).toString(16)); // 抛出 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)); // 输出：1234567890ab console.log(buf.readUIntBE(1, 6).toString(16)); // 抛出 ERR_OUT_OF_RANGE。
buf.readUIntLE(offset, byteLength): void
整数0 <= offset <= buf.length - byteLength
。整数0 < byteLength <= 6
。从 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)); // 输出：ab9078563412
const { Buffer } = require('node:buffer'); const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]); console.log(buf.readUIntLE(0, 6).toString(16)); // 输出：ab9078563412
buf.subarray(start?, end?): void
返回一个新的 Buffer，它引用与原始对象相同的内存，但根据 start 和 end 索引进行偏移和裁剪。
指定大于 buf.length 的 end 将返回与 end 等于 buf.length 相同的结果。
此方法继承自 TypedArray.prototype.subarray()。
修改新的 Buffer 切片将修改原始 Buffer 中的内存，因为这两个对象分配的内存是重叠的。
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)); // 输出：!bc
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 的末尾而不是开头生成。
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)。）
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?): void
稳定性：0 - 已弃用：请改用
buf.subarray。
返回一个新的 Buffer，它引用与原始对象相同的内存，但由 start 和 end 索引进行偏移和裁剪。
此方法与 Uint8Array.prototype.slice() 不兼容，后者是 Buffer 的超类。要复制切片，请使用 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()); // 输出：cuffer console.log(buf.toString()); // 输出：buffer // 使用 buf.slice() 时，原始 buffer 会被修改。 const notReallyCopiedBuf = buf.slice(); notReallyCopiedBuf[0]++; console.log(notReallyCopiedBuf.toString()); // 输出：cuffer console.log(buf.toString()); // 也输出：cuffer (!)
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() 时，原始 buffer 会被修改。 const notReallyCopiedBuf = buf.slice(); notReallyCopiedBuf[0]++; console.log(notReallyCopiedBuf.toString()); // 输出：cuffer console.log(buf.toString()); // 也输出：cuffer (!)
buf.swap16(): void
- 返回值：
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); // 输出：<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。
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 大端之间执行快速就地转换：
import { Buffer } from 'node:buffer'; const buf = Buffer.from('This is little-endian UTF-16', 'utf16le'); buf.swap16(); // 转换为大端 UTF-16 文本。
const { Buffer } = require('node:buffer'); const buf = Buffer.from('This is little-endian UTF-16', 'utf16le'); buf.swap16(); // 转换为大端 UTF-16 文本。
buf.swap32(): void
- 返回值：
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); // 输出：<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。
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(): void
- 返回值：
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); // 输出：<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。
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(): void
- 返回值：
Object
返回 buf 的 JSON 表示。JSON.stringify() 在字符串化 Buffer 实例时会隐式调用此函数。
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); // 输出：{"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>
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?): void
string'utf8'
。integer0
。integerbuf.length
。根据 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 是 '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é
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(): void
- 返回值：
Iterator
创建并返回一个用于 buf 值（字节）的 iterator。当 Buffer 在 for..of 语句中使用时，此函数会自动调用。
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 // 114
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 // 114
buf.write(string, offset?, length?, encoding?): void
根据 encoding 中的字符编码将 string 写入 buf 的 offset 处。length 参数是要写入的字节数。如果 buf 没有足够的空间容纳整个字符串，则只会写入字符串的一部分。但是，部分编码的字符不会被写入。
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)}`); // 打印：12 bytes: ½ + ¼ = ¾ const buffer = Buffer.alloc(10); const length = buffer.write('abcd', 8); console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`); // 打印：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)}`); // 打印：12 bytes: ½ + ¼ = ¾ const buffer = Buffer.alloc(10); const length = buffer.write('abcd', 8); console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`); // 打印：2 bytes : ab
buffer.writeBigInt64BE(): void
将 value 以大端格式写入 buffer 的指定 offset 处。
value 会被解释并写入为二进制补码有符号整数。
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>
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>
bigint 的写入方法
History
将 value 以小端格式写入 buffer 的指定 offset 处。
value 被解释并写入为二进制补码有符号整数。
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>
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
History
此函数也可通过 buf.writeBigUint64BE() 使用。
buf.writeBigUInt64BE(value, offset?): void
以大端字节序格式将 value 写入 buf 中指定的 offset 位置。
此函数也可通过 writeBigUint64BE 别名使用。
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>
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
History
此函数也可作为 buf.writeBigUint64LE() 使用。
buf.writeBigUInt64LE(value, offset?): void
将 value 以小端格式写入 buf 的指定 offset 处。
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>
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?): void
以大端序将 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); // 输出：<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); // 输出：<Buffer 40 5e dd 2f 1a 9f be 77>
buf.writeDoubleLE(value, offset?): void
将 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); // 打印：<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); // 打印：<Buffer 77 be 9f 1a 2f dd 5e 40>
buf.writeFloatBE(value, offset?): void
将 value 以大端格式写入 buf 的指定 offset 处。当 value 不是 JavaScript 数字时，行为未定义。
import { Buffer } from 'node:buffer'; const buf = Buffer.allocUnsafe(4); buf.writeFloatBE(0xcafebabe, 0); console.log(buf); // 打印：<Buffer 4f 4a fe bb>
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?): void
将 value 以小端序写入 buf 中指定的 offset 处。当 value 不是 JavaScript 数字时，行为未定义。
import { Buffer } from 'node:buffer'; const buf = Buffer.allocUnsafe(4); buf.writeFloatLE(0xcafebabe, 0); console.log(buf); // 输出：<Buffer bb fe 4a 4f>
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?): void
将 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); // 输出：<Buffer 02 fe>
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?): void
将 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); // 输出：<Buffer 01 02>
const { Buffer } = require('node:buffer'); const buf = Buffer.allocUnsafe(2); buf.writeInt16BE(0x0102, 0); console.log(buf); // 输出：<Buffer 01 02>
buf.writeInt16LE(value, offset?): void
将 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); // 输出：<Buffer 04 03>
const { Buffer } = require('node:buffer'); const buf = Buffer.allocUnsafe(2); buf.writeInt16LE(0x0304, 0); console.log(buf); // 输出：<Buffer 04 03>
buf.writeInt32BE(value, offset?): void
将 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); // 输出：<Buffer 01 02 03 04>
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?): void
将 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); // 输出：<Buffer 08 07 06 05>
const { Buffer } = require('node:buffer'); const buf = Buffer.allocUnsafe(4); buf.writeInt32LE(0x05060708, 0); console.log(buf); // 输出：<Buffer 08 07 06 05>
buf.writeIntBE
History
已移除 noAssert，且不再隐式将 offset 和 byteLength 强制转换为 uint32。
buf.writeIntBE(value, offset, byteLength): void
将 value 的 byteLength 字节以大端序写入 buf 中指定的 offset
处。支持高达 48 位的精度。当 value 不是有符号整数时，
行为未定义。
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>
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
History
已移除 noAssert，且不再隐式将 offset 和 byteLength 强制转换为 uint32。
buf.writeIntLE(value, offset, byteLength): void
将 value 的 byteLength 字节以小端序写入 buf 中指定的 offset
处。支持高达 48 位的精度。当 value 不是有符号整数时，
行为未定义。
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>
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?): void
将 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); // 输出：<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); // 输出：<Buffer 03 04 23 42>
buf.writeUInt16BE(value, offset?): void
将 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); // 输出：<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); // 输出：<Buffer de ad be ef>
buf.writeUInt16LE(value, offset?): void
将 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); // 输出：<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); // 输出：<Buffer ad de ef be>
buf.writeUInt32BE(value, offset?): void
将 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); // 输出：<Buffer fe ed fa ce>
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?): void
以小端格式将 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); // 输出：<Buffer ce fa ed fe>
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): void
将 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); // 输出：<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); // 输出：<Buffer 12 34 56 78 90 ab>
buf.writeUIntLE(value, offset, byteLength): void
将 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); // 输出：<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); // 输出：<Buffer ab 90 78 56 34 12>
Buffer Constructor
History
在 node_modules 目录外的代码中运行时，调用此构造函数会发出弃用警告。
调用此构造函数不再发出弃用警告。
调用此构造函数现在会发出弃用警告。
new Buffer(array): void
稳定性：0 - 已弃用：请使用
Buffer.from(array)代替。
integer[]Buffer Constructor
History
在 node_modules 目录外的代码中运行时，调用此构造函数会发出弃用警告。
调用此构造函数不再发出弃用警告。
调用此构造函数现在会发出弃用警告。
byteOffset 和 length 参数现在受支持。
new Buffer(arrayBuffer, byteOffset?, length?): void
稳定性：0 - 已弃用：请使用
Buffer.from(arrayBuffer[, byteOffset[, length]])代替。
参见
Buffer.from(arrayBuffer[, byteOffset[, length]])
Buffer Constructor
History
在 node_modules 目录外的代码中运行时，调用此构造函数会发出弃用警告。
调用此构造函数不再发出弃用警告。
调用此构造函数现在会发出弃用警告。
new Buffer(buffer): void
稳定性：0 - 已弃用：请使用
Buffer.from(buffer)代替。
Buffer | Uint8ArrayBuffer
或
Uint8Array
，从中
复制数据。new Buffer(size): void
稳定性：0 - 已弃用：请使用
Buffer.alloc()代替（另见Buffer.allocUnsafe()）。
整数Buffer
所需的长度。参见 Buffer.alloc() 和 Buffer.allocUnsafe()。此变体的
构造函数等同于 Buffer.alloc()。
Buffer Constructor
History
在 node_modules 目录外的代码中运行时，调用此构造函数会发出弃用警告。
调用此构造函数不再发出弃用警告。
调用此构造函数现在会发出弃用警告。
new Buffer(string, encoding?): void
稳定性：0 - 已弃用： 请使用
Buffer.from(string[, encoding])代替。
参见 Buffer.from(string[, encoding])。
类：File
History
- 继承：
Blob
File 提供有关文件的信息。
构造函数
History
string[] | ArrayBuffer[] | TypedArray[] | DataView[] | Blob[] | File[]string属性
History
- 类型：
string
File 的名称。
属性
History
- 类型：
number
File 的最后修改日期。
虽然 Buffer 对象可作为全局对象使用，但还有额外的 Buffer 相关 API 仅可通过使用 require('node:buffer') 访问的 node:buffer 模块获得。
buffer.atob(data): void
稳定性：3 - 遗留。请改用
Buffer.from(data, 'base64')。
any将 Base64 编码的数据字符串解码为字节，并使用 Latin-1 (ISO-8859-1) 将这些字节编码为字符串。
data 可以是任何可强制转换为字符串的 JavaScript 值。
此函数仅提供用于与遗留 Web 平台 API 的兼容性，绝不应在新代码中使用，因为它们使用字符串来表示二进制数据，且早于 JavaScript 中类型数组的引入。对于使用 Node.js API 运行的代码，应在 Base64 编码字符串和二进制数据之间进行转换使用 Buffer.from(str, 'base64') 和 buf.toString('base64')。
提供自动迁移工具（来源）：
npx codemod@latest @nodejs/buffer-atob-btoa
buffer.btoa(data): void
稳定性：3 - 遗留。请改用
buf.toString('base64')。
any使用 Latin-1 (ISO-8859) 将字符串解码为字节，并使用 Base64 将这些字节编码为字符串。
data 可以是任何可强制转换为字符串的 JavaScript 值。
此函数仅用于与遗留 Web 平台 API 兼容，绝不应在新代码中使用，因为它们使用字符串表示二进制数据，并且早于 JavaScript 中类型数组的引入。对于使用 Node.js API 运行的代码，应在 Base64 编码字符串和二进制数据之间进行转换时使用 Buffer.from(str, 'base64') 和 buf.toString('base64')。
提供自动迁移工具（来源）：
npx codemod@latest @nodejs/buffer-atob-btoa
buffer.isAscii
History
分离的 ArrayBuffer 及由其支持的视图将被视为空。
buffer.isAscii(input): void
Buffer | ArrayBuffer | TypedArray如果 input 仅包含有效的 ASCII 编码数据（包括 input 为空的情况），则此函数返回 true。
分离的 ArrayBuffer，或由其支持的 TypedArray，将被视为空。
buffer.isLatin1(input): void
string如果 input 可以使用 Node.js 'latin1' 编码无损编码（包括 input 为空的情况），此函数将返回 true。也就是说，如果 input 中的每个 UTF-16 代码单元都在 U+0000 到 U+00FF 范围内，它就会返回 true。这样的字符串也是有效的 WebIDL ByteString。
此检查使用 Node.js 对 'latin1' 的定义，其中从 U+0000 到 U+00FF 的每个代码单元都直接映射到相同值的字节。它不使用 WHATWG Encoding Standard 的定义；在该定义中，'latin1' 标签是 windows-1252 的别名。例如，此函数会将 '\u0080' 视为 latin1，而不会将 '€'（U+20AC，windows-1252 将其编码为 0x80）视为 latin1。
与 buffer.isAscii() 和 buffer.isUtf8() 不同，此函数验证的是字符串，而不是 Buffer、TypedArray 或 ArrayBuffer。任何字节序列都必然是有效的 'latin1'，因为每个字节都映射到小于或等于 0xFF 的代码单元。
import { isLatin1 } from 'node:buffer'; isLatin1('hello'); // true isLatin1('café'); // true isLatin1('\u00ff'); // true isLatin1('\u0100'); // false isLatin1('€'); // false
const { isLatin1 } = require('node:buffer'); isLatin1('hello'); // true isLatin1('café'); // true isLatin1('\u00ff'); // true isLatin1('\u0100'); // false isLatin1('€'); // false
buffer.isUtf8
History
分离的 ArrayBuffer 及由其支持的视图将被视为空。
buffer.isUtf8(input): void
Buffer | ArrayBuffer | TypedArray如果 input 仅包含有效的 UTF-8 编码数据（包括 input 为空的情况），则此函数返回 true。
分离的 ArrayBuffer，或由其支持的 TypedArray，将被视为空。
- 类型：
integer默认值：50
返回调用 buf.inspect() 时将返回的最大字节数。用户可以覆盖此值。有关 buf.inspect() 行为的更多详细信息，请参阅 util.inspect()。
- 类型：
integer单个Buffer实例允许的最大大小。
buffer.constants.MAX_LENGTH 的别名。
- 类型：
integer单个string实例允许的最大长度。
buffer.constants.MAX_STRING_LENGTH 的别名。
buffer.resolveObjectURL(id): void
stringURL.createObjectURL()
返回的
'blob:nodedata:...
URL 字符串。解析一个 'blob:nodedata:...' URL 为关联的 Blob 对象，该对象是使用之前调用 URL.createObjectURL() 注册的。
buffer.transcode(source, fromEnc, toEnc): void
将给定的 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')); // 打印：'?'
const { Buffer, transcode } = require('node:buffer'); const newBuf = transcode(Buffer.from('€'), 'utf8', 'ascii'); console.log(newBuf.toString('ascii')); // 打印：'?'
因为欧元 (€) 符号在 US-ASCII 中无法表示，所以在转码后的 Buffer 中被替换为 ?。
Buffer 常量
History
- 类型：
integer单个Buffer实例允许的最大大小。
在 32 位架构上，此值等于 231 - 1（约 2 GiB）。
在 64 位架构上，此值等于 Number.MAX_SAFE_INTEGER（253 - 1，约 8 PiB）。
它在底层反映了 v8::Uint8Array::kMaxLength。
此值也可作为 buffer.kMaxLength 使用。
- 类型：
integer单个string实例允许的最大长度。
表示 string 原始类型可以拥有的最大 length，以 UTF-16 代码单元计数。
此值可能取决于所使用的 JS 引擎。
在 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未初始化，分配的内存段可能包含可能敏感的旧数据。
如果 size 小于或等于 Buffer.poolSize 的一半，由 Buffer.allocUnsafe()、Buffer.from(string)、Buffer.concat() 和 Buffer.from(array) 返回的 Buffer 实例_可能_从共享内部内存池分配。由 Buffer.allocUnsafeSlow() 返回的实例_从不_使用共享内部内存池。
--zero-fill-buffers 命令行选项
History
可以使用 --zero-fill-buffers 命令行选项启动 Node.js，以使所有新分配的 Buffer 实例在创建时默认零填充。如果没有该选项，使用 Buffer.allocUnsafe() 和 Buffer.allocUnsafeSlow() 创建的缓冲区不会零填充。使用此标志可能会对性能产生可测量的负面影响。仅在需要强制新分配的 Buffer 实例不能包含可能敏感的旧数据时使用 --zero-fill-buffers 选项。
$ node --zero-fill-buffers > Buffer.allocUnsafe(5); <Buffer 00 00 00 00 00>
当调用 Buffer.allocUnsafe() 和 Buffer.allocUnsafeSlow() 时，分配的内存段是_未初始化的_（它没有被清零）。虽然此设计使内存分配非常快，但分配的内存段可能包含可能敏感的旧数据。使用由 Buffer.allocUnsafe() 创建的 Buffer 而不_完全_覆盖内存，可能会在读取 Buffer 内存时允许此旧数据泄露。
虽然使用 Buffer.allocUnsafe() 有明显的性能优势，但必须格外小心以避免向应用程序引入安全漏洞。
某些操作系统接口要求其操作的内存经过对齐，而在某些硬件上，对齐仅仅意味着速度更快。前一种情况最常见的例子是无缓冲（“直接”）文件 I/O。在 Linux 上，这要求缓冲区地址、文件偏移量和传输长度都必须是底层设备逻辑块大小的倍数：
import { open } from 'node:fs/promises'; import { constants } from 'node:fs'; import { Buffer } from 'node:buffer'; const blockSize = 4096; // 要使 O_DIRECT 接受该缓冲区，缓冲区地址必须按块对齐。 const buf = Buffer.allocUnsafeSlow(blockSize, blockSize); const file = await open('/dev/sda', constants.O_RDONLY | constants.O_DIRECT); try { await file.read(buf, 0, blockSize, 0); } finally { await file.close(); }
const fs = require('node:fs'); const { Buffer } = require('node:buffer'); const blockSize = 4096; // 要使 O_DIRECT 接受该缓冲区，缓冲区地址必须按块对齐。 const buf = Buffer.allocUnsafeSlow(blockSize, blockSize); const flags = fs.constants.O_RDONLY | fs.constants.O_DIRECT; fs.open('/dev/sda', flags, (err, fd) => { if (err) throw err; fs.read(fd, buf, 0, blockSize, 0, (err) => { fs.close(fd, () => {}); if (err) throw err; }); });
即使没有接口强制要求，对齐也可能纯粹为了性能而值得请求。将一个高频使用的 Buffer 按缓存行大小（当代大多数 CPU 上为 64 字节）对齐，可以避免它跨越不必要的额外缓存行，使得一个小型结构只需一次缓存未命中即可获取，而不是两次；按页（4096 字节）对齐的分配同样有助于映射或固定内存的接口。这些都是微优化：在采用它们之前应先进行测量，因为额外的字节并非没有代价。
由于无法直接选择 Buffer 内存的地址，必须分配或跳过额外的字节才能到达对齐的地址。Buffer.allocUnsafeSlow() 会额外分配 alignment 个字节；如果 alignment 小于该值，则额外分配 8 个字节，并将返回的 Buffer 放置在其中第一个满足对齐要求的字节处。Buffer.allocUnsafe() 则会在共享内部池中填充其偏移量，该池的起始位置始终按 64 字节对齐；只有当 alignment 大于此值时，才会退回到单独分配。无论哪种情况，buf.byteOffset 通常都不为 0，并且 buf.buffer 大于 size，因此访问 Buffer 底层 ArrayBuffer 中超出 Buffer 范围的代码必须考虑偏移量，访问池化的 Buffer 时也一样。
对齐是返回的 Buffer 的属性，并且在其整个生命周期内都会保留，但不会被其他视图继承：buf.subarray、buf.slice() 和 structuredClone() 都可能生成未对齐的 Buffer。
将对齐状态保存到启动快照中也无法保留对齐：内存在序列化过程中不会保留其地址，因此在 --build-snapshot 生效时分配的 Buffer 在反序列化进程中不会保持对齐。如果运行时必须保持对齐，应在 v8.startupSnapshot.setDeserializeMainFunction() 回调中或启动之后进行分配。