拼接 .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 中的較大者。不同的任務大小會導致不完全相同的壓縮幀。