zstd.h缺失需安装对应开发包：ubuntu/debian用libzstd-dev，centos/rhel用zstd-devel，macos用brew install zstd；流式解压应使用zstd_decompressstream而非zstd_decompress，并注意输入缓冲区管理和zstd_isendofframe判断。
zstd.h 头文件找不到？先确认 libzstd 开发包已安装
直接 #include <zstd.h></zstd.h> 报错，大概率是系统没装开发头文件。Ubuntu/Debian 用 sudo apt install libzstd-dev；CentOS/RHEL 用 sudo yum install zstd-devel（或 dnf）。macOS 用 brew install zstd 即可。仅安装运行时库（如 libzstd1）不够，编译期必须有 zstd.h 和对应的静态/动态链接支持。
用 ZSTD_decompressStream 读取流式解压更稳妥
别用 ZSTD_decompress 一次性加载整个压缩文件——它要求提前知道原始大小，且内存不友好。真实场景中文件往往很大，或来源是 socket、pipe 等不可回溯流。正确做法是分块读取压缩数据，用 ZSTD_decompressStream 增量解压：
ZSTD_DStream* dstream = ZSTD_createDStream();
ZSTD_initDStream(dstream);
ZSTD_inBuffer in = { src_buf, src_size, 0 };
ZSTD_outBuffer out = { dst_buf, dst_capacity, 0 };
<p>while (in.pos 0) {
// 处理已解出的 out.pos 字节
out.pos = 0; // 重置输出位置，下次继续填
}
}
ZSTD_freeDStream(dstream);</p>
关键点：ZSTD_isEndOfFrame 判断帧是否结束，而非依赖 in.pos == in.size；out.pos 每次返回实际写入字节数，必须手动归零再复用缓冲区；输入缓冲区的 in.pos 由 API 自动推进。
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
ifstream + istreambuf_iterator 无法直接读 zstd 流
别试图把 std::ifstream 包装成 std::istream 后传给某个“自动解压”函数——C++ 标准库完全不识别 zstd 格式。常见误区是查到 boost::iostreams::zstd_decompressor，但它依赖 Boost.Iostreams + Boost.ZLib 风格封装，且需手动注册 filter，不是开箱即用。若坚持用流接口，得自己继承 std::streambuf 实现底层 read logic，再绑定到 std::istream；但多数项目没必要绕这么大弯，直接用 read() + ZSTD_decompressStream 更直白可靠。
注意 ZSTD_getFrameContentSize 的返回值含义
想预估解压后大小？调 ZSTD_getFrameContentSize(src_buf, src_size)。但它返回三种可能：ZSTD_CONTENTSIZE_UNKNOWN（-1）、ZSTD_CONTENTSIZE_ERROR（负值且非 -1）、或具体字节数。很多 zstd 文件（尤其用 --single-thread 或 streaming mode 生成的）根本没存原始尺寸，此时返回 ZSTD_CONTENTSIZE_UNKNOWN 是正常行为，不代表文件损坏。别因此拒绝解压——ZSTD_decompressStream 本身不依赖这个值。
最易被忽略的是输入缓冲区管理：zstd 解压器内部会暂存未完成帧的头部或尾部数据，所以哪怕 in.pos == in.size，只要 ZSTD_isEndOfFrame 返回 false，就得继续喂空输入（in.src = nullptr; in.size = 0;），直到它真正结束。漏掉这步，小概率丢最后几字节。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
