拼接 .zst 文件¶

可以将多个 .zst 文件拼接在一起。zstd 会将这样拼接而成的文件当作单个 .zst 文件进行解压缩。

整数后缀与特殊值¶

在大多数需要整数参数的地方，都支持使用可选的后缀来方便地表示较大的整数。整数与后缀之间不能有空格。

KiB

将整数乘以 1,024（2^10）。Ki、K 和 KB 都可作为 KiB 的同义词。

MiB

将整数乘以 1,048,576（2^20）。Mi、M 和 MB 都可作为 MiB 的同义词。

操作模式¶

如果给出了多个操作模式选项，则以最后一个为准。

-z, --compress

压缩。当未指定操作模式选项，且命令名称也未隐含其他操作模式时（例如 unzstd 隐含 --decompress），这是默认的操作模式。

-d, --decompress, --uncompress

解压缩。

-t, --test

测试压缩 files 的完整性。此选项等效于 --decompress --stdout > /dev/null，解压缩后的数据会被丢弃，并进行校验和计算以检查错误。不会创建或删除任何文件。

-b#

使用压缩级别 # 对文件进行基准测试。有关此操作的说明，请参见下方的 BENCHMARK（基准测试）一节。

--train FILES

使用 FILES 作为训练集来创建字典。训练集应包含大量小文件（> 100 个）。有关此操作的说明，请参见下方的 DICTIONARY BUILDER（字典构建器）一节。

-l, --list

显示与 zstd 压缩文件相关的信息，例如大小、压缩率和校验和。其中某些字段可能不可用。此命令的输出可以通过 -v 修饰符加以扩充。

操作修饰符¶

