注意：此頁面是由 compression README 產生。

compression

Node.js 壓縮中間件。

支援下列壓縮編碼

deflate
gzip

安裝

這是一個透過 npm 註冊表提供的 Node.js 模組。安裝使用 npm install 指令

$ npm install compression

API

var compression = require('compression')

compression([options])

使用指定的 options 傳回壓縮中介軟體。中介軟體將嘗試根據指定的 options 壓縮通過中介軟體的所有要求的回應主體。

此中介軟體絕不會壓縮包含 no-transform 指令的 Cache-Control 標頭的回應，因為壓縮會轉換主體。

選項

compression() 在選項物件中接受這些屬性。除了下列所列的屬性之外，zlib 選項也可以傳遞至選項物件中。

chunkSize

預設值為 zlib.Z_DEFAULT_CHUNK 或 16384。

請參閱 Node.js 文件以了解使用方式。

filter

決定是否應考慮壓縮回應的函式。此函式稱為 filter(req, res)，預期傳回 true 以考慮壓縮回應，或傳回 false 以不壓縮回應。

預設的篩選函式使用 compressible 模組來判斷 res.getHeader('Content-Type') 是否可壓縮。

level

要套用於回應的 zlib 壓縮層級。較高的層級將產生更好的壓縮，但需要較長的時間才能完成。較低的層級將產生較少的壓縮，但會快很多。

這是介於 0（無壓縮）到 9（最大壓縮）範圍內的整數。特殊值 -1 可用於表示「預設壓縮層級」，這是速度和壓縮之間的預設折衷（目前等於層級 6）。

-1 預設壓縮層級（亦為 zlib.Z_DEFAULT_COMPRESSION）。
0 無壓縮（亦為 zlib.Z_NO_COMPRESSION）。
1 最快壓縮（亦為 zlib.Z_BEST_SPEED）。
2
3
4
5
6（目前 zlib.Z_DEFAULT_COMPRESSION 指向的內容）。
7
8
9 最佳壓縮（亦為 zlib.Z_BEST_COMPRESSION）。

預設值為 zlib.Z_DEFAULT_COMPRESSION，或 -1。

請注意在上述清單中，zlib 來自 zlib = require('zlib')。

memLevel

這會指定內部壓縮狀態應配置多少記憶體，且為介於 1（最低層級）和 9（最高層級）之間的整數。

預設值為 zlib.Z_DEFAULT_MEMLEVEL，或 8。

請參閱 Node.js 文件以了解使用方式。

strategy

這用於調整壓縮演算法。此值只會影響壓縮比，而非壓縮輸出的正確性，即使未適當地設定亦然。

zlib.Z_DEFAULT_STRATEGY 用於一般資料。
zlib.Z_FILTERED 用於由過濾器（或預測器）產生的資料。過濾資料主要由具有隨機分佈的小值組成。在此情況下，壓縮演算法會調整為更佳地壓縮這些值。其效果會強制更多 Huffman 編碼和更少的字串比對；它在 zlib.Z_DEFAULT_STRATEGY 和 zlib.Z_HUFFMAN_ONLY 之間某個程度的中間值。
zlib.Z_FIXED 用於防止使用動態 Huffman 編碼，允許為特殊應用程式提供更簡單的解碼器。
zlib.Z_HUFFMAN_ONLY 用於強制僅使用 Huffman 編碼（無字串比對）。
zlib.Z_RLE 用於將比對距離限制為一（執行長度編碼）。這被設計為幾乎與 zlib.Z_HUFFMAN_ONLY 一樣快，但為 PNG 影像資料提供更好的壓縮。

請注意在上述清單中，zlib 來自 zlib = require('zlib')。

閾值

在考量回應的壓縮之前，回應主體大小的位元組閾值，預設為 1kb。這是位元組數或 bytes 模組接受的任何字串。

注意這只是一個建議設定；如果在寫入回應標頭時無法確定回應大小，則假設回應超過閾值。若要保證可以確定回應大小，請務必設定 Content-Length 回應標頭。

windowBits

預設值為 zlib.Z_DEFAULT_WINDOWBITS，或 15。

請參閱 Node.js 文件以了解使用方式。

.filter

預設的 filter 函式。這用於建構自訂的 filter 函式，作為預設函式的延伸。

var compression = require('compression')
var express = require('express')

var app = express()
app.use(compression({ filter: shouldCompress }))

function shouldCompress (req, res) {
  if (req.headers['x-no-compression']) {
    // don't compress responses with this request header
    return false
  }

  // fallback to standard filter function
  return compression.filter(req, res)
}

res.flush

此模組新增一個 res.flush() 方法，用於強制將部分壓縮的回應刷新到用戶端。

範例

express/connect

將此模組與 express 或 connect 一起使用時，只需盡可能高地 app.use 模組。通過中間軟體的請求將被壓縮。

var compression = require('compression')
var express = require('express')

var app = express()

// compress all responses
app.use(compression())

// add all routes

伺服器傳送事件

由於壓縮的性質，此模組並未與伺服器傳送事件開箱即用。若要壓縮內容，需要緩衝輸出視窗才能獲得良好的壓縮。通常在使用伺服器傳送事件時，有某些資料區塊需要傳送至用戶端。

當你需要將寫入的資料實際傳送給客戶端時，你可以呼叫 res.flush() 來達成此目的。

var compression = require('compression')
var express = require('express')

var app = express()

// compress responses
app.use(compression())

// server-sent event stream
app.get('/events', function (req, res) {
  res.setHeader('Content-Type', 'text/event-stream')
  res.setHeader('Cache-Control', 'no-cache')

  // send a ping approx every 2 seconds
  var timer = setInterval(function () {
    res.write('data: ping\n\n')

    // !!! this is the important part
    res.flush()
  }, 2000)

  res.on('close', function () {
    clearInterval(timer)
  })
})

授權

MIT