Zlib

[稳定: 2 - 稳定]

node:zlib 模块提供使用 Gzip、Deflate/Inflate 和 Brotli 实现的压缩功能。

访问方式：

ESMCJS

import os from 'node:zlib'

const zlib = require('node:zlib')

压缩和解压缩基于 Node.js 的流 API。

通过将源流通过 zlib Transform 流传递到目标流来完成流（例如文件）的压缩或解压缩：

ESMCJS

import { createReadStream, createWriteStream } from 'node:fs'
import process from 'node:process'
import { createGzip } from 'node:zlib'
import { pipeline } from 'node:stream'

const gzip = createGzip()
const source = createReadStream('input.txt')
const destination = createWriteStream('input.txt.gz')

pipeline(source, gzip, destination, err => {
  if (err) {
    console.error('An error occurred:', err)
    process.exitCode = 1
  }
})

const { createReadStream, createWriteStream } = require('node:fs')
const process = require('node:process')
const { createGzip } = require('node:zlib')
const { pipeline } = require('node:stream')

const gzip = createGzip()
const source = createReadStream('input.txt')
const destination = createWriteStream('input.txt.gz')

pipeline(source, gzip, destination, err => {
  if (err) {
    console.error('An error occurred:', err)
    process.exitCode = 1
  }
})

或者，使用 promise pipeline API：

ESMCJS

import { createReadStream, createWriteStream } from 'node:fs'
import process from 'node:process'
import { createGzip } from 'node:zlib'
import { pipeline } from 'node:stream/promises'

async function do_gzip(input, output) {
  const gzip = createGzip()
  const source = createReadStream(input)
  const destination = createWriteStream(output)
  await pipeline(source, gzip, destination)
}

await do_gzip('input.txt', 'input.txt.gz')

const { createReadStream, createWriteStream } = require('node:fs')
const process = require('node:process')
const { createGzip } = require('node:zlib')
const { pipeline } = require('node:stream/promises')

async function do_gzip(input, output) {
  const gzip = createGzip()
  const source = createReadStream(input)
  const destination = createWriteStream(output)
  await pipeline(source, gzip, destination)
}

do_gzip('input.txt', 'input.txt.gz').catch(err => {
  console.error('An error occurred:', err)
  process.exitCode = 1
})

也可以一步压缩或解压缩数据：

ESMCJS

import process from 'node:process'
import { Buffer } from 'node:buffer'
import { deflate, unzip } from 'node:zlib'

const input = '.................................'
deflate(input, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString('base64'))
})

const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64')
unzip(buffer, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString())
})

// Or, Promisified

import { promisify } from 'node:util'
const do_unzip = promisify(unzip)

const unzippedBuffer = await do_unzip(buffer)
console.log(unzippedBuffer.toString())

const { deflate, unzip } = require('node:zlib')

const input = '.................................'
deflate(input, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString('base64'))
})

const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64')
unzip(buffer, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString())
})

// Or, Promisified

const { promisify } = require('node:util')
const do_unzip = promisify(unzip)

do_unzip(buffer)
  .then(buf => console.log(buf.toString()))
  .catch(err => {
    console.error('An error occurred:', err)
    process.exitCode = 1
  })

线程池使用和性能注意事项

除明确声明为同步的 API 外，所有 zlib API 都使用 Node.js 内部线程池。这可能会在某些应用程序中导致意想不到的效果和性能限制。

同时创建和使用大量 zlib 对象可能会导致严重的内存碎片。

ESMCJS

import zlib from 'node:zlib'
import { Buffer } from 'node:buffer'

const payload = Buffer.from('This is some data')

// WARNING: DO NOT DO THIS!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {})
}

const zlib = require('node:zlib')

const payload = Buffer.from('This is some data')

// WARNING: DO NOT DO THIS!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {})
}

在前面的示例中，并发创建了 30,000 个 deflate 实例。由于某些操作系统处理内存分配和释放的方式，这可能会导致严重的内存碎片。

强烈建议缓存压缩操作的结果，以避免重复工作。

压缩 HTTP 请求和响应

node:zlib 模块可用于实现由 HTTP 定义的 gzip、deflate 和 br 内容编码机制的支持。

HTTP Accept-Encoding 头部用于 HTTP 请求中，以标识客户端接受的压缩编码。Content-Encoding 头部用于标识实际应用于消息的压缩编码。

以下示例进行了大幅简化，以展示基本概念。使用 zlib 编码可能代价高昂，结果应该被缓存。有关 zlib 使用中涉及的速度/内存/压缩权衡的更多信息，请参阅内存使用调整。

