源代码: lib/buffer.js

Buffer 对象用于表示固定长度的字节序列。 许多 Node.js API 都支持 Buffer。

Buffer 类是 JavaScript Uint8Array 类的子类，并使用涵盖额外用例的方法对其进行扩展。 Node.js API 在支持 Buffer 的地方也接受普通的 Uint8Array。

虽然 Buffer 类在全局范围内可用，但仍然建议通过 import 或 require 语句显式地引用它。

  1. const { Buffer } = require('buffer');
  3. // 创建长度为 10 的以零填充的缓冲区。
  4. const buf1 = Buffer.alloc(10);
  6. // 创建长度为 10 的缓冲区，
  7. // 使用值为 `1` 的字节填充。
  8. const buf2 = Buffer.alloc(10, 1);
  10. // 创建长度为 10 的未初始化的缓冲区。
  11. // 这比调用 Buffer.alloc() 快，
  12. // 但返回的缓冲区实例可能包含旧数据，
  13. // 需要使用 fill()、write() 、
  14. // 或其他填充缓冲区内容的函数重写。
  15. const buf3 = Buffer.allocUnsafe(10);
  17. // 创建包含字节 [1, 2, 3] 的缓冲区。
  18. const buf4 = Buffer.from([1, 2, 3]);
  20. // 创建包含字节 [1, 1, 1, 1] 的缓冲区，
  21. // 所有条目都使用 `(value & 255)` 截断以符合范围 0–255。
  22. const buf5 = Buffer.from([257, 257.5, -255, '1']);
  24. // 创建包含字符串 'tést' 的 UTF-8 编码字节的缓冲区：
  25. // [0x74, 0xc3, 0xa9, 0x73, 0x74]（十六进制）
  26. // [116, 195, 169, 115, 116]（十进制）
  27. const buf6 = Buffer.from('tést');
  29. // 创建包含 Latin-1 字节 [0x74, 0xe9, 0x73, 0x74] 的缓冲区。
  30. const buf7 = Buffer.from('tést', 'latin1');

缓冲区与字符编码

版本 变更
v15.7.0 引入 base64url 编码。

当在 Buffer 和字符串之间进行转换时，可以指定字符编码。 如果未指定字符编码，则默认使用 UTF-8。
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’: 将每个字节编码为两个十六进制字符。 当解码仅包含有效十六进制字符的字符串时，可能会发生数据截断。 ```javascript const { Buffer } = require(‘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’)); // 打印: console.log(Buffer.from(‘fhqwhgads’, ‘utf16le’)); // 打印: 

  1. ```javascript
  2. const { Buffer } = require('buffer');
  4. Buffer.from('1ag', 'hex');
  5. // 打印 <Buffer 1a>，当遇到第一个非十六进制值 ('g') 时，则截断数据。
  7. Buffer.from('1a7g', 'hex');
  8. // 打印 <Buffer 1a>，当数据以一位数 ('7') 结尾时，则截断数据。
  10. Buffer.from('1634', 'hex');
  11. // 打印 <Buffer 16 34>，表现所有数据。

缓冲区与迭代器

可以使用 for..of 语法迭代 Buffer 示例：

  1. const { Buffer } = require('buffer');
  3. const buf = Buffer.from([1,2,3]);
  5. for (const b of buf) {
  6.   console.log(b);
  7. }
  8. // 打印:
  9. //   1
  10. //   2
  11. //   3

此外，buf.values()、buf.keys() 和 buf.entries() 方法可用于创建迭代器。

参考资料：
http://nodejs.cn/api/buffer.html