Node.js ZLIB

Zlib

稳定性: 3 - 文档

可以通过以下方式访问这个模块:

var zlib = require('zlib');

这个模块提供了对 Gzip/Gunzip, Deflate/Inflate, 和 DeflateRaw/InflateRaw 类的绑定。每个类都有相同的参数和可读/写的流。

例子

压缩/解压缩一个文件，可以通过倒流（piping）一个 fs.ReadStream 到 zlib 流里来，再到一个 fs.fs.WriteStream.

var gzip = zlib.createGzip();
var fs = require('fs');
var inp = fs.createReadStream('input.txt');
var out = fs.createWriteStream('input.txt.gz');

inp.pipe(gzip).pipe(out);

一步压缩/解压缩数据可以通过一个简便方法来实现。

var input = '.................................';
zlib.deflate(input, function(err, buffer) {
  if (!err) {
    console.log(buffer.toString('base64'));
  }
});

var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
zlib.unzip(buffer, function(err, buffer) {
  if (!err) {
    console.log(buffer.toString());
  }
});

要在一个 HTTP 客户端或服务器中使用这个模块，可以在请求时使用 accept-encoding，响应时使用 content-encoding 头。

注意: 这些例子只是简单展示了基本概念。 Zlib 编码可能消耗非常大，并且结果可能要被缓存。更多使用 zlib 相关的速度/内存/压缩的权衡选择细节参见后面的 Memory Usage Tuning。

// client request example
var zlib = require('zlib');
var http = require('http');
var fs = require('fs');
var request = http.get({ host: 'izs.me',
                         path: '/',
                         port: 80,
                         headers: { 'accept-encoding': 'gzip,deflate' } });
request.on('response', function(response) {
  var output = fs.createWriteStream('izs.me_index.html');

  switch (response.headers['content-encoding']) {
    // or, just use zlib.createUnzip() to handle both cases
    case 'gzip':
      response.pipe(zlib.createGunzip()).pipe(output);
      break;
    case 'deflate':
      response.pipe(zlib.createInflate()).pipe(output);
      break;
    默认：
      response.pipe(output);
      break;
  }
});

// server example
// Running a gzip operation on every request is quite expensive.
// It would be much more efficient to cache the compressed buffer.
var zlib = require('zlib');
var http = require('http');
var fs = require('fs');
http.createServer(function(request, response) {
  var raw = fs.createReadStream('index.html');
  var acceptEncoding = request.headers['accept-encoding'];
  if (!acceptEncoding) {
    acceptEncoding = '';
  }

  // Note: this is not a conformant accept-encoding parser.
  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
  if (acceptEncoding.match(/deflate/)) {
    response.writeHead(200, { 'content-encoding': 'deflate' });
    raw.pipe(zlib.createDeflate()).pipe(response);
  } else if (acceptEncoding.match(/gzip/)) {
    response.writeHead(200, { 'content-encoding': 'gzip' });
    raw.pipe(zlib.createGzip()).pipe(response);
  } else {
    response.writeHead(200, {});
    raw.pipe(response);
  }
}).listen(1337);

zlib.createGzip([options])

根据参数 options 返回一个新的 Gzip 对象。

zlib.createGunzip([options])

根据参数 options 返回一个新的 Gunzip 对象。

zlib.createDeflate([options])

根据参数 options 返回一个新的 Deflate 对象。

zlib.createInflate([options])

根据参数 options 返回一个新的 Inflate 对象。

zlib.createDeflateRaw([options])

根据参数 options 返回一个新的 DeflateRaw 对象。

zlib.createInflateRaw([options])

根据参数 options 返回一个新的 InflateRaw 对象。

zlib.createUnzip([options])

根据参数 options 返回一个新的 Unzip 对象。

Class: zlib.Zlib

这个类未被 zlib 模块导出。之所以写在这，是因为这是压缩/解压缩类的基类。

zlib.flush([kind], callback)

参数 kind 默认为 zlib.Z_FULL_FLUSH。

刷入缓冲数据。不要轻易调用这个方法，过早的刷会对压缩算法产生负面影响。

zlib.params(level, strategy, callback)

动态更新压缩基本和压缩策略。仅对 deflate 算法有效。

zlib.reset()

重置压缩/解压缩为默认值。仅适用于 inflate 和 deflate 算法。

Class: zlib.Gzip

使用 gzip 压缩数据。

Class: zlib.Gunzip

使用 gzip 解压缩数据。

Class: zlib.Deflate

使用 deflate 压缩数据。

Class: zlib.Inflate

解压缩 deflate 流。

Class: zlib.DeflateRaw

使用 deflate 压缩数据，不需要拼接 zlib 头。

Class: zlib.InflateRaw

解压缩一个原始 deflate 流。

Class: zlib.Unzip