ESMCJS

// 客户端请求示例
import fs from 'node:fs'
import zlib from 'node:zlib'
import http from 'node:http'
import process from 'node:process'
import { pipeline } from 'node:stream'

const request = http.get({
  host: 'example.com',
  path: '/',
  port: 80,
  headers: { 'Accept-Encoding': 'br,gzip,deflate' },
})
request.on('response', response => {
  const output = fs.createWriteStream('example.com_index.html')

  const onError = err => {
    if (err) {
      console.error('An error occurred:', err)
      process.exitCode = 1
    }
  }

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError)
      break
    // 或，只需使用 zlib.createUnzip() 来处理以下两种情况：
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError)
      break
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError)
      break
    default:
      pipeline(response, output, onError)
      break
  }
})

// 客户端请求示例
const zlib = require('node:zlib')
const http = require('node:http')
const fs = require('node:fs')
const { pipeline } = require('node:stream')

const request = http.get({
  host: 'example.com',
  path: '/',
  port: 80,
  headers: { 'Accept-Encoding': 'br,gzip,deflate' },
})
request.on('response', response => {
  const output = fs.createWriteStream('example.com_index.html')

  const onError = err => {
    if (err) {
      console.error('An error occurred:', err)
      process.exitCode = 1
    }
  }

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError)
      break
    // 或，只需使用 zlib.createUnzip() 来处理以下两种情况：
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError)
      break
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError)
      break
    default:
      pipeline(response, output, onError)
      break
  }
})

ESMCJS

// 服务器示例
// 对每个请求运行 gzip 操作非常昂贵。
// 缓存压缩缓冲区会效率得多。
import zlib from 'node:zlib'
import http from 'node:http'
import fs from 'node:fs'
import { pipeline } from 'node:stream'

http
  .createServer((request, response) => {
    const raw = fs.createReadStream('index.html')
    // 存储资源的压缩版本和未压缩版本。
    response.setHeader('Vary', 'Accept-Encoding')
    const acceptEncoding = request.headers['accept-encoding'] || ''

    const onError = err => {
      if (err) {
        // 如果发生错误，我们几乎无能为力，因为
        // 服务器已经发送了 200 响应代码，并且
        // 一些数据已经发送到客户端。
        // 我们能做的最好的事情是立即终止响应
        // 并记录错误。
        response.end()
        console.error('An error occurred:', err)
      }
    }

    // 注意：这不是符合规范的 accept-encoding 解析器。
    // 请参阅 https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
    if (/\bdeflate\b/.test(acceptEncoding)) {
      response.writeHead(200, { 'Content-Encoding': 'deflate' })
      pipeline(raw, zlib.createDeflate(), response, onError)
    } else if (/\bgzip\b/.test(acceptEncoding)) {
      response.writeHead(200, { 'Content-Encoding': 'gzip' })
      pipeline(raw, zlib.createGzip(), response, onError)
    } else if (/\bbr\b/.test(acceptEncoding)) {
      response.writeHead(200, { 'Content-Encoding': 'br' })
      pipeline(raw, zlib.createBrotliCompress(), response, onError)
    } else {
      response.writeHead(200, {})
      pipeline(raw, response, onError)
    }
  })
  .listen(1337)

// 服务器示例
// 对每个请求运行 gzip 操作非常昂贵。
// 缓存压缩缓冲区会效率得多。
const zlib = require('node:zlib')
const http = require('node:http')
const fs = require('node:fs')
const { pipeline } = require('node:stream')

http
  .createServer((request, response) => {
    const raw = fs.createReadStream('index.html')
    // 存储资源的压缩版本和未压缩版本。
    response.setHeader('Vary', 'Accept-Encoding')
    const acceptEncoding = request.headers['accept-encoding'] || ''

    const onError = err => {
      if (err) {
        // 如果发生错误，我们几乎无能为力，因为
        // 服务器已经发送了 200 响应代码，并且
        // 一些数据已经发送到客户端。
        // 我们能做的最好的事情是立即终止响应
        // 并记录错误。
        response.end()
        console.error('An error occurred:', err)
      }
    }

    // 注意：这不是符合规范的 accept-encoding 解析器。
    // 请参阅 https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
    if (/\bdeflate\b/.test(acceptEncoding)) {
      response.writeHead(200, { 'Content-Encoding': 'deflate' })
      pipeline(raw, zlib.createDeflate(), response, onError)
    } else if (/\bgzip\b/.test(acceptEncoding)) {
      response.writeHead(200, { 'Content-Encoding': 'gzip' })
      pipeline(raw, zlib.createGzip(), response, onError)
    } else if (/\bbr\b/.test(acceptEncoding)) {
      response.writeHead(200, { 'Content-Encoding': 'br' })
      pipeline(raw, zlib.createBrotliCompress(), response, onError)
    } else {
      response.writeHead(200, {})
      pipeline(raw, response, onError)
    }
  })
  .listen(1337)

