在日常前端开发中,如果想在浏览器端高效压缩数据,CompressionStream 这一原生 API 确实是值得关注的利器,但其使用细节值得深究。它仅支持 "gzip" 和 "deflate" 两种压缩格式,并且必须通过 pipeThrough() 方法接入到 ReadableStream 的管道中才能发挥作用。如果你期望直接用它压缩字符串或调整压缩级别,很遗憾,它并不提供这些功能。此外,压缩完成后输出的数据 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")(注意大小写)都会导致构造失败。
目前该 API 只接受两个取值:
"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),或者退回到服务端进行压缩。这一点,往往是兼容性考量中最容易被忽略的盲区。
