Node.js v18.15.0 文档

线程池的使用与性能的考虑#

中英对照

所有 zlib API，除了那些显式同步的 API，都使用 Node.js 内部线程池。 这可能会在某些应用程序中导致令人惊讶的效果和性能限制。

同时创建和使用大量压缩对象会导致显着的内存碎片。

const zlib = require('node:zlib');

const payload = Buffer.from('This is some data');

// 警告：不要这样做！
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {});
}

在前面的示例中，同时创建了 30,000 个 deflate 实例。 由于某些操作系统如何处理内存分配和释放，这可能会导致严重的内存碎片。

强烈建议缓存压缩操作的结果以避免重复工作。

压缩 HTTP 的请求和响应#

中英对照

node:zlib 模块可用于实现对 HTTP 定义的 gzip、deflate 和 br 内容编码机制的支持。

HTTP Accept-Encoding 标头在 HTTP 请求中用于识别客户端接受的压缩编码。 Content-Encoding 标头用于标识实际应用于消息的压缩编码。

下面给出的示例经过彻底简化以显示基本概念。 使用 zlib 编码可能很昂贵，结果应该被缓存。 有关 zlib 使用中涉及的速度/内存/压缩权衡的更多信息，请参阅内存使用调整。

// 客户端请求示例
const zlib = require('node:zlib');
const http = require('node:http');
const fs = require('node:fs');
const { pipeline } = require('node:stream');

const request = http.get({ host: 'example.com',
                           path: '/',
                           port: 80,
                           headers: { 'Accept-Encoding': 'br,gzip,deflate' } });
request.on('response', (response) => {
  const output = fs.createWriteStream('example.com_index.html');

  const onError = (err) => {
    if (err) {
      console.error('An error occurred:', err);
      process.exitCode = 1;
    }
  };

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError);
      break;
    // 或者，只需使用 zlib.createUnzip() 来处理以下两种情况：
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError);
      break;
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError);
      break;
    default:
      pipeline(response, output, onError);
      break;
  }
});

// 服务器示例
// 对每个请求运行 gzip 操作是非常昂贵的。
// 缓存压缩的缓冲区会更有效率。
const zlib = require('node:zlib');
const http = require('node:http');
const fs = require('node:fs');
const { pipeline } = require('node:stream');

http.createServer((request, response) => {
  const raw = fs.createReadStream('index.html');
  // 存储资源的压缩版本和未压缩版本。
  response.setHeader('Vary', 'Accept-Encoding');
  let acceptEncoding = request.headers['accept-encoding'];
  if (!acceptEncoding) {
    acceptEncoding = '';
  }

  const onError = (err) => {
    if (err) {
      // 如果发生错误，则无能为力，
      // 因为服务器已经发送了 200 响应代码，
      // 并且已经向客户端发送了一些数据。
      // 能做的最好的事情
      // 就是立即终止响应并记录错误。
      response.end();
      console.error('An error occurred:', err);
    }
  };

  // 注意：这不是一个符合标准的接受编码解析器。
  // 参见 https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
  if (/\bdeflate\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'deflate' });
    pipeline(raw, zlib.createDeflate(), response, onError);
  } else if (/\bgzip\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'gzip' });
    pipeline(raw, zlib.createGzip(), response, onError);
  } else if (/\bbr\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'br' });
    pipeline(raw, zlib.createBrotliCompress(), response, onError);
  } else {
    response.writeHead(200, {});
    pipeline(raw, response, onError);
  }
}).listen(1337);

默认情况下，zlib 方法在解压缩截断数据时会抛出错误。 但是，如果已知数据不完整，或者希望仅检查压缩文件的开头，则可以通过更改用于解压缩输入的最后一个块的刷新方法来抑制默认错误处理数据：

// 这是上述示例中缓冲区的截断版本
const buffer = Buffer.from('eJzT0yMA', 'base64');