默认情况下，zlib 方法在解压缩截断数据时会抛出错误。但是，如果已知数据不完整，或者只想检查压缩文件开头，则可以通过更改用于解压缩最后输入数据块的刷新方法来抑制默认错误处理：

// 这是上面示例中缓冲区的截断版本
const buffer = Buffer.from('eJzT0yMA', 'base64')

zlib.unzip(
  buffer,
  // 对于 Brotli，等效项是 zlib.constants.BROTLI_OPERATION_FLUSH。
  { finishFlush: zlib.constants.Z_SYNC_FLUSH },
  (err, buffer) => {
    if (err) {
      console.error('An error occurred:', err)
      process.exitCode = 1
    }
    console.log(buffer.toString())
  }
)

这不会改变其他抛出错误的情况下的行为，例如，当输入数据格式无效时。使用此方法，将无法确定输入是否过早结束或缺少完整性检查，因此需要手动检查解压缩的结果是否有效。

内存使用调整

基于 zlib 的流

来自 zlib/zconf.h，为 Node.js 使用进行了修改：

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

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

也就是说：windowBits = 15 为 128K + memLevel = 8 (默认值) 为 128K，加上少量用于小型对象的千字节。

例如，要将默认内存需求从 256K 减少到 128K，应将选项设置为：

const options = { windowBits: 14, memLevel: 7 }

但是，这通常会降低压缩率。

inflate 的内存需求（以字节为单位）是 1 << windowBits。也就是说，windowBits = 15（默认值）为 32K，加上少量用于小型对象的千字节。

这之外还有一个大小为 chunkSize 的单个内部输出内存块缓冲区，默认为 16K。

zlib 压缩的速度受 level 设置的影响最大。较高的级别将导致更好的压缩率，但完成时间更长。较低的级别将导致压缩率较低，但速度更快。

通常，更大的内存使用选项意味着 Node.js 必须更少地调用 zlib，因为它能够在每次 write 操作中处理更多数据。因此，这是影响速度的另一个因素，但代价是内存使用。

基于 Brotli 的流

基于 Brotli 的流也有与 zlib 选项等效的选项，尽管这些选项的范围与 zlib 选项不同：

zlib 的 level 选项与 Brotli 的 BROTLI_PARAM_QUALITY 选项匹配。
zlib 的 windowBits 选项与 Brotli 的 BROTLI_PARAM_LGWIN 选项匹配。

有关 Brotli 特定选项的更多详细信息，请参阅此处。

刷新

在压缩流上调用 .flush() 将使 zlib 返回当前尽可能多的输出。这可能会以压缩质量下降为代价，但在需要尽快获得数据时非常有用。

在下面的示例中，flush() 用于向客户端写入压缩的部分 HTTP 响应：

ESMCJS

import zlib from 'node:zlib'
import http from 'node:http'
import { pipeline } from 'node:stream'

http
  .createServer((request, response) => {
    // 为简单起见，省略了 Accept-Encoding 检查。
    response.writeHead(200, { 'content-encoding': 'gzip' })
    const output = zlib.createGzip()
    let i

    pipeline(output, response, err => {
      if (err) {
        // 如果发生错误，我们无能为力，因为
        // 服务器已经发送了 200 响应代码，
        // 并且已经向客户端发送了一些数据。
        // 我们能做的最好的事情是立即终止响应
        // 并记录错误。
        clearInterval(i)
        response.end()
        console.error('An error occurred:', err)
      }
    })

    i = setInterval(() => {
      output.write(`The current time is ${Date()}\n`, () => {
        // 数据已传递给 zlib，但压缩算法可能
        // 已决定缓冲数据以实现更有效的压缩。
        // 调用 .flush() 将使数据尽快可用，以便客户端
        // 准备好接收它。
        output.flush()
      })
    }, 1000)
  })
  .listen(1337)

const zlib = require('node:zlib')
const http = require('node:http')
const { pipeline } = require('node:stream')

