Node.js v21.7.2 文件

執行緒池使用和效能考量#

除了明確同步的 API 之外，所有 zlib 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，外加一些小物件的幾 KB。

例如，若要將預設記憶體需求從 256K 降低至 128K，應將選項設定為

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

不過，這通常會降低壓縮率。

inflate 的記憶體需求（以位元組為單位）為 1 << windowBits。也就是說，windowBits = 15（預設值）的 32K，外加一些小物件的幾 KB。

這還不包括大小為 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。目前仍可直接從模組存取常數，但已標示為不建議使用。

允許的 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 的串流使用

flush 操作#

下列值是基於 Brotli 的串流的有效 flush 操作

• 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 <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 物件。

zlib.bytesRead#

• <數字>

已棄用的別名，對應於 zlib.bytesWritten。選擇這個原始名稱是因為它也可以合理地將值解釋為引擎讀取的位元組數，但與 Node.js 中以這些名稱公開值的其它串流不一致。

zlib.bytesWritten#

• <數字>

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 <integer>
• strategy <integer>
• callback <Function>

這個函式只適用於基於 zlib 的串流，也就是說不適用於 Brotli。

動態更新壓縮層級和壓縮策略。僅適用於 deflate 演算法。

zlib.reset()#

將壓縮器/解壓縮器重設為原廠預設值。僅適用於 inflate 和 deflate 演算法。

zlib.constants#

提供一個列舉與 Zlib 相關常數的物件。

zlib.createBrotliCompress([options])#

• options <brotli options>

建立並傳回一個新的 BrotliCompress 物件。

zlib.createBrotliDecompress([選項])#

• options <brotli options>

建立並傳回新的 BrotliDecompress 物件。

zlib.createDeflate([選項])#

• 選項 <zlib 選項>

建立並傳回新的 Deflate 物件。

zlib.createDeflateRaw([選項])#

• 選項 <zlib 選項>

建立並傳回新的 DeflateRaw 物件。

當 windowBits 設定為 8 時，zlib 從 1.2.8 升級到 1.2.11 會改變原始 deflate 串流的行為。如果最初將 windowBits 設定為 8，zlib 會自動將 windowBits 設定為 9。較新版本的 zlib 會擲回例外，因此 Node.js 還原將值 8 升級為 9 的原始行為，因為將 windowBits = 9 傳遞給 zlib 實際上會產生一個壓縮串流，而該串流有效地僅使用 8 位元視窗。

zlib.createGunzip([選項])#

• 選項 <zlib 選項>

建立並傳回新的 Gunzip 物件。

zlib.createGzip([選項])#

• 選項 <zlib 選項>

建立並傳回新的 Gzip 物件。請參閱 範例。

zlib.createInflate([選項])#

• 選項 <zlib 選項>

建立並傳回新的 Inflate 物件。

zlib.createInflateRaw([選項])#

• 選項 <zlib 選項>

建立並傳回一個新的 InflateRaw 物件。

zlib.createUnzip([options])#

• 選項 <zlib 選項>

建立並傳回一個新的 Unzip 物件。

方便的方法#

所有這些方法都將 Buffer、TypedArray、DataView、ArrayBuffer 或字串作為第一個引數，第二個引數（選用）用於提供選項給 zlib 類別，並會以 callback(error, result) 呼叫提供的回呼函式。

每個方法都有對應的 *Sync，它們接受相同的引數，但沒有回呼函式。

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

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

zlib.brotliCompressSync(buffer[, options])#

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

使用 BrotliCompress 壓縮資料區塊。

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

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

zlib.brotliDecompressSync(buffer[, options])#

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

使用 BrotliDecompress 解壓縮資料區塊。

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>
• callback <Function>

zlib.deflateSync(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>

使用 Deflate 壓縮資料區塊。

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>
• callback <Function>

zlib.deflateRawSync(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>

使用 DeflateRaw 壓縮資料區塊。

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>
• callback <Function>

zlib.gunzipSync(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>

使用 Gunzip 解壓縮資料區塊。

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>
• callback <Function>

zlib.gzipSync(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>

使用 Gzip 壓縮資料區塊。

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>
• callback <Function>

zlib.inflateSync(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>

使用 Inflate 解壓縮資料區塊。

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>
• callback <Function>

zlib.inflateRawSync(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>

使用 InflateRaw 解壓縮資料區塊。

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>
• callback <Function>

zlib.unzipSync(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• 選項 <zlib 選項>

使用 Unzip 解壓縮資料區塊。