注意
此页面由 compression README 生成。compression
Node.js 压缩中间件。
支持以下压缩编码
- deflate
- gzip
- br (brotli)
注意 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)。
-1
默认压缩级别(也为zlib.constants.Z_DEFAULT_COMPRESSION
)。0
无压缩(也为zlib.constants.Z_NO_COMPRESSION
)。1
最快压缩(也为zlib.constants.Z_BEST_SPEED
)。2
3
4
5
6
(目前zlib.constants.Z_DEFAULT_COMPRESSION
指向的值)。7
8
9
最佳压缩(也为zlib.constants.Z_BEST_COMPRESSION
)。
注意 在以上列表中,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.constants.Z_DEFAULT_STRATEGY
用于普通数据。zlib.constants.Z_FILTERED
用于过滤器(或预测器)生成的数据。过滤后的数据主要由具有某种随机分布的小值组成。在这种情况下,压缩算法会进行调整以更好地压缩它们。其效果是强制进行更多霍夫曼编码和更少字符串匹配;它介于zlib.constants.Z_DEFAULT_STRATEGY
和zlib.constants.Z_HUFFMAN_ONLY
之间。zlib.constants.Z_FIXED
用于阻止使用动态霍夫曼编码,从而允许为特殊应用提供更简单的解码器。zlib.constants.Z_HUFFMAN_ONLY
用于强制仅进行霍夫曼编码(无字符串匹配)。zlib.constants.Z_RLE
用于将匹配距离限制为一(游程编码)。它旨在实现与zlib.constants.Z_HUFFMAN_ONLY
几乎相同的速度,但能为 PNG 图像数据提供更好的压缩。
注意 在以上列表中,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 http://localhost: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 项目欢迎所有建设性的贡献。贡献形式多样,包括错误修复和增强的代码、文档的添加和修正、额外的测试、分类传入的拉取请求和问题等等!
有关贡献的更多技术细节,请参阅贡献指南。