lz4 命令行完全指南：掌握 lz4、unlz4、lz4cat 的压缩与解压实战-迪斯科星球

lz4 命令行完全指南：掌握 lz4、unlz4、lz4cat 的压缩与解压实战

【免费下载链接】lz4Extremely Fast Compression algorithm项目地址: https://gitcode.com/GitHub_Trending/lz/lz4

lz4 是基于 liblz4 的极速无损压缩命令行工具，本指南以仓库 programs/lz4.1.md 手册页为核心骨架，完整讲解 lz4 / unlz4 / lz4cat 三个命令的语法、全部选项参数、多文件模式、基准测试与环境变量，并结合 programs/lz4cli.c、programs/lz4io.c、programs/lz4conf.h 等源码剖析每个选项的底层实现。读完本文，你将能熟练使用 lz4 完成单文件/多文件/流式压缩、解压、完整性校验、性能基准测试，并理解压缩级别、块大小、校验和、字典、线程数等参数如何影响压缩比与速度。

命令概览（SYNOPSIS）

lz4 的命令行基本形式为：

lz4 [OPTIONS] [-|INPUT-FILE] <OUTPUT-FILE>

其中-表示标准输入/标准输出。此外，lz4 还提供两个别名命令：

unlz4等价于lz4 -d，即解压；
lz4cat等价于lz4 -dcfm，即强制解压并输出到标准输出、允许覆盖、支持多文件输入。

这两个别名的行为并非手动拼凑：在 programs/lz4cli.c 中，exeNameMatch()会检查可执行文件的调用名，若名为lz4cat则自动进入解压模式并强制写入 stdout，若名为unlz4则自动进入解压模式（见 programs/lz4cli.c）。因此同样的二进制，通过不同链接名调用就会呈现不同默认行为。

手册建议：在编写需要解压文件的脚本时，应始终使用lz4名称并携带明确参数（lz4 -d或lz4 -dc），而不要依赖unlz4、lz4cat这些名字，因为脚本运行环境的调用方式可能变化，显式指定参数最稳妥。

核心定位：极速压缩与原生 .lz4 格式

lz4是基于liblz4的 CLI 前端，liblz4是一种极快的无损压缩算法实现，默认压缩速度通常可达每核心 500 MB/s 以上。通过提高压缩级别参数，可以用压缩速度换取更好的压缩比；解压虽然是单线程，但速度可达数 GB/s，通常快到受限于 I/O 而非 CPU。lz4 的原生文件格式即.lz4格式。

压缩和解压的速度特性从 lib/lz4.h 与 lib/lz4frame.h 的公开接口设计中可见一斑：核心 API 提供LZ4_compress_fast()等极简调用路径，而lz4frame层负责.lz4帧的封装。帧与块的二进制布局详见 doc/lz4_Frame_format.md 与 doc/lz4_Block_format.md。

lz4 与 gzip 的差异

lz4 支持与gzip(1)相似但并不完全相同的命令行语法，主要差异如下：

默认只压缩单个文件（多文件需加-m）；
lz4 file1 file2的含义是：把 file1 压缩到 file2 中；
lz4 file.lz4默认执行解压（可用-z强制压缩）；
默认保留原始文件（可用--rm在完成后删除源文件）；
单文件压缩/解压期间会显示实时统计信息（可用-q静默）；
未指定输出时，结果发送到"隐式输出"：
- 若 stdout 不是控制台（如重定向到管道或文件），stdout 成为隐式输出；
- 若 stdout 是控制台，隐式输出为filename.lz4；
- 手册明确告诫：脚本中依赖隐式输出是不良实践，因为脚本环境可能变化，应始终显式指定输出；-c保证输出到 stdout，而提供输出文件名或使用-m则保证输出到指定名称或filename.lz4。

这些默认行为可以通过"主动选择"的命令修改：

lz4 -m支持多个输入文件，逐个压缩为带.lz4后缀的文件；此时进度通知默认关闭（可用-v重新开启）。该模式更接近 gzip 的命令行行为，主要剩余差异是默认保留源文件；
lz4 -m -d可批量解压多个*.lz4文件；
可通过--rm选择在压缩或解压成功后删除源文件；
因此lz4 -m --rm的行为最接近 gzip 默认（gzip 会删除源文件，而lz4 -m等价于gzip -k，保留源文件）。

