Node.js zlib模块所有 API 详解 + 常用 API + 使用场景
一、zlib 模块简介
zlib是 Node.js 内置的压缩模块，基于 zlib C 库实现。支持常见压缩算法：gzip、deflate、brotli。
常用于：HTTP 压缩传输、文件压缩存储、流式数据压缩。
引入模块：
const zlib = require('zlib');
二、zlib 模块 API 分类详解
1. 压缩/解压缩（同步/异步方式）
异步 API（推荐，非阻塞 IO）
zlib.gzip(buffer[, options], callback)
zlib.gunzip(buffer[, options], callback)
zlib.deflate(buffer[, options], callback)
zlib.inflate(buffer[, options], callback)
zlib.deflateRaw(buffer[, options], callback)
zlib.inflateRaw(buffer[, options], callback)
zlib.brotliCompress(buffer[, options], callback)
zlib.brotliDecompress(buffer[, options], callback)
示例：
const input = 'Hello Node.js';zlib.gzip(input, (err, result) => {if (err) throw err;console.log('压缩后:', result.toString('base64'));zlib.gunzip(result, (err, output) => {if (err) throw err;console.log('解压后:', output.toString());});
});
同步 API（阻塞线程，少用）
zlib.gzipSync(buffer[, options])
zlib.gunzipSync(buffer[, options])
zlib.deflateSync(buffer[, options])
zlib.inflateSync(buffer[, options])
zlib.deflateRawSync(buffer[, options])
zlib.inflateRawSync(buffer[, options])
zlib.brotliCompressSync(buffer[, options])
zlib.brotliDecompressSync(buffer[, options])
2. 流式压缩/解压（大文件推荐）
可用于 管道，处理大文件（如 .tar.gz），不需要一次性加载到内存。
zlib.createGzip([options])
zlib.createGunzip([options])
zlib.createDeflate([options])
zlib.createInflate([options])
zlib.createDeflateRaw([options])
zlib.createInflateRaw([options])
zlib.createBrotliCompress([options])
zlib.createBrotliDecompress([options])
示例：
const fs = require('fs');
const zlib = require('zlib');// 文件压缩
fs.createReadStream('input.txt').pipe(zlib.createGzip()).pipe(fs.createWriteStream('input.txt.gz'));// 文件解压
fs.createReadStream('input.txt.gz').pipe(zlib.createGunzip()).pipe(fs.createWriteStream('output.txt'));
3. 常见选项
level: 压缩等级（0-9，默认zlib.constants.Z_DEFAULT_COMPRESSION）windowBits: 压缩算法的滑动窗口大小memLevel: 内存使用量（1-9）strategy: 压缩策略flush: 刷新模式finishFlush: 结束刷新模式chunkSize: 默认 16KB
示例（高压缩比）：
const options = { level: zlib.constants.Z_BEST_COMPRESSION };
zlib.gzip('hello', options, (err, res) => {console.log(res.toString('base64'));
});
4. 常量
zlib.constants 提供了许多压缩参数常量：
Z_NO_COMPRESSION(0)Z_BEST_SPEED(1)Z_BEST_COMPRESSION(9)Z_DEFAULT_COMPRESSION(-1)Z_BROTLI_PARAM_QUALITY(Brotli 压缩质量 0–11)
console.log(zlib.constants.Z_BEST_COMPRESSION); // 9
三、常用 API 总结
| API | 功能 | 常用场景 |
|---|---|---|
gzip / gunzip | gzip 压缩 / 解压 | HTTP 响应压缩、日志文件压缩 |
deflate / inflate | deflate 压缩 / 解压 | 老的 HTTP 压缩协议 |
brotliCompress / brotliDecompress | Brotli 压缩 / 解压 | HTTP/2, HTTP/3 推荐算法 |
createGzip / createGunzip | 流式 gzip | 大文件压缩（如 .tar.gz） |
createBrotliCompress / createBrotliDecompress | 流式 Brotli | Web 内容压缩 |
zlib.constants | 压缩参数常量 | 调整压缩率/速度平衡 |
四、使用场景总结
1. HTTP 响应压缩
const http = require('http');
const zlib = require('zlib');http.createServer((req, res) => {const raw = 'Hello World, this is compressed!';res.writeHead(200, { 'Content-Encoding': 'gzip' });zlib.gzip(raw, (err, buffer) => {res.end(buffer);});
}).listen(3000);
2. 日志文件压缩
const fs = require('fs');
const zlib = require('zlib');fs.createReadStream('server.log').pipe(zlib.createGzip()).pipe(fs.createWriteStream('server.log.gz'));
3. 大文件解压缩
fs.createReadStream('backup.tar.gz').pipe(zlib.createGunzip()).pipe(fs.createWriteStream('backup.tar'));
4. Brotli 在前端资源压缩（HTTP/2 常用）
const input = 'Some static file content';
zlib.brotliCompress(input, {params: {[zlib.constants.BROTLI_PARAM_QUALITY]: 11, // 最优压缩}
}, (err, result) => {console.log('Brotli 压缩结果:', result.toString('base64'));
});
5. 自定义压缩等级
zlib.gzip('test', { level: zlib.constants.Z_BEST_SPEED }, (err, res) => {console.log('快速压缩:', res.length);
});zlib.gzip('test', { level: zlib.constants.Z_BEST_COMPRESSION }, (err, res) => {console.log('高压缩比:', res.length);
});
五、注意事项
异步优先：避免使用同步 API，防止阻塞事件循环。
流式操作：处理大文件时，推荐
pipe流式压缩，避免内存溢出。算法选择：
gzip → 兼容性最好
deflate → 较旧协议用
brotli → 新一代 Web 压缩（HTTP/2, HTTP/3 推荐）
压缩比与性能权衡：
压缩等级越高（9 / Brotli 11），压缩率更好但 CPU 占用更高。
✅ 总结：
zlib模块提供了 同步 / 异步 / 流式 三类 API。常用 API：
gzip/gunzip、deflate/inflate、brotliCompress/brotliDecompress、createGzip/createGunzip。典型场景：HTTP 内容压缩、日志归档、大文件存储、Web 资源优化。