# Zlib
~~~
稳定度: 3 - 稳定
~~~
你可以这样引入此模块：
~~~
var zlib = require('zlib');
~~~
这个模块提供了对Gzip/Gunzip, Deflate/Inflate和DeflateRaw/InflateRaw类的绑定。每一个类都可以接收相同的选项，并且本身也是一个可读写的Stream类。
### 例子
压缩或解压缩一个文件可以通过导流一个 fs.ReadStream 到一个 zlib 流，然后到一个 fs.WriteStream 来完成。
~~~
inp.pipe(gzip).pipe(out);
~~~
一步压缩或解压缩数据可以通过快捷方法来完成。
~~~
var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
zlib.unzip(buffer, function(err, buffer) {
if (!err) {
console.log(buffer.toString());
}
});
~~~
要在 HTTP 客户端或服务器中使用此模块，请在请求和响应中使用 [accept-encoding](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3) 和 [content-encoding](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11) 头。
**注意：这些例子只是极其简单地展示了基础的概念** Zlib 编码消耗非常大,结果需要缓存.看下面的[内存调优](#) 中更多的关于Zlib用法中 速度/内存/压缩 的权衡取舍。
~~~
// 注意: 这不是一个不合格的 accept-encoding 解析器
// 详见 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
if (acceptEncoding.match(/\bdeflate\b/)) {
response.writeHead(200, { 'content-encoding': 'deflate' });
raw.pipe(zlib.createDeflate()).pipe(response);
} else if (acceptEncoding.match(/\bgzip\b/)) {
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](#) 对象。
### 类: zlib.Zlib
这个类未被 `zlib` 模块导出，编入此文档是因为它是其它压缩器/解压缩器的基类。
### zlib.flush([kind], callback)
`kind` 缺省为 `zlib.Z_FULL_FLUSH`。
写入缓冲数据。请勿轻易调用此方法，过早的写入会对压缩算法的作用产生影响。
### zlib.params(level, strategy, callback)
动态更新压缩级别和压缩策略。仅对 deflate 算法有效。
### zlib.reset()
将压缩器/解压缩器重置为缺省值。仅对 inflate 和 deflate 算法有效。
### 类: zlib.Gzip
使用 gzip 压缩数据。
### 类: zlib.Gunzip
解压缩一个 gzip 流。
### 类: zlib.Deflate
使用 deflate 压缩数据。
### 类: zlib.Inflate
解压缩一个 deflate 流。
### 类: zlib.DeflateRaw
使用 deflate 压缩数据，并且不附带 zlib 头。
### 类: zlib.InflateRaw
解压缩一个原始 deflate 流。
### 类: zlib.Unzip
自动识别头部来解压缩一个以 gzip 或 deflate 压缩的流。
### 快捷方法
所有这些方法的第一个参数都可以是字符串或 Buffer；可选地可以将传给 zlib 类的选项作为第二个参数传入；回调格式为 `callback(error, result)`。
### zlib.deflate(buf, [options], callback)
使用 Deflate 压缩一个字符串。
### zlib.deflateRaw(buf, [options], callback)
使用 DeflateRaw 压缩一个字符串。
### zlib.Gzip(buf, [options], callback)
使用 Gzip 压缩一个字符串。
### zlib.gunzip(buf, [options], callback)
使用 Gunzip 解压缩一个原始的 Buffer。
### zlib.inflate(buf, [options], callback)
使用 Inflate 解压缩一个原始的 Buffer。
### zlib.inflateRaw(buf, [options], callback)
使用 InflateRaw 解压缩一个原始的 Buffer。
### zlib.unzip(buf, [options], callback)
使用 Unzip 解压缩一个原始的 Buffer。
### 选项
各个类都有一个选项对象。所有选项都是可选的。
请注意有些选项仅对压缩有效，并会被解压缩类所忽略。
- flush（缺省：`zlib.Z_NO_FLUSH`）
- chunkSize（缺省：16*1024）
- windowBits
- level（仅用于压缩）
- memLevel（仅用于压缩）
- strategy（仅用于压缩）
- dictionary（仅用于 deflate/inflate，缺省为空目录）
详情请参阅 [http://zlib.net/manual.html#Advanced](http://zlib.net/manual.html#Advanced) 的 `deflateInit2` 和 `inflateInit2`。
### 内存使用调优
来自 `zlib/zconf.h`，修改为 node 的用法：
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` 的影响。更高的压缩级别会有更好的压缩率，但也要花费更长时间。更低的压缩级别会有较低压缩率，但速度更快。
通常，使用更多内存的选项意味着 node 能减少对 zlib 的调用，因为单次 `write`操作能处理更多数据。因此，这是另一个影响速度和内存占用的因素。
### 常量
所有在 zlib.h 中定义的常量同样也定义在 `require('zlib')` 中。 在通常情况下您几乎不会用到它们，编入文档只是为了让您不会对它们的存在感到惊讶。该章节几乎完全来自 [zlib 的文档](http://zlib.net/manual.html#Constants)。详见 [http://zlib.net/manual.html#Constants](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`