.lz4 文件拼接

.lz4文件可以直接拼接。lz4会把拼接后的文件当作单个.lz4文件解压。例如：

lz4 file1 > foo.lz4 lz4 file2 >> foo.lz4

之后lz4cat foo.lz4等价于cat file1 file2。这一特性在测试脚本 tests/test-lz4-frame-concatenation.sh 中有专门覆盖，其底层依据是lz4frame解码器天然支持连续多个帧的读取。

选项通用规则

短命令拼接

部分选项既可用短命令-x，也可用长命令--long-word。短命令可以拼接，例如-d -c等价于-dc；长命令不能拼接，必须用空格明确分隔。

多个矛盾命令

当同一命令行出现多个相互矛盾的命令时，只有最后一条生效。例如lz4 -z file.lz4 -d会以解压模式执行（后写的-d覆盖先写的-z）。这一"后者覆盖前者"的语义直接体现在 programs/lz4cli.c 的解析循环中：case 'z'将模式设为压缩、case 'd'将模式设为解压，解析顺序即最终生效顺序。

操作模式

选项	含义
`-z--compress`	压缩。当命令行未指定任何操作模式、命令名未隐含其他模式（如`unlz4`隐含`--decompress`）、输入文件名也未隐含其他模式（如`.lz4`扩展名默认隐含`--decompress`）时，压缩是默认操作模式。`-z`还可用于强制压缩一个已是`.lz4`的文件
`-d--decompress--uncompress`	解压。当输入文件名以`.lz4`结尾时，解压也是默认操作
`-t--test`	测试`.lz4`文件的完整性。解压出的数据被丢弃，不创建也不删除任何文件
`-b#`	基准测试模式，使用`#`压缩级别
`--list`	列出`.lz4`文件信息；查看多帧文件的详细信息可加`-v`。`--list`会自动触发`-m`修饰

模式自动推断在源码中有明确实现：determineOpMode()检查输入文件名是否以.lz4扩展名结尾，是则返回解压模式，否则返回压缩模式（见 programs/lz4cli.c）。当未指定输出文件且模式为om_auto时，该函数决定最终走向压缩还是解压（见 programs/lz4cli.c）。-t的实现也很直观：解析到-t后，CLI 将输出重定向到空设备并转交解压流程（见 programs/lz4cli.c），因此测试模式不产生任何文件。

操作修饰符

压缩级别：`-#`

压缩级别取 1 到 12 之间的任意整数，数值越大，用压缩速度换取更高压缩比；12 以上的值按 12 处理。推荐值：

1：快速压缩（默认）；
9：高压缩。

速度/压缩比的取舍随待压缩数据而异，但所有级别下解压速度都保持很快。该默认值在 programs/lz4conf.h 中定义为LZ4_CLEVEL_DEFAULT 1，并被命令行-#覆盖。

超快级别：`--fast[=#]`

切换到超快压缩级别。数值越大压缩越快，但压缩产物越大。若省略=#，默认取1。该设置会覆盖先前设置的压缩级别；同样，--fast之后再设置压缩级别也会覆盖它。在源码中，--fast把压缩级别编码为负数加速值：cLevel = -(int)fastLevel（见 programs/lz4cli.c），负压缩级别在 liblz4 中即代表加速倍数语义。

最高压缩：`--best`

设置最高压缩级别，等价于-12。源码中--best直接映射到LZ4HC_CLEVEL_MAX（见 programs/lz4cli.c）。

多线程：`-T#`、`--threads=#`

使用#个线程进行压缩。传0或不传数值时，线程数由检测到的 CPU 核心数自动决定。注意：

多线程能力依赖编译期开关LZ4IO_MULTITHREAD，在 programs/lz4conf.h 中 Windows 默认开启（利用 Completion Ports），其他平台默认关闭（需要 pthread 支持并在构建时开启）；
运行时可选线程数上限为LZ4_NBWORKERS_MAX（默认 200，见 programs/lz4conf.h），超出会自动截断（见 programs/lz4cli.c）；
若二进制未编译多线程支持却传了-T#（#>1），会给出警告提示（见 programs/lz4cli.c）。

