CompressionStream压缩数据流使用指南

在浏览器中直接压缩数据，CompressionStream 原生 API 是一个高效的工具，但其使用存在特定规则。它仅支持 “gzip” 和 “deflate” 两种格式，且必须通过 pipeThrough() 方法接入 ReadableStream 管道。该 API 无法直接压缩字符串或调整压缩级别，同时，压缩后数据的 MIME 类型也需要手动指定。

简而言之，CompressionStream 是浏览器内置的流式压缩工具，无需引入第三方库。但其使用有环境限制，目前仅 Chrome 120+、Firefox 122+ 和 Safari 17.4+ 等较新版本支持。它专为处理流设计，因此无法直接用于 标签内的字符串或传统的 XMLHttpRequest 响应体，其适用场景仅限于 ReadableStream。

CompressionStream 构造函数参数必须是字符串

一个常见误区是构造函数的参数必须为字符串字面量。如果传入数字、对象或 undefined，会立即抛出 TypeError: Failed to construct 'CompressionStream': invalid format 错误。

例如，new CompressionStream("gzip") 是合法的，但 new CompressionStream(9) 或 new CompressionStream("GZIP")（注意大小写）都会导致构造失败。

目前仅支持两个有效值：

• "gzip"：标准 GZIP 格式，生成包含 10 字节头部和 8 字节尾部（内含 CRC32 校验码）的数据流。
• "deflate"：遵循 RFC 1951 的格式，无头部和尾部。需特别注意，它不是 "deflate-raw"，后者在此 API 中无效。

传错格式名称是开发中最易遇到的错误，尤其是误将 "deflate-raw" 当作合法选项。该值可能在 Node.js 的 zlib.createDeflateRaw() 或某些后端库中存在，但在 CompressionStream 中不可用。

必须配合 stream().pipeThrough() 使用

CompressionStream 本身不是一个可直接调用的工具函数，其角色是一个 TransformStream，需插入到 ReadableStream 的管道中。常见的错误是试图用它直接处理 ArrayBuffer 或 Blob。

例如，以下写法无效：const compressed = new CompressionStream("gzip").compress(rawData) —— 因为根本不存在 compress() 方法。

正确的使用链路如下：

const readStream = file.stream();
const compressStream = new CompressionStream("gzip");
const compressedStream = readStream.pipeThrough(compressStream);
const blob = await new Response(compressedStream).blob();

需注意，pipeThrough() 方法会返回一个新的 ReadableStream，原始流不会被消耗或关闭。但不可对同一原始流重复调用 pipeThrough()，否则会抛出 InvalidStateError 错误。

压缩后 Blob 的 type 不能自动推断

浏览器不会因使用了 "gzip" 格式而自动为生成的 Blob 设置 type: "application/gzip"。若使用 new Blob([blob]) 再次包装，其 type 属性默认为空字符串，可能导致下载时文件被错误识别为 text/plain 甚至出现乱码。

因此，务必显式设置 MIME 类型：

• 对于 gzip 输出：使用 new File([blob], filename + ".gz", {type: "application/gzip"})
• 对于 deflate 输出：无标准 MIME 类型，通常建议使用 application/x-deflate（虽非官方但较通用），或直接使用 application/octet-stream

忽略此步骤可能导致前端解压失败。例如，使用 DecompressionStream 解压时，可能抛出 DataError: Invalid compressed data，因为解压器需要依赖正确的格式标识进行初始校验。

不支持配置压缩级别或字典

CompressionStream 是浏览器封装好的“黑盒”，未暴露如 level、windowBits、memLevel 等精细化压缩参数。这意味着：

• 无法在客户端控制“压缩率”与“压缩速度”之间的权衡。
• 无法复现服务端使用 zlib.gzip(data, { level: 1 }) 生成的低开销 gzip 流。
• 无法与对压缩窗口大小有特定要求的设备通信（例如，某些 IoT 固件可能只接受 windowBits=12 的 deflate 流）。

如果项目有此类强约束，则需考虑其他方案，例如改用 WebAssembly 实现的库（如 fflate），或退回到服务端进行压缩。这一点往往是兼容性考量中容易被忽略的盲区。