http
  .createServer((request, response) => {
    // 为简单起见，省略了 Accept-Encoding 检查。
    response.writeHead(200, { 'content-encoding': 'gzip' })
    const output = zlib.createGzip()
    let i

    pipeline(output, response, err => {
      if (err) {
        // 如果发生错误，我们无能为力，因为
        // 服务器已经发送了 200 响应代码，
        // 并且已经向客户端发送了一些数据。
        // 我们能做的最好的事情是立即终止响应
        // 并记录错误。
        clearInterval(i)
        response.end()
        console.error('An error occurred:', err)
      }
    })

    i = setInterval(() => {
      output.write(`The current time is ${Date()}\n`, () => {
        // 数据已传递给 zlib，但压缩算法可能
        // 已决定缓冲数据以实现更有效的压缩。
        // 调用 .flush() 将使数据尽快可用，以便客户端
        // 准备好接收它。
        output.flush()
      })
    }, 1000)
  })
  .listen(1337)

常量

新增于：v0.5.8

zlib 常量

zlib.h 中定义的所有常量也在 require('node:zlib').constants 中定义。在正常的运行过程中，不需要使用这些常量。对其进行文档记录是为了避免它们的出现令人意外。本节内容几乎直接摘自 zlib 文档。

以前，可以直接从 require('node:zlib') 访问这些常量，例如 zlib.Z_NO_FLUSH。目前仍然可以从模块直接访问这些常量，但这已弃用。

允许的刷新值：

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

压缩/解压函数的返回码。负值表示错误，正值用于特殊但正常的事件。

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

压缩级别：

zlib.constants.Z_NO_COMPRESSION
zlib.constants.Z_BEST_SPEED
zlib.constants.Z_BEST_COMPRESSION
zlib.constants.Z_DEFAULT_COMPRESSION

压缩策略：

zlib.constants.Z_FILTERED
zlib.constants.Z_HUFFMAN_ONLY
zlib.constants.Z_RLE
zlib.constants.Z_FIXED
zlib.constants.Z_DEFAULT_STRATEGY

Brotli 常量

新增于：v11.7.0, v10.16.0

Brotli 基于流的压缩方式提供了多个选项和常量：

刷新操作

以下值是 Brotli 基于流的有效刷新操作：

zlib.constants.BROTLI_OPERATION_PROCESS（所有操作的默认值）
zlib.constants.BROTLI_OPERATION_FLUSH（调用 .flush() 时的默认值）
zlib.constants.BROTLI_OPERATION_FINISH（最后一个块的默认值）
zlib.constants.BROTLI_OPERATION_EMIT_METADATA
- 在 Node.js 环境中，此操作可能难以使用，因为流层难以确定哪些数据最终会进入此帧。此外，目前无法通过 Node.js API 使用此数据。

压缩器选项

Brotli 编码器可以设置多个选项，影响压缩效率和速度。键和值都可以作为 zlib.constants 对象的属性访问。

最重要的选项包括：

BROTLI_PARAM_MODE
- BROTLI_MODE_GENERIC（默认）
- BROTLI_MODE_TEXT，针对 UTF-8 文本调整
- BROTLI_MODE_FONT，针对 WOFF 2.0 字体调整
BROTLI_PARAM_QUALITY
- 范围从 BROTLI_MIN_QUALITY 到 BROTLI_MAX_QUALITY，默认为 BROTLI_DEFAULT_QUALITY。
BROTLI_PARAM_SIZE_HINT
- 表示预期输入大小的整数值；对于未知输入大小，默认为 0。

以下标志可以用于高级控制压缩算法和内存使用调整：

BROTLI_PARAM_LGWIN
- 范围从 BROTLI_MIN_WINDOW_BITS 到 BROTLI_MAX_WINDOW_BITS，默认为 BROTLI_DEFAULT_WINDOW，如果设置了 BROTLI_PARAM_LARGE_WINDOW 标志，则最多可达 BROTLI_LARGE_MAX_WINDOW_BITS。
BROTLI_PARAM_LGBLOCK
- 范围从 BROTLI_MIN_INPUT_BLOCK_BITS 到 BROTLI_MAX_INPUT_BLOCK_BITS。
BROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING
- 布尔标志，它降低压缩率以提高解压缩速度。
BROTLI_PARAM_LARGE_WINDOW
- 布尔标志，启用“大窗口 Brotli”模式（与 RFC 7932 中标准化的 Brotli 格式不兼容）。
BROTLI_PARAM_NPOSTFIX
- 范围从 0 到 BROTLI_MAX_NPOSTFIX。
BROTLI_PARAM_NDIRECT
- 范围从 0 到 15 \<\< NPOSTFIX，步长为 1 \<\< NPOSTFIX。