通过自动检测头解压缩一个 Gzip- 或 Deflate-compressed 流。

简便方法

所有的这些方法第一个参数为字符串或缓存，第二个可选参数可以供 zlib 类使用，回调函数为 callback(error, result)。

每个方法都有一个 *Sync 伴随方法，它接收相同参数，不过没有回调。

zlib.deflate(buf[, options], callback)

zlib.deflateSync(buf[, options])

使用 Deflate 压缩一个字符串。

zlib.deflateRaw(buf[, options], callback)

zlib.deflateRawSync(buf[, options])

使用 DeflateRaw 压缩一个字符串。

zlib.gzip(buf[, options], callback)

zlib.gzipSync(buf[, options])

使用 Gzip 压缩一个字符串。

zlib.gunzip(buf[, options], callback)

zlib.gunzipSync(buf[, options])

使用 Gunzip 解压缩一个原始的 Buffer。

zlib.inflate(buf[, options], callback)

zlib.inflateSync(buf[, options])

使用 Inflate 解压缩一个原始的 Buffer。

zlib.inflateRaw(buf[, options], callback)

zlib.inflateRawSync(buf[, options])

使用 InflateRaw 解压缩一个原始的 Buffer。

zlib.unzip(buf[, options], callback)

zlib.unzipSync(buf[, options])

使用 Unzip 解压缩一个原始的 Buffer。

Options

每个类都有一个选项对象。所有选项都是可选的。

注意：某些选项仅在压缩时有用，解压缩时会被忽略。

• flush (默认： zlib.Z_NO_FLUSH)
• chunkSize (默认： 16*1024)
• windowBits
• level (仅压缩有效)
• memLevel (仅压缩有效)
• strategy (仅压缩有效)
• dictionary (仅 deflate/inflate 有效, 默认为空字典)

参见 deflateInit2 和 inflateInit2 的描述，它们位于http://zlib.net/manual.html#Advanced。

使用内存调优

来自 zlib/zconf.h,修改为 node's 的用法:

deflate 的内存需求（单位：字节）：

(1 << (windowBits+2)) +  (1 << (memLevel+9))

windowBits=15 的 128K 加 memLevel = 8 的 128K （缺省值），加其他对象的若干 KB。

例如，如果你想减少默认的内存需求（从 256K 减为 128k），设置选项：

{ windowBits: 14, memLevel: 7 }

当然这通常会降低压缩等级。

inflate 的内存需求（单位：字节）：

1 << windowBits

windowBits=15 (默认值)32K 加其他对象的若干 KB。

这是除了内部输出缓冲外 chunkSize 的大小，缺省为 16K

影响 zlib 的压缩速度最大因素为 level 压缩级别。 level 越大，压缩率越高，速度越慢，level 越小，压缩率越小，速度会更快。

通常来说，使用更多的内存选项，意味着 node 必须减少对 zlib 掉哟过，因为可以在一个 write 操作里可以处理更多的数据。所以，这是另一个影响速度和内存使用率的因素，

常量

所有常量定义在 zlib.h ，也定义在 require('zlib') 。

通常的操作，基本用不到这些常量。写到文档里是想你不会对他们的存在感到惊讶。这个章节基本都来自 zlibdocumentation。更多细节参见 http://zlib.net/manual.html#Constants。

允许 flush 的值：

• zlib.Z_NO_FLUSH
• zlib.Z_PARTIAL_FLUSH
• zlib.Z_SYNC_FLUSH
• zlib.Z_FULL_FLUSH
• zlib.Z_FINISH
• zlib.Z_BLOCK
• zlib.Z_TREES

压缩/解压缩函数的返回值。负数代表错误，正数代表特殊但正常的事件：

• zlib.Z_OK
• zlib.Z_STREAM_END
• zlib.Z_NEED_DICT
• zlib.Z_ERRNO
• zlib.Z_STREAM_ERROR
• zlib.Z_DATA_ERROR
• zlib.Z_MEM_ERROR
• zlib.Z_BUF_ERROR
• zlib.Z_VERSION_ERROR

压缩级别：

• zlib.Z_NO_COMPRESSION
• zlib.Z_BEST_SPEED
• zlib.Z_BEST_COMPRESSION
• zlib.Z_DEFAULT_COMPRESSION

压缩策略：

• zlib.Z_FILTERED
• zlib.Z_HUFFMAN_ONLY
• zlib.Z_RLE
• zlib.Z_FIXED
• zlib.Z_DEFAULT_STRATEGY

data_type 字段的可能值：

• zlib.Z_BINARY
• zlib.Z_TEXT
• zlib.Z_ASCII
• zlib.Z_UNKNOWN

deflate 的压缩方法：

• zlib.Z_DEFLATED

初始化 zalloc, zfree, opaque：

• zlib.Z_NULL