Node.js v25.0.0 文档

线程池的使用和性能考量#

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

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

import zlib from 'node:zlib';
import { Buffer } from 'node:buffer';

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) => {});
}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 和 zstd 内容编码机制的支持。

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

下面给出的示例被大幅简化，以展示基本概念。使用 zlib 编码可能成本很高，其结果应该被缓存。有关 zlib 使用中涉及的速度/内存/压缩权衡的更多信息，请参阅内存使用调优。

// Client request example
import fs from 'node:fs';
import zlib from 'node:zlib';
import http from 'node:http';
import process from 'node:process';
import { pipeline } from '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;
  }
});// 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,zstd' } });
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;
    case 'zstd':
      pipeline(response, zlib.createZstdDecompress(), 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.
import zlib from 'node:zlib';
import http from 'node:http';
import fs from 'node:fs';
import { pipeline } from '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');
  const acceptEncoding = request.headers['accept-encoding'] || '';

  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);// 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');
  const acceptEncoding = request.headers['accept-encoding'] || '';

  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 if (/\bzstd\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'zstd' });
    pipeline(raw, zlib.createZstdCompress(), 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.
  // For Zstd, the equivalent is zlib.constants.ZSTD_e_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

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

内存使用调优#

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

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

刷新（Flushing）#

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

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

import zlib from 'node:zlib';
import http from 'node:http';
import { pipeline } from '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);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

常量#

const stream = zlib.createZstdCompress({
  params: {
    [zlib.constants.ZSTD_c_strategy]: zlib.constants.ZSTD_btultra,
  },
}); copy

类：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
• info <boolean> 如果为 true，返回一个包含 buffer 和 engine 的对象。默认： false

例如：

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#

• 继承自：ZlibBase

使用 Brotli 算法压缩数据。

类：zlib.BrotliDecompress#

• 继承自：ZlibBase

使用 Brotli 算法解压缩数据。

类：zlib.Deflate#

• 继承自：ZlibBase

使用 deflate 压缩数据。

类：zlib.DeflateRaw#

• 继承自：ZlibBase

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

类：zlib.Gunzip#

• 继承自：ZlibBase

解压缩 gzip 流。

类：zlib.Gzip#

• 继承自：ZlibBase

使用 gzip 压缩数据。

类：zlib.Inflate#

• 继承自：ZlibBase

解压缩 deflate 流。

类：zlib.InflateRaw#

• 继承自：ZlibBase

解压缩原始 deflate 流。

类：zlib.Unzip#

• 继承自：ZlibBase

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

类：zlib.ZlibBase#

• 继承自：stream.Transform

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

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

类：ZstdOptions#

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

• flush <integer> 默认： zlib.constants.ZSTD_e_continue
• finishFlush <integer> 默认： zlib.constants.ZSTD_e_end
• chunkSize <integer> 默认： 16 * 1024
• params <Object> 包含索引化 Zstd 参数的键值对象。
• maxOutputLength <integer> 在使用便捷方法时限制输出大小。默认： buffer.kMaxLength
• info <boolean> 如果为 true，返回一个包含 buffer 和 engine 的对象。默认： false
• dictionary <Buffer> 可选字典，用于在压缩或解压缩与字典具有共同模式的数据时提高压缩效率。

例如：

const stream = zlib.createZstdCompress({
  chunkSize: 32 * 1024,
  params: {
    [zlib.constants.ZSTD_c_compressionLevel]: 10,
    [zlib.constants.ZSTD_c_checksumFlag]: 1,
  },
}); copy

类：zlib.ZstdCompress#

使用 Zstd 算法压缩数据。

类：zlib.ZstdDecompress#

使用 Zstd 算法解压缩数据。

zlib.constants#

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

zlib.crc32(data[, value])#

• data <string> | <Buffer> | <TypedArray> | <DataView> 当 data 是字符串时，它将被编码为 UTF-8 后用于计算。
• value <integer> 一个可选的起始值。它必须是一个 32 位无符号整数。默认： 0
• 返回：<integer> 一个包含校验和的 32 位无符号整数。

计算 data 的 32 位循环冗余校验 (Cyclic Redundancy Check) 校验和。如果指定了 value，它将用作校验和的起始值，否则使用 0 作为起始值。

CRC 算法旨在计算校验和并检测数据传输中的错误。它不适用于加密认证。

为了与其他 API 保持一致，如果 data 是一个字符串，它将在计算前被编码为 UTF-8。如果用户只使用 Node.js 来计算和匹配校验和，这与默认使用 UTF-8 编码的其他 API 配合得很好。

一些第三方 JavaScript 库基于 str.charCodeAt() 计算字符串的校验和，以便它可以在浏览器中运行。如果用户想匹配在浏览器中用这类库计算的校验和，如果该库也能在 Node.js 中运行，那么最好在 Node.js 中使用同一个库。如果用户必须使用 zlib.crc32() 来匹配由这类第三方库生成的校验和：

1. 如果该库接受 Uint8Array 作为输入，请在浏览器中使用 TextEncoder 将字符串编码为 UTF-8 的 Uint8Array，然后在浏览器中基于 UTF-8 编码的字符串计算校验和。
2. 如果该库只接受字符串并基于 str.charCodeAt() 计算数据，在 Node.js 端，使用 Buffer.from(str, 'utf16le') 将字符串转换为缓冲区。

import zlib from 'node:zlib';
import { Buffer } from 'node:buffer';

let crc = zlib.crc32('hello');  // 907060870
crc = zlib.crc32('world', crc);  // 4192936109

crc = zlib.crc32(Buffer.from('hello', 'utf16le'));  // 1427272415
crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc);  // 4150509955const zlib = require('node:zlib');
const { Buffer } = require('node:buffer');

let crc = zlib.crc32('hello');  // 907060870
crc = zlib.crc32('world', crc);  // 4192936109

crc = zlib.crc32(Buffer.from('hello', 'utf16le'));  // 1427272415
crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc);  // 4150509955copy

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 对象。

zlib 从 1.2.8 升级到 1.2.11 改变了当为原始 deflate 流设置 windowBits 为 8 时的行为。zlib 过去会自动将 windowBits 设置为 9，如果它最初被设置为 8。新版本的 zlib 会抛出异常，因此 Node.js 恢复了将值 8 升级到 9 的原始行为，因为向 zlib 传递 windowBits = 9 实际上会产生一个有效使用 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 对象。

zlib.createZstdCompress([options])#

• options <zstd options>

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

zlib.createZstdDecompress([options])#

• options <zstd options>

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

便捷方法#

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

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