zlib.unzip(
  buffer,
  // 对于 Brotli，相当于 zlib.constants.BROTLI_OPERATION_FLUSH
  { finishFlush: zlib.constants.Z_SYNC_FLUSH },
  (err, buffer) => {
    if (err) {
      console.error('An error occurred:', err);
      process.exitCode = 1;
    }
    console.log(buffer.toString());
  });

这不会改变其他错误抛出情况下的行为，例如当输入数据的格式无效时。 使用此方法，将无法确定输入是否提前结束或缺少完整性检查，因此需要手动检查解压结果是否有效。

内存使用的调整#

对于基于 zlib 的流#

中英对照

从 zlib/zconf.h 开始，针对 Node.js 使用进行了修改：

deflate 的内存要求是（以字节为单位）：

(1 << (windowBits + 2)) + (1 << (memLevel + 9))

即：windowBits 的 128K = 15 + memLevel 的 128K = 8（默认值）加上小对象的几千字节。

例如，要将默认内存要求从 256K 减少到 128K，应将选项设置为：

const options = { windowBits: 14, memLevel: 7 };

然而，这通常会降低压缩性能。

inflate 的内存要求是（以字节为单位）1 << windowBits。 也就是说，windowBits 的 32K = 15（默认值）加上小对象的几千字节。

这是对大小为 chunkSize 的单个内部输出平板缓冲区的补充，默认为 16K。

zlib 压缩的速度受 level 设置的影响最大。 更高的级别将导致更好的压缩，但需要更长的时间才能完成。 较低的级别将导致较少的压缩，但会更快。

一般来说，更大的内存使用选项意味着 Node.js 必须对 zlib 进行更少的调用，因为它能够在每个 write 操作上处理更多的数据。 所以，这是影响速度的另一个因素，以内存使用为代价。

对于基于 Brotli 的流#

中英对照

有与基于 Brotli 的流的 zlib 选项等效的选项，尽管这些选项的范围与 zlib 的范围不同：

• zlib 的 level 选项匹配 Brotli 的 BROTLI_PARAM_QUALITY 选项。
• zlib 的 windowBits 选项匹配 Brotli 的 BROTLI_PARAM_LGWIN 选项。

有关 Brotli 特定选项的更多详细信息，请参见下文。

刷新#

中英对照

在压缩流上调用 .flush() 将使 zlib 返回尽可能多的当前输出。 这可能以降低压缩质量为代价，但在需要尽快提供数据时非常有用。

在以下示例中，flush() 用于将压缩的部分 HTTP 响应写入客户端：

const zlib = require('node:zlib');
const http = require('node:http');
const { pipeline } = require('node:stream');

http.createServer((request, response) => {
  // 为了简单起见，省略了接受编码检查。
  response.writeHead(200, { 'content-encoding': 'gzip' });
  const output = zlib.createGzip();
  let i;

  pipeline(output, response, (err) => {
    if (err) {
      // 如果发生错误，则无能为力，
      // 因为服务器已经发送了 200 响应代码，
      // 并且已经向客户端发送了一些数据。
      // 能做的最好的事情
      // 就是立即终止响应并记录错误。
      clearInterval(i);
      response.end();
      console.error('An error occurred:', err);
    }
  });

  i = setInterval(() => {
    output.write(`The current time is ${Date()}\n`, () => {
      // 数据已传给 zlib，
      // 但压缩算法可能已决定缓冲数据以进行更有效的压缩。
      // 一旦客户端准备好接收数据，
      // 调用 .flush() 将使数据可用。
      output.flush();
    });
  }, 1000);
}).listen(1337);

常量#

zlib 常量#

中英对照

zlib.h 中定义的所有常量也在 require('node:zlib').constants 上定义。 在正常的操作过程中，没有必要使用这些常量。 它们被记录在案，因此它们的存在不足为奇。 本章节几乎直接取自 zlib 文档。

以前，常量可直接从 require('node:zlib') 获得，例如 zlib.Z_NO_FLUSH。 目前仍然可以直接从模块访问常量，但已弃用。

允许的刷新值。

