一个 2 MB 的 .zst 文件,解压出来只有十几 KB

8 阅读1分钟

一个 2 MB 的 .zst 文件,解压出来只有十几 KB

起因

处理一批压缩过的会话归档,文件 2,196,441 字节。按常识解压:

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 —— 流式解码器理论上应该能一帧接一帧推进吧?

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:

const dec = zlib.createZstdDecompress();
dec.on('data', (c) => chunks.push(c));
dec.write(buf);
dec.end();

还是第一帧。

拿三个各 20,000 字节的帧拼成一个 57 字节的文件实测(Node 24.21.0):

方式解出字节实际帧数
zstdDecompressSync20,0001
createZstdDecompress + pipe20,0001
createZstdDecompress + write/end20,0001
手工切帧后逐帧解60,0003

Node 的 zlib zstd 实现,不管 one-shot 还是流式,遇到第一帧结束就收工。

这个结论有点反直觉 —— 理论上流式解码器应该能识别连续帧。但至少在当前 Node 版本里它不认。所以只能自己切。

正解:按 magic 切帧

但我的场景需要逐条处理——每条会话要单独做时间戳对齐,整块解出来还得再切分。那就得自己找帧边界。

每帧开头是固定的 4 字节 magic:

0x28 0xB5 0x2F 0xFD

按小端读是 0xFD2FB528。

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 抛错,整个循环中断。

我加了容错:

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 不会告诉你它失效了,它只是安静地少给你一部分数据。

判断自己会不会踩

三个信号,中一个就要警惕:

  1. 文件是追加写入产生的(日志、事件、批量归档)
  2. 写入方是每次独立的压缩调用,而不是维持一个压缩流
  3. 解压后的大小与文件大小比例异常(压缩比超过 20:1 基本不可能,除非内容是重复文本)

第 3 条最实用。正常文本压缩比 3:1 到 8:1,2 MB 解出 30 KB 是 70:1——这个数字本身就在报警。

小结

需求用什么
拿到全部内容按 magic 切帧后逐帧解(one-shot 和流式都只给第一帧)
逐帧单独处理同上,顺手就拿到了
判断是否多帧看解压后大小与文件大小的比例

一个 4 字节 magic,加上一次没被验证的假设,够查半天。