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);
});

---

五、注意事项

1. 异步优先：避免使用同步 API，防止阻塞事件循环。

2. 流式操作 ：处理大文件时，推荐 pipe 流式压缩，避免内存溢出。

3. 算法选择：

   • gzip → 兼容性最好

   • deflate → 较旧协议用

   • brotli → 新一代 Web 压缩（HTTP/2, HTTP/3 推荐）

4. 压缩比与性能权衡：

   • 压缩等级越高（9 / Brotli 11），压缩率更好但 CPU 占用更高。

---

✅ 总结：

• zlib 模块提供了 同步 / 异步 / 流式 三类 API。

• 常用 API：gzip/gunzip、deflate/inflate、brotliCompress/brotliDecompress、createGzip/createGunzip。

• 典型场景：HTTP 内容压缩 、日志归档 、大文件存储 、Web 资源优化。