解压缩选项

以下高级选项可用于控制解压缩：

BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION
- 布尔标志，影响内部内存分配模式。
BROTLI_DECODER_PARAM_LARGE_WINDOW
- 布尔标志，启用“大窗口 Brotli”模式（与RFC 7932中标准化的 Brotli 格式不兼容）。

类: `Options`

[历史]

版本	变更
v14.5.0, v12.19.0	现在支持 `maxOutputLength` 选项。
v9.4.0	`dictionary` 选项可以是 `ArrayBuffer`。
v8.0.0	`dictionary` 选项现在可以是 `Uint8Array`。
v5.11.0	现在支持 `finishFlush` 选项。
v0.11.1	新增于：v0.11.1

每个基于 zlib 的类都接受一个 options 对象。无需任何选项。

某些选项仅在压缩时相关，解压缩类会忽略这些选项。

flush <整数> 默认值： zlib.constants.Z_NO_FLUSH
finishFlush <整数> 默认值： zlib.constants.Z_FINISH
chunkSize <整数> 默认值： 16 * 1024
windowBits <整数>
level <整数> (仅压缩)
memLevel <整数> (仅压缩)
strategy <整数> (仅压缩)
dictionary <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> (仅限 deflate/inflate，默认为空字典)
info <布尔值> (如果为 true，则返回包含 buffer 和 engine 的对象。)
maxOutputLength <整数> 使用便捷方法时限制输出大小。默认值： buffer.kMaxLength

有关更多信息，请参阅deflateInit2 和 inflateInit2 文档。

类: `BrotliOptions`

[历史]

版本	变更
v14.5.0, v12.19.0	现在支持 `maxOutputLength` 选项。
v11.7.0	新增于：v11.7.0

每个基于 Brotli 的类都接受一个 options 对象。所有选项都是可选的。

flush <整数> 默认值: zlib.constants.BROTLI_OPERATION_PROCESS
finishFlush <整数> 默认值: zlib.constants.BROTLI_OPERATION_FINISH
chunkSize <整数> 默认值: 16 * 1024
params <对象> 包含索引的 Brotli 参数的键值对对象。
maxOutputLength <整数> 使用便捷方法时限制输出大小。默认值: buffer.kMaxLength

例如：

