Ubuntu 22.04 安装 Apache Commons Compress 指南

目标：在一台全新的 Ubuntu 22.04 服务器上搭建可编译、可运行 Apache Commons Compress 的 Java 环境，并提供 Maven 依赖与官方发行包两种获取 jar 的方案。全部命令与回显已在 Ubuntu 22.04（JDK 17 + Maven）实测通过。

一、环境信息

本章先确认操作系统版本，再安装 JDK 17 与 Maven，为后续获取 Commons Compress 做准备。Commons Compress 1.28.0 编译目标为 Java 8（jar 内清单 X-Compile-Target-JDK: 1.8），因此 JDK 8 及以上均可运行，本文统一使用 JDK 17 作为开发与运行环境。

先确认系统版本：

cat /etc/os-release | grep -E "^(NAME|VERSION)="

实测回显：

NAME="Ubuntu"
VERSION="22.04.5 LTS (Jammy Jellyfish)"

安装 JDK 17 与 Maven（约 1~2 分钟，取决于网络）：

sudo apt update
sudo apt install -y openjdk-17-jdk maven

实测回显（节选，实测首尾）：

Reading package lists... Done
Building dependency tree... Done
The following additional packages will be installed:
  openjdk-17-jdk-headless openjdk-17-jre openjdk-17-jre-headless
Suggested packages:
  openjdk-17-demo openjdk-17-source visualvm maven-docs
Setting up openjdk-17-jdk:amd64 (17.0.20.1+1-1~22.04) ...
Setting up maven (3.6.3-5) ...

验证安装结果：

java -version
javac -version
mvn -v

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
javac 17.0.20.1
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en, platform encoding: UTF-8
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

输出中 Java version: 17.0.20.1 说明 Maven 已经用上了刚安装的 JDK 17。若这一行显示的是其他版本，请在 ~/.bashrc 中追加 export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 后重新登录。

💡 技术拓展：压缩领域有两类工具，选型前要先分清。**归档（archiver）**把多个文件打包成一个文件，本身不一定压缩；**压缩（compressor）**只针对单条数据流做编码压缩。下表是常见格式的对比：

类别	格式	是否压缩	随机访问	典型工具
归档	tar	否（仅打包）	否	GNU tar、Commons Compress
归档	zip	是（每条目 DEFLATE）	是（中央目录）	Info-ZIP、Commons Compress
归档	jar	是（zip 超集）	是	JDK jar、Commons Compress
归档	7z	是	部分	p7zip、Commons Compress（只读为主）
压缩	gzip	是（DEFLATE）	否	gzip、Commons Compress
压缩	bzip2	是（BWT）	否	bzip2、Commons Compress
压缩	xz	是（LZMA2）	否	XZ Utils、Commons Compress
压缩	zstd	是（Zstandard）	否	zstd、Commons Compress（需 zstd-jni）

本文安装的 Commons Compress 属于 Java 库，同时覆盖「归档」与「压缩」两类能力；tar.gz、tar.bz2 这类双扩展名就是「先归档再压缩」的两层结构。

二、版本选型

Commons Compress 遵循「最新版只挂在官方下载目录、旧版进归档仓库」的发布策略，选型时建议直接用最新稳定版。下表列出常用版本（JDK 要求以各版本 jar 清单与官方发布说明为准）：

版本	发布状态	JDK 要求	必需传递依赖	适用场景
1.28.0	最新稳定版（2025-07）	Java 8 及以上	commons-io 2.20.0、commons-lang3 3.18.0、commons-codec 1.19.0	新项目首选
1.27.1	稳定版	Java 8 及以上	commons-io、commons-lang3（1.27 起必需）	1.28 有兼容顾虑时的回退
1.26.0	稳定版	Java 8 及以上	commons-io 2.15.1、commons-lang3 3.14.0、commons-codec 1.16.1	存量项目锁版本
1.21	维护期版本	Java 8 及以上	commons-io（可选时期）	老系统兼容

关于「JDK 要求」的实测依据：解出 1.28.0 jar 的清单文件，其中 X-Compile-Source-JDK: 1.8、X-Compile-Target-JDK: 1.8、Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.8))" 三处都表明 1.28.0 的字节码目标是 Java 8，因此 JDK 8/11/17/21 都能运行（本文用 JDK 17 实测）。

本文统一采用以下坐标与下载地址（均实测有效）：