面向解压速度优化：`--favor-decSpeed`

生成针对解压速度优化的压缩数据。代价是压缩产物略大（通常约 0.5%），而解压速度可提升 5%–20%，具体取决于使用场景。该选项只在很高的压缩级别（>=10）下起作用。底层对应LZ4IO_favorDecSpeed(prefs, 1)，会开启 HC 压缩器中的解压速度优化路径（见 programs/lz4cli.c）。

字典：`-D dictionaryName`

使用字典dictionaryName进行压缩、解压或基准测试。压缩与解压必须使用同一字典才能兼容；解压时使用不同字典要么因解压错误而中止，要么产生校验和错误。CLI 层通过LZ4IO_setDictionaryFilename()把字典文件名传递给 I/O 层（见 programs/lz4io.c 与 programs/lz4cli.c），字典加载后供压缩上下文引用。字典压缩的正确用例如下：

lz4 -D dict file > file.lz4 lz4 -D dict -d file.lz4

强制覆盖与透传：`-f--[no-]force`

该选项有多重效果：

若目标文件已存在，不提示直接覆盖；
与--decompress结合且 lz4 无法识别源文件类型时，将源文件原样复制到标准输出。这使得lz4cat --force可以像cat(1)一样用于未经 lz4 压缩的文件。

源码中-f通过LZ4IO_setOverwrite(prefs, 1)打开覆盖（见 programs/lz4cli.c），而--no-force会将其关闭；透传行为由LZ4IO_setPassThrough()控制（见 programs/lz4io.c），lz4cat与-c都会开启它。

强制输出到标准输出：`-c--stdout--to-stdout`

强制写入标准输出，即使 stdout 是控制台。解析到-c时，CLI 设置forceStdout=1并把输出文件名置为 stdout 标记（见 programs/lz4cli.c）。反过来，如果输出目标是控制台且未加-c，CLI 会拒绝执行（见 programs/lz4cli.c）。

多文件：`-m--multiple`

多个输入文件。压缩文件名自动追加.lz4后缀；该模式还会降低通知级别，也可用于列出多个文件。lz4 -m行为等价于gzip -k（默认保留源文件）。同时传入多个非选项参数时，正是multiple_inputs标志把它们收集到输入文件表中（见 programs/lz4cli.c）。

递归目录：`-r`

对目录递归操作，该模式同时隐式启用-m（多文件输入）。在 programs/lz4cli.c 中-r设置recursive=1并落入case 'm'；递归展开目录列表由UTIL_createFileList()完成。

块大小：`-B#`

块大小取值4-7，默认7：

取值	块大小
`-B4`	64 KB
`-B5`	256 KB
`-B6`	1 MB
`-B7`	4 MB（默认）

在 programs/lz4io.c 中，LZ4IO_setBlockSizeID()用静态表{ 64 KB, 256 KB, 1 MB, 4 MB }完成 ID 到字节数的映射，超出[4,7]范围的 ID 返回 0 即无效。默认块大小 ID 由 programs/lz4conf.h 的LZ4_BLOCKSIZEID_DEFAULT 7决定。另外，CLI 也接受-B后跟大于 7 的数值（如-B32，单位 KB 起），此时走LZ4IO_setBlockSize()路径，把任意字节数归一到最接近的标准块大小（见 programs/lz4cli.c 与 programs/lz4io.c）。

块关联性：`-BI`/`-BD`

-BI：生成独立块（默认）。每个块可独立解压，适合随机访问；
-BD：块依赖前序块（Linked blocks），可提升压缩比，在小块上更明显。

底层实现是LZ4IO_setBlockMode()设置blockIndependence标志（见 programs/lz4io.c）。随机访问场景可参考仓库示例 examples/dictionaryRandomAccess.c 中的块定位思想。

块校验和：`-BX`

生成块校验和（默认关闭）。对应LZ4IO_setBlockChecksumMode(prefs, 1)（见 programs/lz4cli.c 与 programs/lz4io.c）。