const stream = zlib.createBrotliCompress({
  chunkSize: 32 * 1024,
  params: {
    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
    [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
    [zlib.constants.BROTLI_PARAM_SIZE_HINT]: fs.statSync(inputFile).size,
  },
})

类: `zlib.BrotliCompress`

新增于: v11.7.0, v10.16.0

使用 Brotli 算法压缩数据。

类: `zlib.BrotliDecompress`

新增于: v11.7.0, v10.16.0

使用 Brotli 算法解压缩数据。

类: `zlib.Deflate`

新增于: v0.5.8

使用 deflate 压缩数据。

类: `zlib.DeflateRaw`

新增于: v0.5.8

使用 deflate 压缩数据，并且不附加 zlib 头。

类: `zlib.Gunzip`

[历史]

版本	变更
v6.0.0	输入流末尾的尾随垃圾现在将导致 `'error'` 事件。
v5.9.0	现在支持多个连接的 gzip 文件成员。
v5.0.0	截断的输入流现在将导致 `'error'` 事件。
v0.5.8	新增于: v0.5.8

解压缩 gzip 流。

类: `zlib.Gzip`

新增于: v0.5.8

使用 gzip 压缩数据。

类: `zlib.Inflate`

[历史]

版本	变更
v5.0.0	截断的输入流现在将导致 `'error'` 事件。
v0.5.8	新增于: v0.5.8

解压缩 deflate 流。

类: `zlib.InflateRaw`

[历史]

版本	变更
v6.8.0	`InflateRaw` 现在支持自定义字典。
v5.0.0	截断的输入流现在将导致 `'error'` 事件。
v0.5.8	新增于：v0.5.8

解压缩原始 deflate 流。

类: `zlib.Unzip`

新增于：v0.5.8

通过自动检测头部解压缩 Gzip 或 Deflate 压缩流。

类: `zlib.ZlibBase`

[历史]

版本	变更
v11.7.0, v10.16.0	此类已从 `Zlib` 重命名为 `ZlibBase`。
v0.5.8	新增于：v0.5.8

node:zlib 模块未导出。此处对其进行文档说明，因为它是在压缩器/解压缩器类的基类。

此类继承自 stream.Transform，允许在管道和类似流操作中使用 node:zlib 对象。

`zlib.bytesWritten`

新增于：v10.0.0

<数字>

zlib.bytesWritten 属性指定写入引擎的字节数，在字节被处理（压缩或解压缩，取决于派生类）之前。

`zlib.crc32(data[, value])`

新增于：v22.2.0, v20.15.0

data <字符串> | <Buffer> | <TypedArray> | <DataView> 当 data 为字符串时，它将在使用前被编码为 UTF-8。
value <整数> 可选的起始值。它必须是一个 32 位无符号整数。默认值： 0
返回值： <整数> 一个包含校验和的 32 位无符号整数。

计算 data 的 32 位循环冗余校验校验和。如果指定了 value，则将其用作校验和的起始值，否则使用 0 作为起始值。

CRC 算法旨在计算校验和并检测数据传输中的错误。它不适用于加密身份验证。

为了与其他 API 保持一致，如果 data 是字符串，它将在使用前使用 UTF-8 编码。如果用户仅使用 Node.js 计算和匹配校验和，则此方法与默认使用 UTF-8 编码的其他 API 兼容良好。

一些第三方 JavaScript 库基于 str.charCodeAt() 计算字符串的校验和，以便它可以在浏览器中运行。如果用户希望匹配使用这种库在浏览器中计算的校验和，最好在 Node.js 中使用相同的库（如果它也运行在 Node.js 中）。如果用户必须使用 zlib.crc32() 来匹配这种第三方库生成的校验和：

ESMCJS

import zlib from 'node:zlib'
import { Buffer } from 'node:buffer'

let crc = zlib.crc32('hello') // 907060870
crc = zlib.crc32('world', crc) // 4192936109

crc = zlib.crc32(Buffer.from('hello', 'utf16le')) // 1427272415
crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc) // 4150509955

const zlib = require('node:zlib')
const { Buffer } = require('node:buffer')

let crc = zlib.crc32('hello') // 907060870
crc = zlib.crc32('world', crc) // 4192936109

crc = zlib.crc32(Buffer.from('hello', 'utf16le')) // 1427272415
crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc) // 4150509955

`zlib.close([callback])`

新增于：v0.9.4

callback <Function>

关闭底层句柄。

`zlib.flush([kind, ]callback)`

新增于：v0.5.8

kind **默认值：**对于基于 zlib 的流，为 zlib.constants.Z_FULL_FLUSH；对于基于 Brotli 的流，为 zlib.constants.BROTLI_OPERATION_FLUSH。
callback <Function>

刷新待处理数据。不要随意调用此函数，过早刷新会对压缩算法的有效性产生负面影响。

调用此函数只会刷新内部 zlib 状态中的数据，不会对流级别执行任何类型的刷新。相反，它的行为类似于对 .write() 的普通调用，即它将在其他待处理写入之后排队，并且只有在从流中读取数据时才会产生输出。

`zlib.params(level, strategy, callback)`

新增于：v0.11.4

level <integer>
strategy <integer>
callback <Function>

此函数仅适用于基于 zlib 的流，即不适用于 Brotli。

动态更新压缩级别和压缩策略。仅适用于 deflate 算法。

`zlib.reset()`

新增于：v0.7.0

将压缩器/解压缩器重置为出厂默认设置。仅适用于 inflate 和 deflate 算法。

`zlib.constants`

新增于：v7.0.0

提供一个枚举 Zlib 相关常量的对象。

`zlib.createBrotliCompress([options])`

新增于：v11.7.0, v10.16.0

options <brotli 选项>

创建并返回一个新的 BrotliCompress 对象。

`zlib.createBrotliDecompress([options])`

新增于：v11.7.0, v10.16.0

options <brotli 选项>

创建并返回一个新的 BrotliDecompress 对象。

`zlib.createDeflate([options])`

新增于：v0.5.8

options <zlib 选项>

创建并返回一个新的 Deflate 对象。

`zlib.createDeflateRaw([options])`

新增于：v0.5.8

options <zlib 选项>

创建并返回一个新的 DeflateRaw 对象。