Maven 坐标：org.apache.commons:commons-compress:1.28.0
发行包：https://downloads.apache.org/commons/compress/binaries/commons-compress-1.28.0-bin.tar.gz
校验文件：https://downloads.apache.org/commons/compress/binaries/commons-compress-1.28.0-bin.tar.gz.sha512
sha512（实测）：
87c6b00ec854d8dc08834ed3bd1590d1facce45dad8c8fc37b2e82e30b18f793181f8dd6b8fcbba3850534b56cfafc7cfa3bd5236004293368fc3b7ff651d4b6

两点实测结论需要提前知道：

downloads.apache.org 只保留最新版。实测访问旧版地址 https://downloads.apache.org/commons/compress/binaries/commons-compress-1.26.0-bin.tar.gz 返回 404 Not Found，旧版需到 https://archive.apache.org/dist/commons/compress/binaries/ 下载，且该归档站点速度较慢。
从 1.27 开始，commons-io 与 commons-lang3 成为必需依赖（1.28.0 的 pom 里还多了 commons-codec），手动安装时必须一起放进类路径，否则运行期报 NoClassDefFoundError。

💡 技术拓展：如果只需要基础压缩能力，也可以选其他 Java 库。下表对比常见选择，本文使用功能最全的 Commons Compress：

库	坐标	支持格式	特点
JDK 内置	无（java.util.zip）	zip/gzip/deflate	零依赖，但不支持 tar、7z、bzip2、xz 等
Commons Compress	org.apache.commons:commons-compress	14 种压缩流、8 种归档流	覆盖面最广，API 统一
snappy-java	org.xerial.snappy:snappy-java	snappy	极致速度，JNI 实现，无归档能力
XZ for Java	org.tukaani:xz	xz/lzma	高压缩比，Commons Compress 以它为可选依赖

三、方案A：Maven 中央仓库依赖

方案A通过 Maven 自动下载 jar 及其全部传递依赖，是工程化项目的推荐做法。先创建项目骨架：

mkdir -p /opt/compress-demo/src/main/java/net/quzuo/demo
cd /opt/compress-demo

该命令无输出。写入 pom.xml：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>net.quzuo.demo</groupId>
  <artifactId>compress-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-compress</artifactId>
      <version>1.28.0</version>
    </dependency>
  </dependencies>
</project>

逐项说明：maven.compiler.source/target 指定按 Java 17 语法编译；project.build.sourceEncoding 强制源码按 UTF-8 读取；dependencies 只声明了 commons-compress 一个依赖，commons-io、commons-lang3、commons-codec 会作为传递依赖自动引入。

验证依赖解析结果：

mvn dependency:tree

实测回显（节选，实测首尾）：