帧校验和：`--[no-]frame-crc`

选择帧校验和，默认开启。--frame-crc调用LZ4IO_setStreamChecksumMode(prefs, 1)，--no-frame-crc关闭（见 programs/lz4cli.c）。帧校验和位于.lz4帧尾部，用于检测整帧完整性。

同时关闭校验：`--no-crc`

同时禁用帧校验和与块校验和。源码中它同时调用LZ4IO_setStreamChecksumMode(0)与LZ4IO_setBlockChecksumMode(0)（见 programs/lz4cli.c）。注意这与帧格式规范的关系：帧头中的校验标志位随之置零，具体字段定义见 doc/lz4_Frame_format.md。

内容大小：`--[no-]content-size`

在帧头中包含原始大小（默认不包含）。注意：仅当原始大小可确定时才能启用，即输入是文件；对于 stdin 或管道等未知大小的输入无效。CLI 会在 stdin 场景下给出明确警告（见 programs/lz4cli.c）。底层通过LZ4IO_setContentSize()控制contentSizeFlag（见 programs/lz4io.c）。携带内容大小后，解压端可通过lz4 --list查看原始大小。

稀疏文件：`--[no-]sparse`

稀疏模式支持，默认在文件上启用、在 stdout 上禁用。稀疏文件能跳过全零块，减少磁盘占用，适合解压含大量零字节的数据。LZ4IO_setSparseFile()用值2表示"强制启用"（见 programs/lz4io.c），--sparse传 2、--no-sparse传 0。稀疏行为有专门测试脚本 tests/test-lz4-sparse.sh 覆盖。

旧版格式：`-l`

使用 Legacy 格式（典型用于 Linux 内核压缩）。注意-l与-m（--multiple）及-r不兼容。Legacy 格式是 lz4 早期帧格式，已标记为 deprecated；源码中-l会把块大小固定为 8 MB 并走独立的 Legacy 压缩路径（见 programs/lz4cli.c 与 programs/lz4cli.c）。

其他选项

选项	含义
`-v--verbose`	详细模式
`-q--quiet`	抑制警告与实时统计；指定两次可连错误一并抑制
`-h-H--help`	显示帮助/长帮助并退出
`-V--version`	显示版本号并退出
`-k--keep`	保留源文件（默认行为，为 xz/lzma 兼容而提供）
`--rm`	压缩或解压成功后删除源文件
`--`	之后的所有参数一律视为文件名（用于处理以`-`开头的文件）

其中--在源码中通过all_arguments_are_files=1实现，解析循环随后跳过所有以-开头的参数判断（见 programs/lz4cli.c 与 programs/lz4cli.c）。-q是递减式通知级别：每出现一次-q，displayLevel减一（见 programs/lz4cli.c），所以两次-q才压过错误输出级别。-v则递增该级别（见 programs/lz4cli.c），最终通过LZ4IO_setNotificationLevel()作用于 I/O 层（见 programs/lz4io.c）。

基准测试模式（Benchmark）

-b#：以压缩级别#对文件做基准测试；
-e#：基准测试多个压缩级别，从b#到e#（含两端）；
-i#：每个级别最短评测时间（秒），取值范围1-9，默认3。

基准模式是独立于压缩/解压的第五种操作模式om_bench，解析到-b后直接调用BMK_benchFiles()（见 programs/lz4cli.c 与 programs/lz4cli.c）。最短评测时间在 programs/bench.c 中由BMK_setNbSeconds()设置并参与循环计时；评测结果按"每秒处理字节数/压缩比"输出。典型用法：

lz4 -b7 file # 级别 7，默认测 3 秒 lz4 -b1 -e12 -i5 file # 扫描级别 1 到 12，每级测 5 秒 lz4 -b7 -d file.lz4 # 仅测解压速度（-d 触发 decode-only 模式）

-d与基准模式组合时不会切换模式，而是开启BMK_setDecodeOnlyMode(1)只评测解压（见 programs/lz4cli.c 与 programs/bench.c）。

环境变量

