Node.js v18.18.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的 128K = 15 + memLevel的 128K = 8（默认值）加上小对象的几千字节。

例如，要将默认内存要求从 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
  • 启用“大窗口 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 <整数> 默认值： zlib.constants.Z_NO_FLUSH
• finishFlush <整数> 默认值： zlib.constants.Z_FINISH
• chunkSize <整数> 默认值： 16 * 1024
• windowBits <整数>
• level <整数>（仅压缩）
• memLevel <整数>（仅压缩）
• strategy <整数>（仅压缩）
• dictionary <缓冲区> | <类型化数组> | <数据视图> | <ArrayBuffer>（仅缩小/膨胀，默认为空字典）
• info <boolean>（如果为true ，则返回具有buffer和engine的对象。）
• maxOutputLength <integer>使用 便捷方法时限制输出大小。默认值： buffer.kMaxLength

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

类：BrotliOptions#

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

• flush <整数> 默认值： zlib.constants.BROTLI_OPERATION_PROCESS
• finishFlush <整数> 默认值： 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#

• <数字>

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

zlib.bytesWritten#

• <数字>

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

zlib.close([callback])#

• callback <函数>

关闭底层句柄。

zlib.flush([kind, ]callback)#

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

刷新待处理数据。不要轻率地称呼这一点，过早的刷新会对压缩算法的有效性产生负面影响。

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

zlib.params(level, strategy, callback)#

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

此函数仅适用于基于 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 选项>

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

zlib.createDeflateRaw([options])#

• options <zlib 选项>

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

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

zlib.createGunzip([options])#

• options <zlib 选项>

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

zlib.createGzip([options])#

• options <zlib 选项>

创建并返回一个新的Gzip对象。请参阅示例。

zlib.createInflate([options])#

• options <zlib 选项>

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

zlib.createInflateRaw([options])#

• options <zlib 选项>

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

zlib.createUnzip([options])#

• options <zlib 选项>

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

便捷方法#

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

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

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <brotli 选项>
• callback <函数>

zlib.brotliCompressSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <brotli 选项>

使用BrotliCompress压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <brotli 选项>
• callback <函数>

zlib.brotliDecompressSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <brotli 选项>

使用BrotliDecompress解压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>
• callback <函数>

zlib.deflateSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>

使用Deflate压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>
• callback <函数>

zlib.deflateRawSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>

使用DeflateRaw压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>
• callback <函数>

zlib.gunzipSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>

使用Gunzip解压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>
• callback <函数>

zlib.gzipSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>

使用Gzip压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>
• callback <函数>

zlib.inflateSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>

使用Inflate解压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>
• callback <函数>

zlib.inflateRawSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>

使用InflateRaw解压缩数据块。

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

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>
• callback <函数>

zlib.unzipSync(buffer[, options])#

• buffer <缓冲区> | <类型化数组> | <数据视图> | <数组缓冲区> | <字符串>
• options <zlib 选项>

使用Unzip解压缩数据块。