[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ compress-demo ---
[INFO] net.quzuo.demo:compress-demo:jar:1.0.0
[INFO] \- org.apache.commons:commons-compress:jar:1.28.0:compile
[INFO]    +- commons-codec:commons-codec:jar:1.19.0:compile
[INFO]    +- commons-io:commons-io:jar:2.20.0:compile
[INFO]    \- org.apache.commons:commons-lang3:jar:3.18.0:compile
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

可以看到 commons-codec、commons-io、commons-lang3 三个 jar 都是 compile 作用域，即编译和运行都需要。写入最小验证程序 src/main/java/net/quzuo/demo/HelloCompress.java：

package net.quzuo.demo;

import org.apache.commons.compress.archivers.zip.ZipArchiveEntry;
import org.apache.commons.compress.archivers.zip.ZipArchiveOutputStream;
import org.apache.commons.compress.archivers.zip.ZipFile;

import java.io.BufferedReader;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;

public class HelloCompress {
    public static void main(String[] args) throws IOException {
        byte[] data = "hello commons compress".getBytes(StandardCharsets.UTF_8);
        ByteArrayOutputStream bos = new ByteArrayOutputStream();
        try (ZipArchiveOutputStream zos = new ZipArchiveOutputStream(bos)) {
            ZipArchiveEntry entry = new ZipArchiveEntry("hello.txt");
            entry.setSize(data.length);
            zos.putArchiveEntry(entry);
            zos.write(data);
            zos.closeArchiveEntry();
        }
        File tmp = File.createTempFile("hello", ".zip");
        Files.write(tmp.toPath(), bos.toByteArray());
        try (ZipFile zf = ZipFile.builder().setFile(tmp).setCharset("UTF-8").get();
             BufferedReader reader = new BufferedReader(
                     new InputStreamReader(zf.getInputStream(zf.getEntry("hello.txt")), StandardCharsets.UTF_8))) {
            System.out.println("zip 读回内容: " + reader.readLine());
        } finally {
            tmp.delete();
        }
        Package p = ZipArchiveEntry.class.getPackage();
        System.out.println("commons-compress 版本: " + p.getImplementationVersion());
        System.out.println("验证通过");
    }
}

程序逻辑：在内存里用 ZipArchiveOutputStream 建一个含单条目 hello.txt 的 zip，落盘后用 ZipFile 随机访问读回首行，并从 jar 清单打印库版本。编译运行：

mvn -q compile exec:java -Dexec.mainClass=net.quzuo.demo.HelloCompress

说明：exec:java 来自 exec-maven-plugin，首次使用需在 pom 的 build/plugins 中声明（groupId 为 org.codehaus.mojo），或允许 Maven 交互式拉取。实测回显：

zip 读回内容: hello commons compress
commons-compress 版本: 1.28.0
验证通过

三行输出分别确认了「写入-读回链路」「jar 版本」「程序正常退出」，方案A安装完成。

四、方案B：官方发行包手动安装

方案B适合无法使用 Maven 的机器：从官方站点下载发行包，手动拼类路径编译运行。创建安装目录并下载：

sudo mkdir -p /opt/commons
cd /opt/commons
sudo curl -fsSLO https://downloads.apache.org/commons/compress/binaries/commons-compress-1.28.0-bin.tar.gz
sudo curl -fsSLO https://downloads.apache.org/commons/compress/binaries/commons-compress-1.28.0-bin.tar.gz.sha512
ls -l

实测回显：

total 128716
-rw-r--r-- 1 root root 131792030 Oct 13 08:36 commons-compress-1.28.0-bin.tar.gz
-rw-r--r-- 1 root root       129 Oct 13 08:36 commons-compress-1.28.0-bin.tar.gz.sha512

发行包 131,792,030 字节，其中约 120MB 是测试代码 jar，属正常现象。.sha512 文件内容是裸哈希（129 字节：128 个十六进制字符加换行），校验时要把它拼成 哈希文件名 的标准格式再交给 sha512sum -c：

printf '%s  %s\n' "$(cat commons-compress-1.28.0-bin.tar.gz.sha512)" commons-compress-1.28.0-bin.tar.gz | sha512sum -c -

实测回显：

commons-compress-1.28.0-bin.tar.gz: OK

校验通过后解压并查看包内容：

sudo tar xzf commons-compress-1.28.0-bin.tar.gz
ls commons-compress-1.28.0/

实测回显：

LICENSE.txt  NOTICE.txt  README.txt  RELEASE-NOTES.txt  apidocs
commons-compress-1.28.0-javadoc.jar
commons-compress-1.28.0-sources.jar
commons-compress-1.28.0-test-sources.jar
commons-compress-1.28.0-tests.jar
commons-compress-1.28.0.jar

关键点：发行包里只有 commons-compress-1.28.0.jar 一个主 jar，没有 lib/ 目录，必需依赖需要自行下载。下载三个必需依赖 jar 到解压目录旁的 lib/：

cd /opt/commons/commons-compress-1.28.0
sudo mkdir -p lib
cd lib
sudo curl -fsSLO https://repo1.maven.org/maven2/commons-io/commons-io/2.20.0/commons-io-2.20.0.jar
sudo curl -fsSLO https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.18.0/commons-lang3-3.18.0.jar
sudo curl -fsSLO https://repo1.maven.org/maven2/commons-codec/commons-codec/1.19.0/commons-codec-1.19.0.jar
ls -l

实测回显：

total 1776
-rw-r--r-- 1 root root 374716 commons-codec-1.19.0.jar
-rw-r--r-- 1 root root 563971 commons-io-2.20.0.jar
-rw-r--r-- 1 root root 702952 commons-lang3-3.18.0.jar

写入与方案A相同的 HelloCompress.java（内容见第三章，去掉 package net.quzuo.demo; 首行即可放到任意目录，本章放到 /opt/commons/）。先演示一个必踩的坑——发行包 jar 的清单里虽然声明了 Main-Class: org.apache.commons.compress.archivers.Lister，但直接 java -jar 会失败：

cd /opt/commons
java -jar commons-compress-1.28.0/commons-compress-1.28.0.jar

实测回显：

Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/commons/lang3/ArrayUtils
        at org.apache.commons.compress.archivers.Lister.main(Lister.java:80)
Caused by: java.lang.ClassNotFoundException: org.apache.commons.lang3.ArrayUtils
        at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)
        at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:525)

（输出节选，实测首尾，省略了最后一条调用帧）

原因：java -jar 模式下 -cp 会被忽略，主 jar 之外的所有依赖都找不到。正确做法是用 -cp 同时列出主 jar 与依赖 jar。编译并运行验证程序：

