一个 2 MB 的 .zst 文件,解压出来只有十几 KB
起因
处理一批压缩过的会话归档,文件 2,196,441 字节。按常识解压:
js
import fs from 'node:fs';
import zlib from 'node:zlib';
const raw = zlib.zstdDecompressSync(fs.readFileSync('session.zst'));
console.log(raw.length); // 一万多
2 MB 的文件,解出来只有十几 KB。
不报错、不警告、buffer 也不空。第一反应是文件损坏了,于是拿 zstd -t 去校验------校验通过,无损。
那 2 MB 去哪了?
原因:zstd 允许把多个独立帧拼成一个文件
Zstandard 的格式规范(RFC 8878)里,「帧」是最小的独立压缩单元。一个帧自带 magic、帧头、数据块、校验,单独就能解压。
而规范同时允许:一个文件里连续放多帧 。这不算非法格式,zstd -t 会逐帧校验,全部通过。
这种用法在真实场景里很常见:
- 日志归档:每条日志独立压一帧再追加,写入时不用维护跨条目的字典
- 事件流落盘:每批事件一帧,避免单帧无界增长
- 训练数据集:样本各自成帧,方便随机读取某一帧而不解压整个文件
代价是:one-shot 解压 API 通常只处理第一帧就返回。
zstdDecompressSync 就是 one-shot 的。它拿到输入、解出第一帧、认为任务完成,剩下的字节被静默丢弃。
30 KB 是第一条会话的大小,2 MB 是几十条会话叠在一起。
我先试了流式,没用
第一反应是换流式 API ------ 流式解码器理论上应该能一帧接一帧推进吧?
js
import { Readable } from 'node:stream';
import zlib from 'node:zlib';
function decompressAll(buf) {
return new Promise((resolve, reject) => {
const chunks = [];
const dec = zlib.createZstdDecompress();
dec.on('data', (c) => chunks.push(c));
dec.on('end', () => resolve(Buffer.concat(chunks)));
dec.on('error', reject);
Readable.from([buf]).pipe(dec);
});
}
结果和 one-shot 一模一样,还是只有第一帧。
我不信,换成显式 write + end:
js
const dec = zlib.createZstdDecompress();
dec.on('data', (c) => chunks.push(c));
dec.write(buf);
dec.end();
还是第一帧。
拿三个各 20,000 字节的帧拼成一个 57 字节的文件实测(Node 24.21.0):
| 方式 | 解出字节 | 实际帧数 |
|---|---|---|
zstdDecompressSync |
20,000 | 1 |
createZstdDecompress + pipe |
20,000 | 1 |
createZstdDecompress + write/end |
20,000 | 1 |
| 手工切帧后逐帧解 | 60,000 | 3 |
Node 的 zlib zstd 实现,不管 one-shot 还是流式,遇到第一帧结束就收工。
这个结论有点反直觉 ------ 理论上流式解码器应该能识别连续帧。但至少在当前 Node 版本里它不认。所以只能自己切。
正解:按 magic 切帧
但我的场景需要逐条处理------每条会话要单独做时间戳对齐,整块解出来还得再切分。那就得自己找帧边界。
每帧开头是固定的 4 字节 magic:
0x28 0xB5 0x2F 0xFD
按小端读是 0xFD2FB528。
js
const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
function splitFrames(buf) {
const offsets = [];
for (let i = 0; i <= buf.length - 4; i++) {
if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) {
offsets.push(i);
}
}
return offsets.map((off, k) => ({
offset: off,
bytes: buf.subarray(off, offsets[k + 1] ?? buf.length),
}));
}
const frames = splitFrames(fs.readFileSync('session.zst'));
for (const f of frames) {
const text = zlib.zstdDecompressSync(f.bytes).toString('utf8');
// 逐条处理
}
这里有个必须处理的隐患:magic 也可能出现在压缩数据内部。
虽然被误命中的概率不高(4 字节随机碰撞约 1/2^32),但一旦命中,你会切出一个「垃圾帧」,然后 zstdDecompressSync 抛错,整个循环中断。
我加了容错:
js
for (const f of frames) {
let text;
try {
text = zlib.zstdDecompressSync(f.bytes).toString('utf8');
} catch {
continue; // 假边界,跳过
}
if (!text.includes('"')) continue; // 再按内容特征过滤一层
// 处理
}
「解析失败就跳过」比「精确算出每帧长度」便宜得多。 真要精确长度,得完整解析 Frame_Header(含 Frame_Content_Size、Window_Descriptor、可选的字典 ID),比按 magic 切复杂一个数量级,而这种场景下没必要。
两个容易想错的地方
第一,zstd -t 通过不代表单帧。
它是逐帧校验的。一个多帧文件校验全绿,你用 one-shot API 却只能拿到一帧------两者不矛盾,是同一件事的两个视角。
我当时就是因为「校验通过」而排除了格式问题,多绕了一小时。
第二,「换流式就好了」这个直觉,在 Node 上不成立。
我原本认为:one-shot 只解一帧,是因为它假设输入是单个压缩单元;换成流式、逐块喂进去,解码器总能识别帧边界吧?
实测否掉了,见上面那张表。
所以真正的判据不是「用哪种 API」,而是**「你相不相信这个文件只有一帧」。这个假设在单文件压缩场景下成立(gzip/xz 那条线基本都是单流),但在追加写入**的场景下几乎必然失效 ------ 而 API 不会告诉你它失效了,它只是安静地少给你一部分数据。
判断自己会不会踩
三个信号,中一个就要警惕:
- 文件是追加写入产生的(日志、事件、批量归档)
- 写入方是每次独立的压缩调用,而不是维持一个压缩流
- 解压后的大小与文件大小比例异常(压缩比超过 20:1 基本不可能,除非内容是重复文本)
第 3 条最实用。正常文本压缩比 3:1 到 8:1,2 MB 解出 30 KB 是 70:1------这个数字本身就在报警。
小结
| 需求 | 用什么 |
|---|---|
| 拿到全部内容 | 按 magic 切帧后逐帧解(one-shot 和流式都只给第一帧) |
| 逐帧单独处理 | 同上,顺手就拿到了 |
| 判断是否多帧 | 看解压后大小与文件大小的比例 |
一个 4 字节 magic,加上一次没被验证的假设,够查半天。