Node.js v21.7.2 文档

线程池使用和性能注意事项#

所有 zlib API（除了明确同步的 API 外）都使用 Node.js 内部线程池。这可能会导致某些应用程序出现意外效果和性能限制。

同时创建和使用大量 zlib 对象会导致严重的内存碎片。

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

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

// WARNING: DO NOT DO THIS!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {});
} copy

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

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

压缩 HTTP 请求和响应#

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

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

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

// Client request example
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;
    // Or, just use zlib.createUnzip() to handle both of the following cases:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError);
      break;
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError);
      break;
    default:
      pipeline(response, output, onError);
      break;
  }
}); copy

// server example
// Running a gzip operation on every request is quite expensive.
// It would be much more efficient to cache the compressed buffer.
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');
  // Store both a compressed and an uncompressed version of the resource.
  response.setHeader('Vary', 'Accept-Encoding');
  let acceptEncoding = request.headers['accept-encoding'];
  if (!acceptEncoding) {
    acceptEncoding = '';
  }

  const onError = (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      response.end();
      console.error('An error occurred:', err);
    }
  };

  // Note: This is not a conformant accept-encoding parser.
  // See 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); copy

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

// This is a truncated version of the buffer from the above examples
const buffer = Buffer.from('eJzT0yMA', 'base64');

zlib.unzip(
  buffer,
  // For Brotli, the equivalent is 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());
  }); copy

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

内存使用调整#

对于基于 zlib 的流#

来自 zlib/zconf.h，为 Node.js 使用修改

deflate 的内存需求（以字节为单位）

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

也就是说：对于 windowBits = 15，需要 128K；对于 memLevel = 8（默认值），需要 128K；再加上一些用于小型对象的千字节。

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

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

但是，这通常会降低压缩率。

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

这还需加上一个大小为 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) => {
  // For the sake of simplicity, the Accept-Encoding checks are omitted.
  response.writeHead(200, { 'content-encoding': 'gzip' });
  const output = zlib.createGzip();
  let i;

  pipeline(output, response, (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      clearInterval(i);
      response.end();
      console.error('An error occurred:', err);
    }
  });

  i = setInterval(() => {
    output.write(`The current time is ${Date()}\n`, () => {
      // The data has been passed to zlib, but the compression algorithm may
      // have decided to buffer the data for more efficient compression.
      // Calling .flush() will make the data available as soon as the client
      // is ready to receive it.
      output.flush();
    });
  }, 1000);
}).listen(1337); copy

常量#

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
  • 启用“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
  • 启用“Large Window Brotli”模式的布尔标志（与 RFC 7932 中标准化的 Brotli 格式不兼容）。

类：Options#

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

某些选项仅在压缩时才相关，并且会被解压缩类忽略。

• flush <整数> 默认值： zlib.constants.Z_NO_FLUSH
• finishFlush <整数> 默认值： zlib.constants.Z_FINISH
• chunkSize <整数> 默认值： 16 * 1024
• windowBits <整数>
• level <整数> （仅压缩）
• memLevel <整数> （仅压缩）
• strategy <整数> （仅压缩）
• 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 <整数> 默认值： 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,
  },
}); copy

类：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 的流，为 zlib.constants.Z_FULL_FLUSH；对于基于 Brotli 的流，为 zlib.constants.BROTLI_OPERATION_FLUSH。
• callback <Function>

刷新待处理数据。不要随意调用此方法，过早的刷新会对压缩算法的有效性产生负面影响。

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

zlib.params(level, strategy, callback)#

• level <整数>
• strategy <整数>
• callback <Function>

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

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

zlib.reset()#

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

zlib.constants#

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

zlib.createBrotliCompress([options])#

• options <brotli 选项>

创建并返回一个新的 BrotliCompress 对象。

zlib.createBrotliDecompress([options])#

• options <brotli 选项>

创建并返回一个新的 BrotliDecompress 对象。

zlib.createDeflate([options])#

• options <zlib options>

创建一个并返回一个新的 Deflate 对象。

zlib.createDeflateRaw([options])#

• options <zlib options>

创建一个并返回一个新的 DeflateRaw 对象。

从 1.2.8 升级到 1.2.11 的 zlib 版本更改了当 windowBits 设置为 8 用于原始 deflate 流时的行为。zlib 会自动将 windowBits 设置为 9 如果它最初设置为 8。较新的 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 选项>
• callback <Function>

zlib.brotliCompressSync(buffer[, options])#

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

使用 BrotliCompress 压缩数据块。

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

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

zlib.brotliDecompressSync(buffer[, options])#

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

使用 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 解压缩数据块。