#CompressionStreamsAPI实战:用浏览器原生gzip/deflate压缩数据流(CompressionStream与DecompressionStream)上周三晚上十点多,我被测试小姐姐一条消息炸醒了…
Compression Streams API 实战:用浏览器原生 gzip/deflate 压缩数据流(CompressionStream 与 DecompressionStream)
Compression Streams API 实战:用浏览器原生 gzip/deflate 压缩数据流(CompressionStream 与 DecompressionStream)
上周三晚上十点多,我被测试小姐姐一条消息炸醒了。
"埋点上报又超时了,弱网下 3MB 的 JSON 直接把接口顶爆,你快看看。"
我爬起来一看,差点骂出声。事情是这样的:我们那个数据采集 SDK 攒了一批用户行为日志,一股脑 JSON.stringify 之后 POST 出去,压缩这事后端压根不管——也难怪,人家的 nginx 只对响应 gzip,请求体它是不会给你压的。上行带宽就那么点,一个 3MB 的包在 3G 模拟环境里能转圈转到天荒地老。
我第一反应跟大多数人一样:npm i pako,几行pako.gzip() 搞定。包是打上了,可构建完我瞄了一眼产物——好家伙,就为了压个字符串,bundle 凭空胖了 40 多 KB。这还没完,pako 是纯 JS 实现的,几十兆数据压起来主线程直接卡成幻灯片。
后来我才想起来,浏览器自己就带压缩能力,叫 Compression Streams API。折腾一晚上,最后三行代码把 pako 请了出去。这篇文章就把我踩的坑和最终写法完整捋一遍。
可能有人要问,压缩这事儿不是服务器该干的吗?这话对一半。服务器确实会对响应做 gzip,你打开任何一个网站,浏览器拿到的 HTML、JS 基本都是压过的。但方向反过来——浏览器往服务器上传的数据,默认情况下是没人替你压的。nginx 的 gzip 模块只管出不管进,express 的 compression 中间件同理。所以上行链路这一大块,压不压全看前端自己争不争气。埋点、日志、离线编辑器的文档保存、大表单提交,这些全是"上传远大于下载"的场景,压缩的收益全在这儿。想明白这层,你就知道这个 API 不是鸡肋,是补上了一块长期没人管的空白。
一、先搞清楚它到底是个啥
我一开始的认知是错的。我以为CompressionStream是个类似pako.gzip()的工具函数,传进去数据吐出来字节。于是很自然地写了new CompressionStream('gzip').compress(data)这么一句——然而compress方法根本不存在。
运行直接报错。后来翻 MDN 才明白——它是个 TransformStream,不是工具函数。你可以把它理解成管道中间的一台机器:左边塞原始字节流进去,右边出来的是压缩后的字节流。它自己不存数据,也不提供compress()这种一步到位的方法,必须挂在ReadableStream.pipeThrough()上用。
这个认知转变很关键。一旦你想通"它是管道中的一环",后面所有用法就都顺了:上游可以是fetch() 的 body、可以是 file.stream()、也可以是自己 new 出来的流;下游可以继续 pipeThrough再接一个加密流,也可以pipeTo 一个上传的可写流。整个链路是流式的,数据一小块一小块地过,不需要把 3MB 全塞进内存。
它有两个兄弟接口:CompressionStream负责压缩,DecompressionStream负责解压,用法完全对称。支持三种格式:gzip、deflate、deflate-raw。
有个细节必须先说,免得你重蹈我的覆辙:它不支持 brotli。网上不少文章把 brotli 也列进去,纯属以讹传讹。你要是头铁写 new CompressionStream('brotli'),浏览器会甩你一句TypeError: Failed to construct 'CompressionStream': The provided value 'brotli' is not a valid enum value of type CompressionFormat.我当年就在这句话上卡了二十分钟,还以为是浏览器版本问题。
二、先跑通一个最小的闭环
光说不练没用,先上个能直接跑的例子。核心套路就三步:把数据变成流 → 过一遍压缩器 → 用 Response把结果收集起来。
js// 压缩:把字符串 -> gzip 字节数组async function gzipCompress(str) { // 1. Blob 把字符串包成二进制,.stream() 拿到 ReadableStream const source = new Blob([str]).stream(); // 2. 管道中间挂上压缩器,得到压缩后的流 const compressed = source.pipeThrough(new CompressionStream('gzip')); // 3. Response 是收集流的利器,arrayBuffer() 把结果收成二进制 return new Uint8Array(await new Response(compressed).arrayBuffer());}// 解压:把 gzip 字节数组还原成字符串async function gzipDecompress(bytes) { // 从 Uint8Array 造一个只读流塞给解压器 const source = new Blob([bytes]).stream(); const decompressed = source.pipeThrough(new DecompressionStream('gzip')); // text() 直接按 UTF-8 解成字符串,省掉手动 TextDecoder return await new Response(decompressed).text();}// 实测:一段重复文本,压缩率能到 90% 以上const raw = '用户行为埋点数据'.repeat(1000);const bytes = await gzipCompress(raw);const back = await gzipDecompress(bytes);console.log(raw.length, bytes.length, back === raw); // 原文长、压缩后短、内容一致

