注意

此页面由 compression README 生成。

compression

NPM Version NPM Downloads Build Status OpenSSF Scorecard Badge Funding

Node.js 压缩中间件。

支持以下压缩编码

注意 Brotli 仅在 Node.js v11.7.0 和 v10.16.0 及更高版本中受支持。

安装

这是一个可通过 npm 注册表获得的 Node.js 模块。使用 npm install 命令进行安装。

$ npm install compression

API

var compression = require('compression')

compression([options])

返回使用给定 options 的压缩中间件。中间件将根据给定的 options 尝试压缩所有经过该中间件的请求的响应体。

此中间件永远不会压缩包含 Cache-Control 头且带有 no-transform 指令的响应，因为压缩会转换响应体。

选项

compression() 在选项对象中接受以下属性。除了下面列出的之外，zlib 选项或 brotli 选项也可以传递到选项对象中。

chunkSize

类型：Number
默认值：zlib.constants.Z_DEFAULT_CHUNK，或 16384。

有关用法，请参阅 Node.js 文档。

filter

类型：Function

一个函数，用于决定响应是否应被考虑进行压缩。此函数以 filter(req, res) 形式调用，并预期返回 true 以考虑压缩响应，或返回 false 以不压缩响应。

默认的 filter 函数使用 compressible 模块来判断 res.getHeader('Content-Type') 是否可压缩。

level

类型：Number
默认值：zlib.constants.Z_DEFAULT_COMPRESSION，或 -1

应用于响应的 zlib 压缩级别。级别越高，压缩效果越好，但完成时间越长。级别越低，压缩效果越差，但速度会快得多。

这是一个介于 0（无压缩）到 9（最大压缩）之间的整数。特殊值 -1 可用于表示“默认压缩级别”，这是速度和压缩之间的默认折衷方案（目前相当于级别 6）。

注意 在以上列表中，zlib 来自 zlib = require('zlib')。

memLevel

类型：Number
默认值：zlib.constants.Z_DEFAULT_MEMLEVEL，或 8

这指定了内部压缩状态应分配的内存量，它是一个介于 1（最小级别）和 9（最大级别）之间的整数。

有关用法，请参阅 Node.js 文档。

brotli

类型：Object

这指定了配置 Brotli 的选项。有关可用选项的完整列表，请参阅 Node.js 文档。

strategy

类型：Number
默认值：zlib.constants.Z_DEFAULT_STRATEGY

这用于调整压缩算法。此值仅影响压缩比，即使设置不当，也不会影响压缩输出的正确性。

注意 在以上列表中，zlib 来自 zlib = require('zlib')。

threshold

类型：Number 或 String
默认值：1kb

响应体大小在考虑压缩前的字节阈值。这是一个字节数或 bytes 模块接受的任何字符串。

注意 这仅是一个建议设置；如果在写入响应头时无法确定响应大小，则假定响应已超出阈值。为确保可以确定响应大小，请务必设置 Content-Length 响应头。

windowBits

类型：Number
默认值：zlib.constants.Z_DEFAULT_WINDOWBITS，或 15

有关用法，请参阅 Node.js 文档。

enforceEncoding

类型：String
默认值：identity

当客户端未在请求的 Accept-Encoding 头中指定编码时，这是要使用的默认编码。

.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

在 Express 中使用此模块时，只需将模块 app.use 放到你喜欢的位置。经过此中间件的请求都将被压缩。

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

var app = express()

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

// add all routes

Node.js HTTP 服务器

var compression = require('compression')({ threshold: 0 })
var http = require('http')

function createServer (fn) {
  return http.createServer(function (req, res) {
    compression(req, res, function (err) {
      if (err) {
        res.statusCode = err.status || 500
        res.end(err.message)
        return
      }

      fn(req, res)
    })
  })
}

var server = createServer(function (req, res) {
  res.setHeader('Content-Type', 'text/plain')
  res.end('hello world!')
})

server.listen(3000, () => {
  console.log('> Listening at https://:3000')
})

服务器发送事件

由于压缩的特性，此模块无法直接与服务器发送事件（Server-Sent Events）一起工作。要压缩内容，需要缓冲一部分输出才能获得良好的压缩效果。通常在使用服务器发送事件时，有特定的数据块需要到达客户端。

你可以通过在需要数据实际到达客户端时调用 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)
  })
})

贡献

Express.js 项目欢迎所有建设性的贡献。贡献形式多样，包括错误修复和增强的代码、文档的添加和修正、额外的测试、分类传入的拉取请求和问题等等！

有关贡献的更多技术细节，请参阅贡献指南。

许可证

MIT