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 的對應方法，它們接受相同的引數，但沒有回撥函式。