• zlib.constants.Z_NO_FLUSH
• zlib.constants.Z_PARTIAL_FLUSH
• zlib.constants.Z_SYNC_FLUSH
• zlib.constants.Z_FULL_FLUSH
• zlib.constants.Z_FINISH
• zlib.constants.Z_BLOCK
• zlib.constants.Z_TREES

压缩/解压缩函数的返回代码。 负值是错误，正值用于特殊但正常的事件。

• zlib.constants.Z_OK
• zlib.constants.Z_STREAM_END
• zlib.constants.Z_NEED_DICT
• zlib.constants.Z_ERRNO
• zlib.constants.Z_STREAM_ERROR
• zlib.constants.Z_DATA_ERROR
• zlib.constants.Z_MEM_ERROR
• zlib.constants.Z_BUF_ERROR
• zlib.constants.Z_VERSION_ERROR

压缩级别。

• zlib.constants.Z_NO_COMPRESSION
• zlib.constants.Z_BEST_SPEED
• zlib.constants.Z_BEST_COMPRESSION
• zlib.constants.Z_DEFAULT_COMPRESSION

压缩策略。

• zlib.constants.Z_FILTERED
• zlib.constants.Z_HUFFMAN_ONLY
• zlib.constants.Z_RLE
• zlib.constants.Z_FIXED
• zlib.constants.Z_DEFAULT_STRATEGY

Brotli 常量#

中英对照

有几个选项和其他常量可用于基于 Brotli 的流：

刷新操作#

中英对照

以下值是基于 Brotli 的流的有效刷新操作：

• zlib.constants.BROTLI_OPERATION_PROCESS（所有操作的默认值）
• zlib.constants.BROTLI_OPERATION_FLUSH（调用 .flush() 时的默认值）
• zlib.constants.BROTLI_OPERATION_FINISH（最后一个块的默认值）
• zlib.constants.BROTLI_OPERATION_EMIT_METADATA
  • 这个特定的操作可能很难在 Node.js 上下文中使用，因为流层很难知道哪些数据会在这个帧中结束。 此外，目前无法通过 Node.js API 使用这些数据。

压缩器选项#

中英对照

可以在 Brotli 编码器上设置几个选项，影响压缩效率和速度。 键和值都可以作为 zlib.constants 对象的属性访问。

最重要的选项是：

• BROTLI_PARAM_MODE
  • BROTLI_MODE_GENERIC（默认）
  • BROTLI_MODE_TEXT，针对 UTF-8 文本进行了调整
  • BROTLI_MODE_FONT，针对 WOFF 2.0 字体进行了调整
• BROTLI_PARAM_QUALITY
  • 范围从 BROTLI_MIN_QUALITY 到 BROTLI_MAX_QUALITY，默认为 BROTLI_DEFAULT_QUALITY。
• BROTLI_PARAM_SIZE_HINT
  • 表示预期输入大小的整数值；对于未知的输入大小，默认为 0。

可以设置以下标志以对压缩算法和内存使用调整进行高级控制：

• BROTLI_PARAM_LGWIN
  • 范围从 BROTLI_MIN_WINDOW_BITS 到 BROTLI_MAX_WINDOW_BITS，默认为 BROTLI_DEFAULT_WINDOW，如果设置了 BROTLI_PARAM_LARGE_WINDOW 标志，则最高可达 BROTLI_LARGE_MAX_WINDOW_BITS。
• BROTLI_PARAM_LGBLOCK
  • 范围从 BROTLI_MIN_INPUT_BLOCK_BITS 到 BROTLI_MAX_INPUT_BLOCK_BITS。
• BROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING
  • 降低压缩率以提高解压速度的布尔标志。
• BROTLI_PARAM_LARGE_WINDOW
  • 启用“大窗口 Brotli”模式的布尔标志（与 RFC 7932 中标准化的 Brotli 格式不兼容）。
• BROTLI_PARAM_NPOSTFIX
  • 范围从 0 到 BROTLI_MAX_NPOSTFIX。
