Node.js v24.0.0 文档

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

所有 zlib API，除了那些显式同步的 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

刷新#

在压缩流上调用 .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

常量#

类: 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 <布尔值>（如果为 true，则返回带有 buffer 和 engine 的对象。）
• maxOutputLength <整数> 使用 简便方法 时限制输出大小。 默认值: 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 <整数> 使用 简便方法 时限制输出大小。 默认值: 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 对象。

类: ZstdOptions#

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

• flush <整数> 默认值: zlib.constants.ZSTD_e_continue
• finishFlush <整数> 默认值: zlib.constants.ZSTD_e_end
• chunkSize <整数> 默认值: 16 * 1024
• params <对象> 包含索引 Zstd 参数的键值对象。
• maxOutputLength <整数> 使用 简便方法 时限制输出大小。 默认值: buffer.kMaxLength

例如

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 <整数> 一个可选的起始值。 它必须是一个 32 位无符号整数。 默认值: 0
• 返回: <整数> 包含校验和的 32 位无符号整数。

计算 data 的 32 位 循环冗余校验校验和。 如果指定了 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 选项>

创建并返回一个新的 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 对象。

zlib.createZstdCompress([options])#

• options <zstd 选项>

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

zlib.createZstdDecompress([options])#

• options <zstd 选项>

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

便捷方法#

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

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