将 zlib 从 1.2.8 升级到 1.2.11 改变了当 windowBits 设置为 8 用于原始 deflate 流时的行为。zlib 会自动将 windowBits 设置为 9，如果它最初设置为 8。较新的 zlib 版本将抛出异常，因此 Node.js 恢复了将 8 的值升级到 9 的原始行为，因为将 windowBits = 9 传递给 zlib 实际上会产生一个有效地仅使用 8 位窗口的压缩流。

`zlib.createGunzip([options])`

新增于：v0.5.8

options <zlib options>

创建一个并返回新的 Gunzip 对象。

`zlib.createGzip([options])`

新增于：v0.5.8

options <zlib options>

创建一个并返回新的 Gzip 对象。参见示例。

`zlib.createInflate([options])`

新增于：v0.5.8

options <zlib options>

创建一个并返回新的 Inflate 对象。

`zlib.createInflateRaw([options])`

新增于：v0.5.8

options <zlib options>

创建一个并返回新的 InflateRaw 对象。

`zlib.createUnzip([options])`

新增于：v0.5.8

options <zlib options>

创建一个并返回新的 Unzip 对象。

方便方法

所有这些方法都接受 Buffer、TypedArray、DataView、ArrayBuffer 或字符串作为第一个参数，一个可选的第二个参数来为 zlib 类提供选项，并将使用 callback(error, result) 调用提供的回调函数。

每个方法都有一个 *Sync 对应方法，它们接受相同的参数，但没有回调函数。

`zlib.brotliCompress(buffer[, options], callback)`

新增于: v11.7.0, v10.16.0

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <brotli options>
callback <Function>

`zlib.brotliCompressSync(buffer[, options])`

新增于: v11.7.0, v10.16.0

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <brotli options>

使用 BrotliCompress 压缩数据块。

`zlib.brotliDecompress(buffer[, options], callback)`

新增于：v11.7.0, v10.16.0

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <brotli options>
callback <Function>

`zlib.brotliDecompressSync(buffer[, options])`

新增于：v11.7.0, v10.16.0

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <brotli options>

使用 BrotliDecompress 解压缩数据块。

`zlib.deflate(buffer[, options], callback)`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.6.0	v0.6.0 版本中添加

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <字符串>
options <zlib 选项>
callback <函数>

`zlib.deflateSync(buffer[, options])`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.11.12	新增于：v0.11.12

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>

使用 Deflate 压缩数据块。

`zlib.deflateRaw(buffer[, options], callback)`

[历史]

版本	变更
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.6.0	新增于：v0.6.0

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>
callback <函数>

`zlib.deflateRawSync(buffer[, options])`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.11.12	v0.11.12 版本中添加

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>

使用 DeflateRaw 压缩数据块。

`zlib.gunzip(buffer[, options], callback)`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.6.0	v0.6.0 版本中添加

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>
callback <函数>

`zlib.gunzipSync(buffer[, options])`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任意 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.11.12	v0.11.12 版本中添加

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>

使用 Gunzip 解压缩数据块。

`zlib.gzip(buffer[, options], callback)`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任意 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.6.0	v0.6.0 版本中添加

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>
callback <函数>

`zlib.gzipSync(buffer[, options])`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任意 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.11.12	添加于：v0.11.12

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>

使用 Gzip 压缩数据块。

`zlib.inflate(buffer[, options], callback)`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任意 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.6.0	添加于：v0.6.0

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>
callback <函数>

`zlib.inflateSync(buffer[, options])`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任意 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.11.12	v0.11.12 版本添加

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>

使用 Inflate 解压缩数据块。

`zlib.inflateRaw(buffer[, options], callback)`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任意 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.6.0	v0.6.0 版本添加

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>
callback <函数>

`zlib.inflateRawSync(buffer[, options])`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.11.12	新增于：v0.11.12

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>

使用 InflateRaw 解压缩数据块。

`zlib.unzip(buffer[, options], callback)`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.6.0	新增于：v0.6.0

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>
callback <函数>

`zlib.unzipSync(buffer[, options])`

[历史]

版本	变更
v9.4.0	`buffer` 参数可以是 `ArrayBuffer`。
v8.0.0	`buffer` 参数可以是任何 `TypedArray` 或 `DataView`。
v8.0.0	`buffer` 参数现在可以是 `Uint8Array`。
v0.11.12	新增于：v0.11.12

buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
options <zlib 选项>

使用 Unzip 解压缩数据块。

Zlib ​

线程池使用和性能注意事项 ​

压缩 HTTP 请求和响应 ​

内存使用调整 ​

基于 zlib 的流 ​

基于 Brotli 的流 ​

刷新 ​

常量 ​