• BROTLI_PARAM_NDIRECT
  • 范围从 0 到 15 << NPOSTFIX，步长为 1 << NPOSTFIX。

解压器选项#

中英对照

这些高级选项可用于控制减压：

• BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION
  • 影响内部内存分配模式的布尔标志。
• BROTLI_DECODER_PARAM_LARGE_WINDOW
  • 启用“大窗口 Brotli”模式的布尔标志（与 RFC 7932 中标准化的 Brotli 格式不兼容）。

Options 类#

中英对照

每个基于 zlib 的类都有一个 options 对象。 不需要任何选项。

某些选项仅在压缩时相关，而被解压缩类忽略。

• flush <integer> 默认值: zlib.constants.Z_NO_FLUSH
• finishFlush <integer> 默认值: zlib.constants.Z_FINISH
• chunkSize <integer> 默认值: 16 * 1024
• windowBits <integer>
• level <integer> （仅压缩）
• memLevel <integer> （仅压缩）
• strategy <integer> （仅压缩）
• dictionary <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> （仅 deflate/inflate，默认情况下为空字典）
• info <boolean> （如果是 true，则返回具有 buffer 和 engine 的对象。）
• maxOutputLength <integer> 使用便捷方法时限制输出大小。 默认值: buffer.kMaxLength

有关更多信息，请参阅 deflateInit2 和 inflateInit2 文档。

BrotliOptions 类#

中英对照

每个基于 Brotli 的类都有一个 options 对象。 所有选项都是可选的。

• flush <integer> 默认值: zlib.constants.BROTLI_OPERATION_PROCESS
• finishFlush <integer> 默认值: zlib.constants.BROTLI_OPERATION_FINISH
• chunkSize <integer> 默认值: 16 * 1024
• params <Object> 包含索引 Brotli 参数的键值对象。
• maxOutputLength <integer> 使用便捷方法时限制输出大小。 默认值: buffer.kMaxLength

例如：