cd /opt/commons
javac -encoding UTF-8 -cp "commons-compress-1.28.0/commons-compress-1.28.0.jar:commons-compress-1.28.0/lib/*" HelloCompress.java
java -Dfile.encoding=UTF-8 -cp ".:commons-compress-1.28.0/commons-compress-1.28.0.jar:commons-compress-1.28.0/lib/*" HelloCompress

实测回显：

zip 读回内容: hello commons compress
commons-compress 版本: 1.28.0
验证通过

注意 Linux 类路径分隔符是冒号 :（Windows 是分号），lib/* 中的星号由 JVM 自己展开，不要加引号以外的 shell 展开。方案B安装完成。

五、方案对比与选型建议

对比项	方案A：Maven 依赖	方案B：发行包手动安装
依赖管理	自动引入 3 个必需依赖与可选依赖	手动逐个下载，漏一个就运行报错
升级成本	改一行版本号重新构建	重新下载、校验、解压、改脚本
离线部署	需内网私服或预下载	天然离线友好
可复现性	pom 锁版本，强	依赖脚本与人为记录
适用场景	一切有构建工具的工程	无 Maven 的跳板机、快速验证、交付现场

选型建议：开发/CI 环境一律方案A；目标机器没有 Maven 或需要临时排查时用方案B；方案B的三个依赖 jar 也建议从中央仓库按 pom 里实测的版本号下载，避免混用其他版本。

六、多版本管理

同一台机器上共存多个 Commons Compress 版本，推荐用「版本目录 + current 符号链接」的方式管理：所有版本平铺在 /opt/commons/ 下，current 指向当前生效版本，切换时只改链接。创建 1.28.0 与 1.26.0 两个版本目录（1.26.0 的主 jar 与依赖从中央仓库按其 pom 实测版本下载）：

cd /opt/commons
sudo mkdir -p commons-compress-1.26.0/lib
sudo curl -fsSL -o commons-compress-1.26.0/lib/commons-compress-1.26.0.jar https://repo1.maven.org/maven2/org/apache/commons/commons-compress/1.26.0/commons-compress-1.26.0.jar
sudo curl -fsSL -o commons-compress-1.26.0/lib/commons-io-2.15.1.jar https://repo1.maven.org/maven2/commons-io/commons-io/2.15.1/commons-io-2.15.1.jar
sudo curl -fsSL -o commons-compress-1.26.0/lib/commons-lang3-3.14.0.jar https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.14.0/commons-lang3-3.14.0.jar
sudo curl -fsSL -o commons-compress-1.26.0/lib/commons-codec-1.16.1.jar https://repo1.maven.org/maven2/commons-codec/commons-codec/1.16.1/commons-codec-1.16.1.jar
sudo ln -sfn commons-compress-1.28.0 current
ls -l

实测回显：

total 128716
drwxr-xr-x 4 root root      4096 Oct 13 08:36 commons-compress-1.28.0
drwxr-xr-x 3 root root      4096 Oct 13 08:37 commons-compress-1.26.0
-rw-r--r-- 1 root root 131792030 Oct 13 08:36 commons-compress-1.28.0-bin.tar.gz
-rw-r--r-- 1 root root       129 Oct 13 08:36 commons-compress-1.28.0-bin.tar.gz.sha512
lrwxrwxrwx 1 root root        23 Oct 13 08:37 current -> commons-compress-1.26.0

用 current 链接编译运行一次验证程序（复用第四章的 HelloCompress.java）：

cd /opt/commons
javac -encoding UTF-8 -cp "current/commons-compress-1.28.0.jar:current/lib/*" HelloCompress.java -d out
java -Dfile.encoding=UTF-8 -cp "out:current/commons-compress-1.28.0.jar:current/lib/*" HelloCompress

实测回显：

== current -> 1.28.0 ==
zip 读回内容: hello commons compress
commons-compress 版本: 1.28.0
验证通过

切换到 1.26.0 再运行（类路径只保留 out 与 current/lib/*，版本号以程序打印为准）：

sudo ln -sfn commons-compress-1.26.0 current
ls -l current
java -Dfile.encoding=UTF-8 -cp "out:current/lib/*" HelloCompress

实测回显：

lrwxrwxrwx 1 root root 23 Oct 13 08:37 current -> commons-compress-1.26.0
zip 读回内容: hello commons compress
commons-compress 版本: 1.26.0
验证通过

程序打印的版本号随符号链接同步变化，证明切换生效。切回最新版：

sudo ln -sfn commons-compress-1.28.0 current

该命令无输出。这套机制的关键约束是：编译和运行都必须引用 current 路径，任何一处写死版本号目录，切换都会失效。

七、卸载

卸载分三部分：手动安装目录、Maven 本地仓库缓存、以及不再需要时的 JDK/Maven 本身。清理手动安装目录与验证产物：

sudo rm -rf /opt/commons

该命令无输出。Maven 本地仓库中 commons-compress 相关缓存约为 1.2MB，一并清理：

du -sh ~/.m2/repository/org/apache/commons/commons-compress
rm -rf ~/.m2/repository/org/apache/commons/commons-compress

实测回显（第一条命令）：

1.2M    /root/.m2/repository/org/apache/commons/commons-compress

若 JDK 17 与 Maven 也不再有他用，可一并卸载（实测会同时移除其独有依赖包）：

sudo apt remove -y openjdk-17-jdk maven
sudo apt autoremove -y
java -version
mvn -v

实测回显（节选，实测首尾）：

Removing maven (3.6.3-5) ...
Removing openjdk-17-jdk:amd64 (17.0.20.1+1-1~22.04) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
bash: /usr/bin/java: No such file or directory
bash: /usr/bin/mvn: No such file or directory

java/mvn 命令消失即卸载完成。注意：~/.m2 中其他项目的依赖缓存不受本次卸载影响，若要彻底清空可再执行 rm -rf ~/.m2。

八、FAQ

Q1：java -jar commons-compress-1.28.0.jar 为什么报 NoClassDefFoundError: org/apache/commons/lang3/ArrayUtils？ 因为 1.28.0 存在必需依赖 commons-lang3、commons-io、commons-codec，而 java -jar 会忽略 -cp。要么改用 java -cp "主jar:lib/*" 主类 的方式（见第四章实测命令），要么把依赖 jar 解包合并进主 jar。该报错本身也说明清单里的 Main-Class（Lister）只有在依赖齐备时才能启动。

Q2：程序里打印的中文在终端显示成问号或乱码怎么办？ 这是 locale 问题而不是库的问题。实测发现未设置 locale 时 mvn -v 会显示 platform encoding: ANSI_X3.4-1968，Java 程序的 System.out 也会退回 ASCII。解决：export LANG=C.UTF-8 写入 ~/.bashrc，或运行时追加 -Dfile.encoding=UTF-8。

Q3：用到 xz/lzma/zstd/brotli 格式时报 NoClassDefFoundError（如 org/tukaani/xz/FilterOptions）怎么处理？ 这些算法依赖可选依赖：org.tukaani:xz（xz/lzma）、com.github.luben:zstd-jni（zstd）、org.brotli:dec（brotli）。1.28.0 的 pom 实测版本分别是 xz 1.10、zstd-jni 1.5.7-4、dec 0.1.2。Maven 项目按坐标补依赖即可；手动部署则把对应 jar 放进 lib/。

Q4：怎么确认 Commons Compress 的运行版本就是我想要的版本？ 用第三章 HelloCompress 里的 ZipArchiveEntry.class.getPackage().getImplementationVersion()，它读取的是 jar 清单里的 Implementation-Version，实测 1.28.0 会打印 commons-compress 版本: 1.28.0。Maven 场景还可以用 mvn dependency:tree 核对解析结果。

Q5：downloads.apache.org 上找不到旧版本怎么办？ 官方只在主下载目录保留最新版，旧版（如 1.26.0）在 https://archive.apache.org/dist/commons/compress/binaries/，实测主站旧版地址返回 404。更推荐直接从 Maven 中央仓库 https://repo1.maven.org/maven2/org/apache/commons/commons-compress/ 按版本取 jar。

九、参考链接

Apache Commons Compress 官方主页：https://commons.apache.org/proper/commons-compress/
1.28.0 发行包下载：https://downloads.apache.org/commons/compress/binaries/commons-compress-1.28.0-bin.tar.gz
发行包 sha512 校验文件：https://downloads.apache.org/commons/compress/binaries/commons-compress-1.28.0-bin.tar.gz.sha512
Maven 中央仓库 1.28.0 目录（含 pom 与各分类 jar）：https://repo1.maven.org/maven2/org/apache/commons/commons-compress/1.28.0/
Apache 归档下载站（历史版本）：https://archive.apache.org/dist/commons/compress/binaries/
官方 javadoc（1.28.0 在线 API 文档）：https://commons.apache.org/proper/commons-compress/javadocs/api-release/index.html
OpenJDK 17 Ubuntu 安装文档：https://packages.ubuntu.com/jammy/openjdk-17-jdk
Maven 安装文档：https://maven.apache.org/install.html