在某些场景下（例如从脚本中调用 lz4，却无法向其传递参数）可以通过环境变量传递参数。环境变量的优先级高于可执行文件内置默认值，但低于命令行中对应的运行时命令。将环境变量设置为全局值时，可以强制应用不同于内置默认值的个性化默认值。

`LZ4_CLEVEL`

指定 lz4 在命令行未给出压缩级别时使用的默认压缩级别。可执行文件内置默认一般为1。读取逻辑见 programs/lz4cli.c：启动时init_cLevel()读取环境变量，若为合法的无符号数字则采用，否则回退到LZ4_CLEVEL_DEFAULT；命令行解析中的-#随后覆盖它。

export LZ4_CLEVEL=9 lz4 file # 等价于 lz4 -9 file

`LZ4_NBWORKERS`

指定 lz4 压缩时使用的默认线程数。内置默认一般为0，即依据本地 CPU 自动确定。该功能仅当 lz4 以多线程支持编译时相关（见上文LZ4IO_MULTITHREAD）；worker 数量上限为LZ4_NBWORKERS_MAX（默认200）。读取逻辑见 programs/lz4cli.c 的init_nbWorkers()，命令行-T#会覆盖环境变量。

export LZ4_NBWORKERS=4 lz4 -T1 file # 命令行优先，实际只用 1 线程

源码视角：lz4 CLI 的完整决策流程

把手册内容映射到代码，一条lz4命令的执行可概括为五个阶段（均在 programs/lz4cli.c 的main()中，L393-L896）：

初始化默认值：读取环境变量得到初始压缩级别与线程数，创建 I/O 偏好结构LZ4IO_prefs_t，按 programs/lz4conf.h 的编译期常量设定块大小、覆盖策略等默认值；
依据调用名预设行为：exeNameMatch()识别lz4cat/unlz4/lz4c旧版兼容名，分别预设解压模式、透传、stdout 输出或旧版命令语法（L433-L445）；
逐参数解析：长命令--xxx优先匹配，短命令支持拼接并逐个字符switch处理；矛盾选项"后者生效"；--之后的参数全部视为文件（L448-L709）；
推断缺失信息：无输入时回退 stdin；无输出时依据determineOpMode()自动生成filename.lz4或去掉.lz4后缀（L769-L814）；stdout 为控制台且未加-c时拒绝执行（L825-L832）；
分发执行：按最终模式调用LZ4IO_compressFilename/LZ4IO_decompressFilename/ 多文件变体 /LZ4IO_displayCompressedFilesInfo/BMK_benchFiles（L842-L887）。

多线程压缩在分发前还有一道截断逻辑：nbWorkers==0时用LZ4IO_defaultNbWorkers()按 CPU 核数自动确定，超过LZ4_NBWORKERS_MAX则截断到上限（见 programs/lz4cli.c）。

常用实战示例汇总

# 基础压缩与解压 lz4 file # 生成 file.lz4（默认级别 1） lz4 -9 file # 高压缩比 lz4 --fast=5 file # 超快压缩 lz4 -d file.lz4 # 解压 lz4 -dc file.lz4 > out # 解压到 stdout # 管道与流式处理 cat big.log | lz4 > big.log.lz4 lz4 -d < big.log.lz4 | less # 多文件与递归 lz4 -m a b c # 生成 a.lz4 b.lz4 c.lz4 lz4 -m -d *.lz4 # 批量解压 lz4 -r dir/ # 递归压缩目录（隐含 -m） lz4 -m --rm a b # 压缩后删除源文件（最接近 gzip 行为） # 完整性校验与信息查看 lz4 -t file.lz4 # 仅测试完整性，无文件产生 lz4 --list file.lz4 # 列出帧信息（-v 查看多帧详情） # 帧属性微调 lz4 -B5 -BX --no-crc file # 256KB 块 + 块校验和、无帧校验和 lz4 -BD --content-size file # 关联块 + 记录原始大小 lz4 --favor-decSpeed -12 file # 面向解压速度优化（需高压缩级别） # 字典压缩 lz4 -D dict file > file.lz4 lz4 -D dict -d file.lz4 # 基准测试 lz4 -b7 file lz4 -b1 -e12 -i5 file

企业官网建设流程全解析