const stream = zlib.createBrotliCompress({
  chunkSize: 32 * 1024,
  params: {
    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
    [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
    [zlib.constants.BROTLI_PARAM_SIZE_HINT]: fs.statSync(inputFile).size,
  },
});

zlib.BrotliCompress 类#

中英对照

使用 Brotli 算法压缩数据。

zlib.BrotliDecompress 类#

中英对照

使用 Brotli 算法解压缩数据。

zlib.Deflate 类#

中英对照

使用 deflate 压缩数据。

zlib.DeflateRaw 类#

中英对照

使用 deflate 压缩数据，并且不附加 zlib 标头。

zlib.Gunzip 类#

中英对照

解压缩 gzip 流。

zlib.Gzip 类#

中英对照

使用 gzip 压缩数据。

zlib.Inflate 类#

中英对照

解压缩 deflate 流。

zlib.InflateRaw 类#

中英对照

解压缩原始的 deflate 流。

zlib.Unzip 类#

中英对照

通过自动检测标头来解压缩 Gzip 或 Deflate 压缩的流。

zlib.ZlibBase 类#

中英对照

不是由 node:zlib 模块导出的。 它记录在此处，因为它是压缩器/解压缩器类的基类。

这个类继承自 stream.Transform，允许在管道和类似的流操作中使用 node:zlib 对象。

zlib.bytesRead#

中英对照

• <number>

弃用的 zlib.bytesWritten 别名。 选择这个原始名称是因为将值解释为引擎读取的字节数也是有意义的，但与 Node.js 中以这些名称公开值的其他流不一致。

zlib.bytesWritten#

中英对照

• <number>

zlib.bytesWritten 属性指定在处理字节（压缩或解压缩，视派生类而定）之前写入引擎的字节数。

zlib.close([callback])#

中英对照

• callback <Function>

关闭底层句柄。

zlib.flush([kind, ]callback)#

中英对照

• kind 默认值: zlib.constants.Z_FULL_FLUSH 用于基于 zlib 的流，zlib.constants.BROTLI_OPERATION_FLUSH 用于基于 Brotli 的流。
• callback <Function>

刷新挂起的数据。 不要轻率地称之为，过早刷新会对压缩算法的有效性产生负面影响。

调用它只会从内部 zlib 状态刷新数据，并且不会在流级别执行任何类型的刷新。 相反，它的行为类似于对 .write() 的正常调用，即它将排队等待其他未决写入，并且仅在从流中读取数据时才产生输出。

zlib.params(level, strategy, callback)#

中英对照

• level <integer>
• strategy <integer>
• callback <Function>

此函数仅适用于基于 zlib 的流，即不适用于 Brotli。

动态更新压缩级别和压缩策略。 仅适用于 deflate 算法。

zlib.reset()#

中英对照

将压缩器/解压缩器重置为出厂默认设置。 仅适用于 inflate 和 deflate 算法。

zlib.constants#

中英对照

提供枚举 Zlib 相关常量的对象。

zlib.createBrotliCompress([options])#

中英对照

• options <brotli options>

创建并返回新的 BrotliCompress 对象。

zlib.createBrotliDecompress([options])#

中英对照

• options <brotli options>

创建并返回新的 BrotliDecompress 对象。

zlib.createDeflate([options])#

中英对照

• options <zlib options>

创建并返回新的 Deflate 对象。

zlib.createDeflateRaw([options])#

中英对照

• options <zlib options>

创建并返回新的 DeflateRaw 对象。

当原始 deflate 流的 windowBits 设置为 8 时，zlib 从 1.2.8 到 1.2.11 的升级改变了行为。 如果最初设置为 8，则 zlib 会自动将 windowBits 设置为 9。 较新版本的 zlib 会抛出异常，因此 Node.js 恢复了将值从 8 升级到 9 的原始行为，因为将 windowBits = 9 传给 zlib 实际上会产生一个仅有效使用 8 位窗口的压缩流。

zlib.createGunzip([options])#

中英对照

• options <zlib options>

创建并返回新的 Gunzip 对象。

zlib.createGzip([options])#

中英对照

• options <zlib options>

创建并返回新的 Gzip 对象。 查看示例。

zlib.createInflate([options])#

中英对照

• options <zlib options>

创建并返回新的 Inflate 对象。

zlib.createInflateRaw([options])#

中英对照

• options <zlib options>

创建并返回新的 InflateRaw 对象。

zlib.createUnzip([options])#

中英对照

• options <zlib options>

创建并返回新的 Unzip 对象。

便捷方法#

中英对照

所有这些都将 Buffer、TypedArray、DataView、ArrayBuffer 或字符串作为第一个参数，可选的第二个参数为 zlib 类提供选项，并将使用 callback(error, result) 调用提供的回调。

每个方法都有一个对应的 *Sync 方法，它们接受相同的参数，但没有回调。

zlib.brotliCompress(buffer[, options], callback)#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>
• callback <Function>

zlib.brotliCompressSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>

使用 BrotliCompress 压缩数据块。

zlib.brotliDecompress(buffer[, options], callback)#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>
• callback <Function>

zlib.brotliDecompressSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>

使用 BrotliDecompress 解压缩数据块。

zlib.deflate(buffer[, options], callback)#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.deflateSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

使用 Deflate 压缩数据块。

zlib.deflateRaw(buffer[, options], callback)#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.deflateRawSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

使用 DeflateRaw 压缩数据块。

zlib.gunzip(buffer[, options], callback)#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.gunzipSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

使用 Gunzip 解压缩数据块。

zlib.gzip(buffer[, options], callback)#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.gzipSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

使用 Gzip 压缩数据块。

zlib.inflate(buffer[, options], callback)#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.inflateSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

使用 Inflate 解压缩数据块。

zlib.inflateRaw(buffer[, options], callback)#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.inflateRawSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

使用 InflateRaw 解压缩数据块。

zlib.unzip(buffer[, options], callback)#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.unzipSync(buffer[, options])#

中英对照

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

使用 Unzip 解压缩数据块。