zlib 常量 ​

Brotli 常量 ​

刷新操作 ​

压缩器选项 ​

解压缩选项 ​

类: Options ​

类: BrotliOptions ​

类: zlib.BrotliCompress ​

类: zlib.BrotliDecompress ​

类: zlib.Deflate ​

类: zlib.DeflateRaw ​

类: zlib.Gunzip ​

类: zlib.Gzip ​

类: zlib.Inflate ​

类: zlib.InflateRaw ​

类: zlib.Unzip ​

类: zlib.ZlibBase ​

zlib.bytesWritten ​

zlib.crc32(data[, value]) ​

zlib.close([callback]) ​

zlib.flush([kind, ]callback) ​

zlib.params(level, strategy, callback) ​

zlib.reset() ​

zlib.constants ​

zlib.createBrotliCompress([options]) ​

zlib.createBrotliDecompress([options]) ​

zlib.createDeflate([options]) ​

zlib.createDeflateRaw([options]) ​

zlib.createGunzip([options]) ​

zlib.createGzip([options]) ​

zlib.createInflate([options]) ​

zlib.createInflateRaw([options]) ​

zlib.createUnzip([options]) ​

方便方法 ​

zlib.brotliCompress(buffer[, options], callback) ​

zlib.brotliCompressSync(buffer[, options]) ​

zlib.brotliDecompress(buffer[, options], callback) ​

zlib.brotliDecompressSync(buffer[, options]) ​

zlib.deflate(buffer[, options], callback) ​

zlib.deflateSync(buffer[, options]) ​

zlib.deflateRaw(buffer[, options], callback) ​

zlib.deflateRawSync(buffer[, options]) ​

zlib.gunzip(buffer[, options], callback) ​

zlib.gunzipSync(buffer[, options]) ​

zlib.gzip(buffer[, options], callback) ​

zlib.gzipSync(buffer[, options]) ​

zlib.inflate(buffer[, options], callback) ​

zlib.inflateSync(buffer[, options]) ​

zlib.inflateRaw(buffer[, options], callback) ​

zlib.inflateRawSync(buffer[, options]) ​

zlib.unzip(buffer[, options], callback) ​

zlib.unzipSync(buffer[, options]) ​

Zlib

线程池使用和性能注意事项

压缩 HTTP 请求和响应

内存使用调整

基于 zlib 的流

基于 Brotli 的流

刷新

常量

zlib 常量

Brotli 常量

刷新操作

压缩器选项

解压缩选项

类: `Options`

类: `BrotliOptions`

类: `zlib.BrotliCompress`

类: `zlib.BrotliDecompress`

类: `zlib.Deflate`

类: `zlib.DeflateRaw`

类: `zlib.Gunzip`

类: `zlib.Gzip`

类: `zlib.Inflate`

类: `zlib.InflateRaw`

类: `zlib.Unzip`

类: `zlib.ZlibBase`

`zlib.bytesWritten`

`zlib.crc32(data[, value])`

`zlib.close([callback])`

`zlib.flush([kind, ]callback)`

`zlib.params(level, strategy, callback)`

`zlib.reset()`

`zlib.constants`

`zlib.createBrotliCompress([options])`

`zlib.createBrotliDecompress([options])`

`zlib.createDeflate([options])`

`zlib.createDeflateRaw([options])`

`zlib.createGunzip([options])`

`zlib.createGzip([options])`

`zlib.createInflate([options])`

`zlib.createInflateRaw([options])`

`zlib.createUnzip([options])`

方便方法

`zlib.brotliCompress(buffer[, options], callback)`

`zlib.brotliCompressSync(buffer[, options])`

`zlib.brotliDecompress(buffer[, options], callback)`

`zlib.brotliDecompressSync(buffer[, options])`

`zlib.deflate(buffer[, options], callback)`

`zlib.deflateSync(buffer[, options])`

`zlib.deflateRaw(buffer[, options], callback)`

`zlib.deflateRawSync(buffer[, options])`

`zlib.gunzip(buffer[, options], callback)`

`zlib.gunzipSync(buffer[, options])`

`zlib.gzip(buffer[, options], callback)`

`zlib.gzipSync(buffer[, options])`

`zlib.inflate(buffer[, options], callback)`

`zlib.inflateSync(buffer[, options])`

`zlib.inflateRaw(buffer[, options], callback)`

`zlib.inflateRawSync(buffer[, options])`

`zlib.unzip(buffer[, options], callback)`

`zlib.unzipSync(buffer[, options])`