• -#：选择 # 压缩级别 [1-19]（默认值：3）。更高的压缩级别 通常 会以速度和内存为代价换取更高的压缩率。一条粗略的经验法则是，压缩级别每提高 2 级，压缩速度预计会减半。从技术上讲，每个级别都会映射到一组高级参数（这些参数也可以单独修改，参见下文）。由于压缩器的行为在很大程度上取决于要压缩的内容，因此无法保证从一个级别到另一个级别是平滑过渡的。
• --ultra：解锁 20 以上（最高 22）的高压缩级别，这会使用多得多的内存。请注意，使用这些级别时，解压缩也将需要更多内存。
• --fast[=#]：切换到超快压缩级别。如果没有给出 =#，则默认为 1。数值越大，压缩速度越快，但会牺牲一定的压缩率。如果先前设置过压缩级别，此设置会将其覆盖。类似地，如果在 --fast 之后设置了压缩级别，则会覆盖此设置。
• -T#, --threads=#：使用 # 个工作线程进行压缩（默认值：根据物理 CPU 核心数在 1 到 4 之间；参见下方的 ZSTD_NBTHREADS）。如果 # 为 0，则尝试检测并使用物理 CPU 核心的数量。在所有情况下，线程数都会被限制在 ZSTDMT_NBWORKERS_MAX 以内，该值在 32 位模式下为 64，在 64 位环境下为 256。如果编译 zstd 时未启用多线程支持，则此修饰符不起作用。
• --single-thread：使用单个线程同时处理 I/O 和压缩。由于压缩与 I/O 是串行进行的，这可能会稍慢一些。单线程模式的内存占用显著更低，这对于内存有限的系统（例如 32 位系统）可能很有用。

注 1：当禁用多线程支持时，这是唯一可用的模式。

注 2：此模式不同于 -T1，后者会派生 1 个与 I/O 并行的压缩线程。最终的压缩结果也与 -T1 略有不同。

• --auto-threads={physical,logical} (default: physical)：当通过 -T0 使用默认线程数时，根据检测到的物理或逻辑核心数量来选择默认值。
• --adapt[=min=#,max=#]：zstd 会根据感知到的 I/O 状况动态调整压缩级别。可以使用 -v 命令实时观察压缩级别的自适应过程。自适应可以被约束在所提供的 min 和 max 级别之间。该特性在与多线程以及 --long 模式结合使用时有效。它不适用于 --single-thread。它默认将窗口大小设置为 8 MiB（可手动更改，参见 wlog）。由于动态自适应具有混沌特性，压缩结果不可复现。

注：在撰写本文时，--adapt 与多个工作线程（>=2）结合使用时，可能会一直停留在低速状态。

•

--long[=#]：启用长距离匹配，其 windowLog 为 #；如果没有给出 #，则默认为 27。这会增大窗口大小（windowLog）以及压缩器和解压缩器的内存占用。此设置旨在提高那些在较大距离上存在长匹配的文件的压缩率。

注意：如果 windowLog 设置为大于 27，则需要向解压缩器传递 --long=windowLog 或 --memory=windowSize。

• --max：将高级参数设置为最大压缩。警告：此设置非常慢，并且会占用大量资源。它不适用于 32 位模式，因此在该模式下被禁用。
• -D DICT：使用 DICT 作为字典来压缩或解压缩文件
• --patch-from FILE：指定要用作 zstd 差分引擎参考点的文件。这实际上就是字典压缩，只是采用了一些方便的参数选择，即 windowSize > srcSize。

注意：不能同时使用此选项和 -D。

注意：如果 chainLog < fileLog（fileLog 即覆盖整个文件所需的 windowLog），则会自动激活 --long 模式。你也可以手动强制启用它。

注意：在不超过 15 级的情况下，你可以在 --single-thread 模式下使用 --patch-from，以速度为代价略微提高压缩率。在 15 级以上使用 “--single-thread” 会导致更低的压缩率。

注意：对于 19 级，你可以通过将 --zstd=targetLength= 指定为较大的值（例如 4096），并设置较大的 --zstd=chainLog=，以速度为代价来提高压缩率。

• --rsyncable：zstd 会定期同步压缩状态，以使压缩文件对 rsync 更友好。这对压缩率的影响可以忽略不计，但可能会影响压缩速度，在较高速度下会较为明显，例如当 --rsyncable 与许多并行工作线程结合使用时。此特性不适用于 --single-thread。你或许不会想在长距离模式下使用它，因为这会降低同步点的效果，不过实际情况可能因人而异。
• -C, --[no-]check：添加根据未压缩数据计算得出的完整性校验（默认值：启用）
• --[no-]content-size：启用/禁用是否将文件的原始大小放入压缩文件的头部。默认选项为 --content-size（意味着原始大小将被放入头部）。
• --no-dictID：不在帧头部中存储字典 ID（字典压缩）。解码器将不得不依赖关于使用哪个字典的隐式知识，而无法检查其是否正确。
• -M#, --memory=#：设置内存使用上限。默认情况下，zstd 将 128 MiB 作为解压缩器允许使用的最大内存量，但如有需要，你可以手动在任一方向上覆盖此值（即可以增大或减小它）。

在与 --patch-from= 一起使用进行压缩时，也会用到此值。在这种情况下，此参数会覆盖字典所允许的最大大小（128 MiB）。

此外，这还可用于限制字典训练所用的内存。此参数会覆盖默认的 2 GiB 限制。zstd 将加载训练样本直到达到内存上限，并忽略其余部分。

• --stream-size=#：设置来自流的输入所承诺的源大小。此值必须精确，因为它将被包含在生成的帧头部中。不正确的流大小会导致错误。此信息将用于更好地优化压缩参数，从而带来更好且可能更快的压缩，尤其是对于较小的源大小。
• --size-hint=#：在处理来自流的输入时，zstd 在优化压缩参数时必须猜测源大小会有多大。如果流的大小相对较小，这一猜测可能不准确，从而导致压缩率高于预期。此特性允许在需要时控制该猜测值。精确的猜测会带来更好的压缩率。高估会导致压缩率略有下降，而低估则可能导致显著下降。
• --target-compressed-block-size=#：尝试生成大约为此大小的压缩块。为了接近此目标，较大的块会被拆分。当接收方能够利用提前收到的不完整数据时，此特性对于改善延迟尤其有用。此参数定义的是一个宽松的目标：压缩块会以“平均”达到此大小为目标，但各个块仍可能更大或更小。启用此特性在 1 级时最多可使压缩速度降低约 10%。级别越高，相对速度的下降越小，在更高的设置下则难以察觉。
• -f, --force：禁用输入和输出检查。允许覆盖现有文件、从控制台输入、输出到 stdout、对链接和块设备等进行操作。在解压缩过程中且输出目标为 stdout 时，将无法识别的格式原样透传。
• -c, --stdout：写入标准输出（即使它是控制台）；保留原始文件（禁用 --rm）。
• -o FILE：将结果保存到 FILE。请注意，此操作与 -c 冲突。如果命令行中同时出现这两个操作，则以最后给出的为准。
• --[no-]sparse：启用/禁用稀疏文件系统支持，以使含有大量零字节的文件在磁盘上占用更小的空间。创建稀疏文件可以节省磁盘空间，并通过减少磁盘 I/O 量来加快解压缩。默认值：当输出到文件时启用，当输出为 stdout 时禁用。此设置会覆盖默认值，并可强制在 stdout 上使用稀疏模式。
• --[no-]pass-through：启用/禁用将未压缩文件原样透传。在解压缩过程中启用透传时，无法识别的格式将从输入原样复制到输出。默认情况下，当输出目标为 stdout 且设置了强制（-f）选项时，会进行透传。
• --rm：在压缩或解压缩成功后删除源文件。如果输出为 stdout，此命令会被静默忽略。如果与 -o 结合使用，由于这是一项破坏性操作，会触发确认提示（可用 -f 使其静默）。
• -k, --keep：在压缩或解压缩成功后保留源文件。这是默认行为。
• -r：对目录进行递归操作。它会选中指定目录及其所有子目录中的全部文件。当文件很多且文件名会超出命令行的最大长度时，这既有助于减少命令行输入，也可以规避 shell 展开的限制。
• --filelist FILE：从 FILE 中读取要处理的文件列表作为内容。其格式与 ls 的输出兼容，每行一个文件。
• --output-dir-flat DIR：生成的文件会被存储到目标 DIR 目录中，而不是与源文件相同的目录。请注意，如果来自不同目录的多个文件最终具有相同的名称，此命令可能会引入命名冲突问题。冲突解决机制会确保具有某一名称的第一个文件出现在 DIR 中，而在与 -f 结合使用时，则会改为保留最后一个文件。
• --output-dir-mirror DIR：与 --output-dir-flat 类似，输出文件会被存储在目标 DIR 目录之下，但此选项会将输入的目录层次结构复制到输出的 DIR 中。

如果输入目录包含 “..”，则该目录中的文件将被忽略。如果输入目录是绝对目录（例如 “/var/tmp/abc”），它将被存储到 “output-dir/var/tmp/abc” 中。如果有多个输入文件或目录，命名冲突的解决将遵循与 --output-dir-flat 相同的规则。

• --format=FORMAT：以其他格式进行压缩和解压缩。如果编译时启用了相应支持，zstd 可以压缩为其他压缩算法格式，或从中解压缩。可能可用的选项有 zstd、gzip、xz、lzma 和 lz4。如果未提供此类格式，则默认为 zstd。
• -h/-H, --help：显示帮助/详细帮助并退出
• -V, --version：显示版本号并立即退出。请注意，由于它会退出，在 -V 之后指定的标志实际上会被忽略。高级用法：-vV 还会显示所支持的格式。-vvV 还会显示 POSIX 支持情况。-qV 将只显示版本号，适合机器读取。
• -v, --verbose：详细模式，显示更多信息
• -q, --quiet：抑制警告、交互和通知。指定两次也会抑制错误。
• --no-progress：不显示进度条，但保留所有其他消息。
• --show-default-cparams：根据所提供的压缩级别和输入大小，显示将用于某个特定输入文件的默认压缩参数。如果所提供的文件不是普通文件（例如管道），此标志将输出用于未知大小输入的参数。
• --exclude-compressed：仅压缩尚未被压缩的文件。
• --：-- 之后的所有参数都被视为文件

gzip 操作修饰符¶

在经由 gzip 符号链接调用时，zstd 将支持以下额外的选项来模拟 gzip 的行为：

-n, --no-name

压缩文件时不要保存原始文件名和时间戳。这是默认选项，因此不会改变程序行为。

--best

是 -9 选项的别名。

环境变量¶

使用环境变量来设置参数会带来安全方面的影响。因此，这一途径被有意加以限制。目前仅支持 ZSTD_CLEVEL 和 ZSTD_NBTHREADS。它们分别设置压缩时使用的默认压缩级别和线程数。

ZSTD_CLEVEL 可用于设置 1 到 19 之间（即“正常”范围）的级别。如果 ZSTD_CLEVEL 的值不是有效的整数，它将被忽略并给出一条警告消息。ZSTD_CLEVEL 只是替换默认的压缩级别（3）。

ZSTD_NBTHREADS 可用于设置 zstd 在压缩时将尝试使用的线程数。如果 ZSTD_NBTHREADS 的值不是有效的无符号整数，它将被忽略并给出一条警告消息。ZSTD_NBTHREADS 的默认值为 max(1, min(4, nbCores/4))，且上限为 ZSTDMT_NBWORKERS_MAX==200。必须在编译 zstd 时启用多线程支持，此变量才会产生任何效果。

这两者都可以被相应的命令行参数覆盖：-# 用于压缩级别，-T# 用于压缩线程数。

--zstd[=options]:¶

options 以逗号分隔的列表形式提供。你可以只指定想要更改的选项，其余的将取自所选的或默认的压缩级别。可用 options 的列表如下：

strategy=strat, strat=strat

指定匹配查找器所使用的策略。

共有 9 种策略，编号从 1 到 9，从最快到最强：1=ZSTD_fast, 2=ZSTD_dfast, 3=ZSTD_greedy, 4=ZSTD_lazy, 5=ZSTD_lazy2, 6=ZSTD_btlazy2, 7=ZSTD_btopt, 8=ZSTD_btultra, 9=ZSTD_btultra2。

windowLog=wlog, wlog=wlog

指定匹配距离的最大位数。

该值越大，找到匹配的机会就越大，这通常会提高压缩率。它也会增加压缩器和解压缩器的内存需求。wlog 的最小值为 10（1 KiB），最大值在 32 位平台上为 30（1 GiB），在 64 位平台上为 31（2 GiB）。

注意：如果 windowLog 设置为大于 27，则需要向解压缩器传递 --long=windowLog 或 --memory=windowSize。

hashLog=hlog, hlog=hlog

指定哈希表的最大位数。

更大的哈希表会减少冲突，这通常会使压缩更快，但在压缩过程中需要更多内存。

hlog 的最小值为 6（64 个条目 / 256 B），最大值为 30（10 亿个条目 / 4 GiB）。

chainLog=clog, clog=clog

指定次级搜索结构的最大位数，其形式取决于所选的 strategy。

位数越多，找到匹配的机会就越大，这通常会提高压缩率。它也会降低压缩速度并增加压缩的内存需求。对于只有主哈希表的 ZSTD_fast strategy，此选项会被忽略。

clog 的最小值为 6（64 个条目 / 256 B），最大值在 32 位平台上为 29（5.12 亿个条目 / 2 GiB），在 64 位平台上为 30（10 亿个条目 / 4 GiB）。

searchLog=slog, slog=slog

以对数刻度指定在哈希链或二叉树中的最大搜索次数。

更多的搜索会增大找到匹配的机会，这通常会提高压缩率但会降低压缩速度。

slog 的最小值为 1，最大值为 “windowLog” - 1。

minMatch=mml, mml=mml

指定在哈希表中匹配的最小搜索长度。

更大的搜索长度通常会降低压缩率，但会提高解压缩速度。

mml 的最小值为 3，最大值为 7。

targetLength=tlen, tlen=tlen

此字段的影响因所选策略而异。

对于 ZSTD_btopt、ZSTD_btultra 和 ZSTD_btultra2，它指定使匹配查找器停止搜索的最小匹配长度。更大的 targetLength 通常会提高压缩率但会降低压缩速度。

对于 ZSTD_fast，当其 > 0 时会触发超快模式。该值表示在匹配采样之间跳过的数据量。其影响是相反的：更大的 targetLength 会提高压缩速度但会降低压缩率。

对于所有其他策略，此字段没有影响。

tlen 的最小值为 0，最大值为 128 KiB。

overlapLog=ovlog, ovlog=ovlog

确定 overlapSize，即从上一个任务重新加载的数据量。此参数仅在启用多线程时可用。重新加载更多数据会提高压缩率，但会降低速度。

ovlog 的最小值为 0，最大值为 9。1 表示“无重叠”，因此任务之间完全独立。9 表示“完全重叠”，即从上一个任务最多重新加载 windowSize 大小的数据。将 ovlog 减小 1 会使重新加载的数据量减少为原来的一半。例如，8 表示“windowSize/2”，6 表示“windowSize/8”。值 0 比较特殊，表示“默认”：ovlog 由 zstd 自动确定。在这种情况下，ovlog 的取值将在 6 到 9 之间，具体取决于所选的 strat。

ldmHashRateLog=lhrlog, lhrlog=lhrlog

指定向长距离匹配哈希表中插入条目的频率。

除非启用了长距离匹配，否则此选项会被忽略。

更大的值将提高压缩速度。与默认值偏离太远很可能会导致压缩率下降。

默认值在 4 到 7 之间变化，具体取决于 strategy。

ldmHashLog=lhlog, lhlog=lhlog

指定用于长距离匹配的哈希表的最大大小。

除非启用了长距离匹配，否则此选项会被忽略。

更大的哈希表通常会提高压缩率，但代价是压缩过程中占用更多内存以及压缩速度下降。

lhlog 的最小值为 6，最大值为 30（默认值：windowLog - ldmHashRateLog）。

ldmMinMatch=lmml, lmml=lmml

指定长距离匹配中匹配的最小搜索长度。

除非启用了长距离匹配，否则此选项会被忽略。

过大或过小的值通常都会降低压缩率。

lmml 的最小值为 4，最大值为 4096（默认值：32 到 64，具体取决于 strategy）。

ldmBucketSizeLog=lblog, lblog=lblog

指定用于长距离匹配的哈希表中每个桶的大小。

除非启用了长距离匹配，否则此选项会被忽略。

更大的桶大小会改善冲突解决，但会降低压缩速度。

lblog 的最小值为 1，最大值为 8（默认值：4 到 8，具体取决于 strategy）。

示例¶

对于大于 256 KB 的文件，以下参数会将高级压缩选项设置为类似于预定义的 19 级：

--zstd=wlog=23,clog=23,hlog=22,slog=6,mml=3,tlen=48,strat=6

-B#:¶

指定每个压缩任务的大小。此参数仅在启用多线程时可用。每个压缩任务并行运行，因此此值会间接影响活动线程的数量。默认任务大小因压缩级别而异（通常为 4 * windowSize）。-B# 使得手动选择自定义大小成为可能。请注意，任务大小必须满足一个透明强制执行的最小值。该最小值为 512 KB 或 overlapSize 中的较大者。不同的任务大小会导致不完全相同的压缩帧。