这段代码我跑了不下二十遍。有几个点值得单独拎出来说。
第一,new Response(stream).arrayBuffer() 这个写法我第一次见的时候觉得挺邪门——Response 不是 fetch 才用的吗?其实 Response 的构造函数第一个参数就接受一个 ReadableStream,它就是个"流收割机",.blob()、.text()、.json()、.arrayBuffer()随便挑一个就能把流里的所有块收集完。这是原生流里最省事的收集姿势,比自己getReader()循环读再拼数组优雅太多。
第二,解压我用Blob([bytes]).stream() 而不是自己 new 一个 ReadableStream。因为Uint8Array 本来就能直接塞进 Blob,Blob 又自带 .stream(),一行搞定。你会发现整个压缩解压的往返也就四五行代码,比 pako 的引入、配置、调用链条短多了。
第三,中文别担心。Blob([str]) 默认按 UTF-8 编码,Response.text() 也按 UTF-8 解码,一来一回是对得上的。我专门拿中文埋点数据测过,back === raw 稳稳的 true。要是你手动 TextEncoder/TextDecoder,记得两边编码一致就行。说到编码,我顺手补个踩过的雷:有一回我从后端拿到压缩数据,是 base64 字符串,我脑子一抽直接 new Blob([base64Str]) 塞进解压器,结果全是乱码。base64 只是字节的文本表示,不是字节本身,必须先用 atob还原成二进制再喂给DecompressionStream。这个道理现在说起来简单,当时对着一堆乱码盯了半小时。
还有一点我后来才体会到好处:这套 API 是流式的,数据不会因为压缩被整体读进内存。我拿一个 50MB 的日志文件做过对比,用老办法 pako.gzip()一次性压,内存峰值直接飙上去,页面卡了小两秒;换成file.stream().pipeThrough(...)之后,内存曲线平得像条直线。这就是流的意义——它一块一块处理,处理完就扔,不攒着。你要是做在线文档、日志采集这种动辄几十兆的场景,这个差别根本不是"优化",是"能不能用"。
三、gzip、deflate、deflate-raw 到底选哪个
这三个格式名字长得像,我一开始也是糊的。查了一圈资料,简单说清楚:
gzip 是基于 DEFLATE 算法的一种封装格式,前面有 gzip 文件头(魔法数 1f 8b),后面跟 CRC32 校验和长度信息。它是 HTTP 世界里的事实标准,语义最明确,跟服务端对接基本不会出岔子。我实际项目里默认就用它,别纠结。
deflate 这个名字有点坑——在 Compression Streams 里它指的是 zlib 格式,也就是 DEFLATE 数据外面套了两字节的 zlib 头,末尾带 Adler-32 校验。
deflate-raw 则是纯 DEFLATE 数据流,不加任何头和校验。只有当你对接的系统明确要求裸 DEFLATE 时才用。
这里我要拍桌子吐槽一句:这三个格式的选择, Technological 上差别其实没那么大,真正出事的全在"前后端没对上"上。我有次图省事前端用了 deflate-raw,后端哥们用 Node 的 zlib.gunzipSync解,直接炸出一堆乱码,排查到凌晨两点才发现是格式没对齐。所以我的建议很粗暴:除非后端白纸黑字告诉你要别的,一律 gzip。
下面这段是我现在项目里封装的格式检测和降级逻辑,也算把这三种格式的用法收了个口:
js// 支持的三种压缩格式,注意没有 brotliconst SUPPORTED = ['gzip', 'deflate', 'deflate-raw'];// 特性检测:不是所有浏览器/环境都支持 CompressionStreamfunction supportsCompression() { return typeof CompressionStream !== 'undefined' && typeof DecompressionStream !== 'undefined';}// 按格式压缩,参数不合法时直接给出清晰报错async function compressByFormat(str, format = 'gzip') { // 先校验格式名,避免浏览器抛那句看不懂的 enum 报错 if (!SUPPORTED.includes(format)) { throw new Error(`不支持的压缩格式: ${format},只接受 ${SUPPORTED.join('/')}`); } if (!supportsCompression()) { throw new Error('当前环境不支持 Compression Streams API,请走降级方案'); } const stream = new Blob([str]).stream() .pipeThrough(new CompressionStream(format)); return new Uint8Array(await new Response(stream).arrayBuffer());}
兼容性这块我特意查了 Can I Use:Chrome/Edge 80 起、Firefox 113 起、Safari 16.4 起支持,2023 年 5 月之后已经算"Baseline 广泛可用"了。这里得吐槽一下那些过时教程,动不动就说"只有 Chromium 和 Firefox 支持,Safari 完全不行"——那是 2022 年的老黄历了,Safari 早就跟上了。你要是照着这种文章做了降级方案,等于白写一堆代码。所以技术这东西,兼容性一定以 Can I Use 或者 MDN 的实时数据为准,别信博客里的陈年结论,包括我这篇(笑)。
而且它在 Web Worker 和 Service Worker 里都能用,这点后面会派上大用场。唯一要命的前提是必须在安全上下文(HTTPS 或 localhost)里跑,你要是在某个 http 的测试机上调试,CompressionStream这个全局变量压根不存在,你会看到ReferenceError: CompressionStream is not defined,然后满世界找 bug——别问我怎么知道的,说多了都是泪。生产环境基本都是 HTTPS,所以正常上线不用担心,但本地联调如果起了个 http 服务,记得配 localhost 或者本地证书,不然能把你排查到怀疑人生。
另外补充一句关于格式选择的实测数据。我拿同一份 3MB 的埋点 JSON 分别用三种格式压了一遍:gzip 压出来 302KB,deflate 压出来 298KB,deflate-raw 是 297KB。看到了吧,三者压缩率几乎没差别,抠那几 KB 毫无意义。这也再次印证我的观点——选格式别从"哪个压得更小"入手,要从"哪个跟后端最容易对上"入手。为了省几字节把链路搞复杂,是典型的捡芝麻丢西瓜。
四、我踩过的几个坑,一个都别跳过
这部分是我用真金白银的加班时间换来的,建议你逐条对照。
坑一:同一个流不能 pipeThrough 两次。 流一旦被管道接管就被"锁定"了。我早期想对同一个源流既压缩又算 MD5,写了两次 pipeThrough,第二次直接TypeError: ReadableStream is locked。解法是先用tee()把流劈成两股,或者干脆从源头重新造流。
坑二:手动写流时忘记 close。如果你不走Blob.stream(),而是自己 new 一个 ReadableStream用controller.enqueue()喂数据,喂完必须controller.close()。我有次漏了这句,压缩结果永远差最后一块,解压出来缺个尾巴,查了半天怀疑人生。同理,如果你拿到writable.getWriter()手动写,写完也得writer.close(),否则压缩器的缓冲区不会把最后一段冲出来。
坑三:小数据别压。 压缩本身有开销,gzip 头尾就十几个字节。几 KB 的 JSON 压完可能反而更大,纯属帮倒忙。我的经验是设个阈值,小于 100KB 的直接发原包。埋点数据这种动辄几兆的,压缩收益才明显(我这边实测 3MB 的 JSON 能压到 300KB 左右,压缩率九成)。
坑四:Content-Encoding 头要跟后端约死。 你把请求体压成 gzip 发过去,得告诉后端"这是 gzip",通常在 header 里带 Content-Encoding: gzip。但这里有个天坑:如果中间层(比如 nginx 或 express 的 compression 中间件)又给你压一遍,就变成二次压缩,后端解一层还是乱码。这个坑跟之前写 PHP readonly 类与只读属性实战:用不可变对象根治"对象被偷偷改了"的玄学 Bug时后端同事踩的"对象被偷偷改"是一个味道——链路长了一旦没人把约定写死,就有人悄悄动你的数据。所以务必在整个链路上把"压缩算法"当成协议的一部分固化下来。
坑五:服务端返回的 gzip 别手动解压。 fetch 拿到 Content-Encoding: gzip的响应时,现代浏览器已经自动帮你解压了,response.body出来就是明文。我犯过傻,又pipeThrough(new DecompressionStream('gzip')) 一次,结果报" Incorrect header check"。记住:请求体压缩要你自己做,响应体解压浏览器基本替你做了,除非你在搞什么特殊定制。
五、三个真实场景的落地写法
坑讲完,上点能直接抄进项目的东西。
场景一:axios 上传大 JSON 自动压缩
埋点上报就是我最初的那个需求。思路是在请求拦截器里判断 body 大小,超阈值就压缩并打上头:
jsimport axios from 'axios';// 请求拦截器:大体积 JSON 自动 gzip 压缩后再发axios.interceptors.request.use(async (config) => { const data = config.data; // 只处理普通对象/大字符串,FormData、Blob 不碰 if (!data || config.headers['Content-Encoding']) return config; const json = typeof data === 'string' ? data : JSON.stringify(data); // 超过 100KB 才压,小数据压了反而变大 if (new Blob([json]).size < 100 * 1024) return config; const compressed = new Blob([json]).stream() .pipeThrough(new CompressionStream('gzip')); config.data = await new Response(compressed).blob(); // 告诉后端这是 gzip,让它先解压再解析 config.headers['Content-Encoding'] = 'gzip'; // 二进制了,Content-Type 别再写 application/json config.headers['Content-Type'] = 'application/octet-stream'; return config;});
这里Content-Type我改成application/octet-stream是有讲究的。压完已经是二进制字节流了,你再挂着application/json是自欺欺人——真要装成文本,反而会让某些中间代理试图解析它然后炸掉。二进制就老老实实写二进制。
这个拦截器上线前我还专门跟后端对了一遍协议。有几个细节分享给你,省得你重走弯路。第一,拦截器里一定要判断Content-Encoding是否已经存在,不然遇到本来就被上游压过的数据,你会二次压缩,这是灾难。第二,FormData 和文件绝对不能进压缩逻辑,图片视频本来就是压缩格式,再压一遍纯属浪费 CPU 还可能损坏数据,所以我在开头就把它俩排除掉了。第三,也是最容易翻车的——后端得知道你要发压缩数据。我们最后是约定了一个自定义头 X-Payload-Encoded: gzip,后端中间件看到这个头才走解压分支,否则按普通 JSON 处理。这样新老版本能平滑共存:老前端不带头,后端照旧解析;新前端带了头,后端才解压。你要是没做这种兼容,一上线新老客户端混着跑,后端直接懵。
还有个反直觉的点:config.data 换成 Blob 之后,axios 的某些版本不会再自动给它加 application/json 头了。所以你得手动把该带的头都带齐,别指望框架替你兜底。我第一次上线就栽在这,本地测得好好的,一到预发环境后端说"收到的不是 JSON",查了半天是请求头没了。这种坑光看文档看不出来,只能靠踩。
场景二:Web Worker 里压缩,别卡主线程
流式压缩不等于零开销。几十兆数据压起来 CPU 照样飙升,放主线程会掉帧。我的做法是把整个压缩流程丢进 Worker——Compression Streams 在 Worker 里完全可用:
js// ===== 主线程 =====const worker = new Worker('./compress.worker.js');async function compressInWorker(str) { return new Promise((resolve) => { worker.onmessage = (e) => resolve(e.data.compressed); // 第二个参数是 transferable,把 buffer 所有权直接转给 worker,零拷贝 const buf = new TextEncoder().encode(str).buffer; worker.postMessage({ buffer: buf }, [buf]); });}// ===== compress.worker.js =====self.onmessage = async ({ data }) => { // 从 transfer 过来的 ArrayBuffer 造流,过压缩器 const stream = new Blob([data.buffer]).stream() .pipeThrough(new CompressionStream('gzip')); const out = new Uint8Array(await new Response(stream).arrayBuffer()); // 结果同样用 transferable 传回主线程 self.postMessage({ compressed: out }, [out.buffer]);};
这里postMessage 的第二个参数(transferable)是关键。不写的话 ArrayBuffer 会被结构化克隆复制一份,几十兆数据拷来拷去反而更慢;写上之后所有权直接转移,零拷贝。我加了这个之后,主线程在压缩期间帧率稳如老狗。
顺带一提,这种"把重活扔给另一个上下文、用消息传递结果"的思路,跟WebTransport API 实战:基于 HTTP/3 的低延迟双向通信(datagram 数据报与 stream 流) 里聊的 stream 流式传输是一个内核——都是让数据流起来、别堵在一处。WebTransport 的 stream 天生就是为这种低延迟双向流设计的,压缩流挂在它前面正好配套。
场景三:Service Worker 拦截响应做压缩
如果你是做离屏缓存或者静态资源优化的,可以在 Service Worker 里拦截请求,把响应压完再返回:
jsself.addEventListener('fetch', (event) => { event.respondWith((async () => { const response = await fetch(event.request); // 只对文本类资源动手,图片视频本来就压过了 const type = response.headers.get('Content-Type') || ''; if (!type.includes('text/') && !type.includes('javascript')) { return response; } // 包一层新 Response:原始 body 过压缩流 const compressedBody = response.body.pipeThrough( new CompressionStream('gzip') ); return new Response(compressedBody, { status: response.status, headers: { 'Content-Type': type, 'Content-Encoding': 'gzip', // 浏览器拿到后会自动解开 }, }); })());});
这个场景要特别小心别和用户浏览器自带的 gzip 重复压缩——很多 CDN 和源站已经压过一遍了。我这段的适用面其实窄,真正用它的是一些自建的离线缓存方案,普通业务直接用场景一就够了,别为了炫技上 Service Worker。
六、降级方案:老浏览器怎么办
前面说了,Safari 16.4 以下、以及一些老版本安卓 WebView 是不支持这套 API 的。你要是做 to C 的产品,用户机型杂,必须准备后路。
我的策略是特性检测 + 动态加载:现代浏览器走原生,检测到不支持再异步加载 pako 或 fflate。这样既吃到了原生 API 零体积、高性能的红利,又不丢老用户。
js// 按需降级:优先原生,不支持时再动态引入 pakoasync function compressWithFallback(str) { if (typeof CompressionStream !== 'undefined') { const stream = new Blob([str]).stream() .pipeThrough(new CompressionStream('gzip')); return new Uint8Array(await new Response(stream).arrayBuffer()); } // 只有老浏览器才会走到这里,动态 import 不影响主包体积 const pako = await import('pako'); return pako.gzip(new TextEncoder().encode(str));}
注意这里用的是动态import(),打包工具会把它拆成单独的 chunk,只有真正需要的时候才下载。现代浏览器用户压根不会请求这个 chunk,等于白嫖了兼容性。fflate 也是个好选择,比 pako 更小更快,如果你的降级包想更轻可以考虑它。
不过我得说句实在话:降级方案别过度设计。我见过有团队为了兼容那不到 5% 的老浏览器,把整套压缩链路做了三四个分支——原生的、pako 的、fflate 的、甚至还有降到最后干脆不压的,代码复杂得没人敢动,反而成了 bug 温床。我的建议是就留一条原生主路加一条 pako 兜底,够了。真要追求极致,先去看看你的用户画像,Safari 老版本占比到底有多少。如果连 1% 都不到,甚至可以直接放弃——当然这话得你们产品说了算,我不能替你拍这个板。
顺便提一个容易忽略的点:降级到 pako 之后,输出字节和原生 API 是一致的 gzip 格式。也就是说不管走哪条分支,后端看到的都是标准 gzip,解压逻辑只有一套。这一点是这套方案能成立的前提——如果两条分支产出格式不一样,后端就得写两套解析,那复杂度就指数级上升了。所以你看,选 gzip 作为统一格式,从降级设计这个角度又多了一条理由。
七、前端性能这块,到底提升了什么
聊到这儿,我想把"前端性能"这笔账算清楚,免得你以为加个压缩就万事大吉。
Compression Streams 带来的收益是实打实的,但分场景:
网络传输:这是最大的头。弱网、移动网络下,3MB 压到 300KB,上传耗时直接降一个数量级。埋点、日志、大表单这类场景收益最猛。
包体积:用原生 API 意味着你能把 pako 那几十 KB 从 bundle 里踢出去。这对首屏加载是有正面意义的——虽然几十 KB 看着不多,但积少成多。这两年浏览器原生能力疯狂补齐,从 HTML Popover API 实战:不写一行 JS 也能做原生弹窗(popover 属性与 Top Layer 层叠上下文) 那种不写 JS 的原生弹窗,到 CSS Subgrid 实战:用网格继承让嵌套布局严丝合缝对齐(subgrid 与 grid-template-rows/columns)这种原生布局继承,再到今天的原生压缩,趋势非常明显:能交给浏览器干的活,就别自己打包库去干。
内存:流式的意义在于数据不落地。3MB 数据如果用 pako.gzip()一次性处理,内存里同时存在原文、字节数组、压缩结果三份;走流式管道则是一块一块地过,内存占用基本恒定。处理上百兆的文件时这个差别是生死性的。
但也要泼盆冷水:压缩不是银弹。如果你的瓶颈根本不在网络,而是 JS 执行、渲染卡顿,那折腾压缩纯属南辕北辙。我踩过的另一个坑就是——有次兴冲冲给一个本来就只有 20KB 的配置接口加了压缩,结果压缩解压的 CPU 开销比省下的那点流量还亏,回滚了事。
所以我的判断标准就一条:先测量,再动手。用 Performance 面板或者 Network 面板看看数据到底大不大、时间花在哪。大 JSON、弱网、频繁上报——满足这三条中的两条,压缩就值得上。否则老老实实优化数据结构,精简字段、用数字代替冗长的字符串枚举,收益往往比通用压缩更高。
说到底,Compression Streams API 不是一个让你炫技的玩具,它是浏览器把 zlib 能力免费开放给你的一把趁手工具。用对了场景,三行代码就能解决大麻烦;用错了场景,它就是你代码里多出来的一层无用抽象。搞明白它"是管道不是函数"这个本质,剩下的都是水到渠成的事。
那天晚上把 pako 删掉、换上原生实现之后,构建产物小了一圈,弱网上报超时的问题也消失了。测试小姐姐第二天在群里发了个"稳",我看着那三个字,感觉这一晚上的折腾值了——除了那杯凉透的咖啡。
标签:CompressionStream, DecompressionStream, gzip, 数据流压缩, 前端性能描述:通过真实踩坑经历讲解浏览器原生 Compression Streams API 的用法,涵盖 CompressionStream 与 DecompressionStream 的管道式压缩解压、gzip/deflate/deflate-raw 格式选择、axios 上传压缩、Web Worker 与 Service Worker 实战、常见坑与 pako 降级方案,帮助前端在弱网大 JSON 场景下提升传输与前端性能。

发表评论发布评论后审核成功,即可显示在列表中...