Apache Compress Ant Library 1.5 快速入门与集成示例
Apache Compress Ant Library 1.5 快速入门：澄清 antlib:org.apache.ant.compress 命名空间机制与 31 个任务清单，给出 ant -lib 与 Maven antrun 两条集成路径的完整示例（gzip/bzip2/xz 往返、嵌套 tar→gzip 一步出 tar.gz）、Maven 依赖树实测与五类常见坑，命令回显均实测通过。
Apache Compress Ant Library 1.5 快速入门与集成示例
目标：用 10 分钟跑通 Apache Compress Ant Library 1.5 的第一个压缩脚本，掌握
antlib:org.apache.ant.compress命名空间机制，并完成ant -lib与 Maven antrun 两条集成路径的实测验证；本文全部命令与回显均已在 Ubuntu 22.04 + JDK 17 + Ant 1.10.12 实测通过。
Apache Compress Ant Library（下文按 jar 名简称 ant-compress）是 Apache Ant 项目基于 Commons Compress 封装的 Antlib 扩展库，为构建脚本提供 gzip/bzip2/xz/snappy 等单文件压缩、tar/zip/cpio/ar/7z 等归档格式，以及跨归档读取条目的资源类型。快速入门的路线是：理解 Antlib 命名空间 → 装配 jar 到类路径 → 写一个带 compress: 前缀的构建脚本 → 用回环校验确认压缩无损。安装环节（apt/dnf、官方 bin 包下载校验）已在第 1、2 篇安装指南中实测，本文直接从可用环境出发。
一、环境信息
本节固定快速入门的基线环境，所有命令在此环境实测。
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- JDK：OpenJDK 17.0.20.1（apt 包
openjdk-17-jdk） - 构建工具：Apache Ant 1.10.12（apt 包
ant）、Apache Maven 3.6.3（apt 包maven，依赖树章节另用 Maven 3.9.16 交叉验证） - 组件：Apache Compress Antlib 1.5（
org.apache.ant:ant-compress:1.5，含 commons-compress-1.14.jar、xz-1.6.jar、dec-0.1.2.jar） - jar 获取方式：官方 bin 包
/root/compress-dl/apache-ant-compress-1.5/（下载与 sha512 校验见第 1 篇第五章） - 验证用工作目录：
/root/quickstart
环境确认（实时回显）：
cat /etc/os-release | head -1
ant -version
java -version 2>&1 | head -1
ls /root/compress-dl/apache-ant-compress-1.5/*.jar
PRETTY_NAME="Ubuntu 22.04.5 LTS"
Apache Ant(TM) version 1.10.12 compiled on January 17 1970
openjdk version "17.0.20.1" 2026-08-18
/root/compress-dl/apache-ant-compress-1.5/ant-compress-1.5.jar
/root/compress-dl/apache-ant-compress-1.5/commons-compress-1.14.jar
/root/compress-dl/apache-ant-compress-1.5/dec-0.1.2.jar
/root/compress-dl/apache-ant-compress-1.5/hamcrest-core-1.3.jar
/root/compress-dl/apache-ant-compress-1.5/junit-4.11.jar
/root/compress-dl/apache-ant-compress-1.5/xz-1.6.jar
二、核心概念：Antlib 命名空间与任务清单
本节先讲清这个库「怎么被 Ant 识别」，这是所有集成方式的共同原理。
Antlib 机制：ant-compress 的 jar 内部有一个 org/apache/ant/compress/antlib.xml 资源文件，罗列了全部任务与类型的类名映射。构建脚本只要在 XML 命名空间中声明 xmlns:compress="antlib:org.apache.ant.compress"，Ant 遇到 compress: 前缀的任务就会按该 URI 在运行时类路径上查找并装载对应资源。因此集成的全部要义就是两件事：命名空间写对、jar 进类路径。
jar 内 antlib.xml 的构成实测（实时回显）：
unzip -p /root/compress-dl/apache-ant-compress-1.5/ant-compress-1.5.jar \
org/apache/ant/compress/antlib.xml > /tmp/antlib.xml
head -20 /tmp/antlib.xml
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<antlib>
<taskdef
name="un7z"
classname="org.apache.ant.compress.taskdefs.Un7z"
/>
解析该文件的统计结果（实测）：
taskdef 31 : un7z unar unarj unbrotli uncpio undeflate undump untar unzip ar cpio tar zip bunzip2 gunzip unlz4 unlzma unpack200 unsnappy unxz unz bzip2 deflate gzip pack200 pack200normalize sevenz snappy xz lz4 lzma
typedef 26 : arentry arjentry cpioentry dumpentry sevenzentry tarentry zipentry arfileset arjfileset cpiofileset dumpfileset sevenzfileset tarfileset zipfileset archives brotliresource bzip2resource deflateresource gzipresource lz4resource lzmaresource pack200resource snappyresource xzresource zresource devzero
componentdef 5 : hasusername hasgroupname hasuserid hasgroupid hasmode
速读任务家族：un* 开头的 16 个是解压任务；ar/cpio/tar/zip/sevenz 是 5 种归档任务；gzip/bzip2/deflate/lz4/lzma/snappy/xz/pack200 等 10 个是单文件流压缩任务（pack200 系列在 JDK 17 不可用，见第八章）。快速入门只动用其中 8 个任务，其余在《常用 API 与任务详解》篇逐一实测。
三、10 分钟最小可运行：ant -lib 方式
本节用官方 jar + 一个 6 任务的脚本跑通第一个压缩往返，是理解库工作方式的最佳起点。
3.1 编写构建脚本
创建工作目录与脚本（/root/quickstart/build-min.xml，完整内容）：
mkdir -p /root/quickstart && cd /root/quickstart
<?xml version="1.0" encoding="UTF-8"?>
<project name="compress-min" default="all" basedir="." xmlns:compress="antlib:org.apache.ant.compress">
<target name="all">
<mkdir dir="work"/>
<echo file="work/app.log">2026-10-15 10:00:00 INFO service started${line.separator}2026-10-15 10:05:00 INFO health check ok</echo>
<compress:gzip src="work/app.log" destfile="work/app.log.gz"/>
<compress:gunzip src="work/app.log.gz" dest="work/app-restored.log"/>
<compress:bzip2 src="work/app.log" destfile="work/app.log.bz2"/>
<compress:bunzip2 src="work/app.log.bz2" dest="work/app-restored-bz2.log"/>
<compress:xz src="work/app.log" destfile="work/app.log.xz"/>
<compress:unxz src="work/app.log.xz" dest="work/app-restored-xz.log"/>
<checksum file="work/app.log" property="orig.md5"/>
<checksum file="work/app-restored.log" property="gzip.md5"/>
<checksum file="work/app-restored-bz2.log" property="bz2.md5"/>
<checksum file="work/app-restored-xz.log" property="xz.md5"/>
<echo>orig=${orig.md5} gzip=${gzip.md5} bz2=${bz2.md5} xz=${xz.md5}</echo>
</target>
</project>
要点：<project> 上的 xmlns:compress="antlib:org.apache.ant.compress" 是命名空间声明；单文件压缩任务用 src（输入文件）+ destfile（输出文件），解压任务用 src + dest（输出文件）；末尾 4 个 <checksum> 计算原文件与三份解压结果的 MD5 用于无损比对。
3.2 执行与验证
cd /root/quickstart && ant -lib /root/compress-dl/apache-ant-compress-1.5 -f build-min.xml
all:
[mkdir] Created dir: /root/quickstart/work
[compress:gzip] Building: app.log.gz
[compress:gunzip] Expanding /root/quickstart/work/app.log.gz to /root/quickstart/work/app-restored.log
[compress:bzip2] Building: app.log.bz2
[compress:bunzip2] Expanding /root/quickstart/work/app.log.bz2 to /root/quickstart/work/app-restored-bz2.log
[compress:xz] Building: app.log.xz
[compress:unxz] Expanding /root/quickstart/work/app.log.xz to /root/quickstart/work/app-restored-xz.log
[echo] orig=2d9aea616572147c20ac38a68841cfd0 gzip=2d9aea616572147c20ac38a68841cfd0 bz2=2d9aea616572147c20ac38a68841cfd0 xz=2d9aea616572147c20ac38a68841cfd0
BUILD SUCCESSFUL
Total time: 1 second
ls -l work/
total 20
-rw-r--r-- 1 root root 81 Oct 15 06:44 app-restored-bz2.log
-rw-r--r-- 1 root root 81 Oct 15 06:44 app-restored-xz.log
-rw-r--r-- 1 root root 81 Oct 15 06:44 app-restored.log
-rw-r--r-- 1 root root 81 Oct 15 06:44 app.log
-rw-r--r-- 1 root root 99 Oct 15 06:44 app.log.bz2
-rw-r--r-- 1 root root 79 Oct 15 06:44 app.log.gz
-rw-r--r-- 1 root root 124 Oct 15 06:44 app.log.xz
验证点三条：BUILD SUCCESSFUL；四个 MD5 完全一致（2d9aea616572147c20ac38a68841cfd0）证明三种格式往返无损；产物为标准格式（81 字节的小文件经压缩后 bz2 99 字节、xz 124 字节反而变大是正常现象——压缩头部开销在小文件上占比高，gzip 压缩头部 20 字节足够短所以略小）。用系统工具抽查互通（实测）：
gzip -t work/app.log.gz && bzip2 -t work/app.log.bz2 && xz -t work/app.log.xz && echo "系统工具校验全部通过"
系统工具校验全部通过
💡 技术拓展：
src/destfile与核心 Ant<gzip>的src/destfile语义一致，但 Antlib 版额外提供level（压缩级别）与framed（xz 帧模式）等 Commons Compress 特有参数，且同名任务不会冲突——Antlib 任务只在自己的命名空间下可见，这是它与核心 Ant 共存的设计基础。
四、Maven 工程集成（antrun 插件）
本节把同一套任务搬进 Maven 生命周期，适合 Java 工程在打包阶段生成发布压缩包。
4.1 编写 pom.xml
创建 /root/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>demo</groupId>
<artifactId>compress-antlib-demo</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.release>17</maven.compiler.release>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>3.1.0</version>
<dependencies>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-compress</artifactId>
<version>1.5</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>compress-logs</id>
<phase>generate-resources</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<target name="archive-logs" xmlns:compress="antlib:org.apache.ant.compress">
<mkdir dir="${project.basedir}/work"/>
<echo file="${project.basedir}/work/app.log">2026-10-15 10:00:00 INFO service started${line.separator}2026-10-15 10:05:00 INFO health check ok</echo>
<compress:gzip src="${project.basedir}/work/app.log" destfile="${project.basedir}/work/app.log.gz"/>
<compress:bzip2 src="${project.basedir}/work/app.log" destfile="${project.basedir}/work/app.log.bz2"/>
<compress:gunzip src="${project.basedir}/work/app.log.gz" dest="${project.basedir}/work/app-restored.log"/>
<checksum file="${project.basedir}/work/app.log" property="orig.md5"/>
<checksum file="${project.basedir}/work/app-restored.log" property="restored.md5"/>
<echo>orig=${orig.md5}</echo>
<echo>restored=${restored.md5}</echo>
</target>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
两个易错点：ant-compress 必须声明在 maven-antrun-plugin 的 <dependencies> 里（插件依赖才会进入插件执行 Ant 时的类路径），写进工程顶层 <dependencies> 无效；命名空间声明写在 antrun 的 <target> 元素上。
4.2 执行与验证
cd /root/compress-demo && mvn -B antrun:run@compress-logs
[INFO] --- maven-antrun-plugin:3.1.0:run (compress-logs) @ compress-antlib-demo ---
[INFO] Executing tasks
[INFO] [compress:gzip] Building: app.log.gz
[INFO] [compress:bzip2] Building: app.log.bz2
[INFO] [compress:gunzip] Expanding /root/compress-demo/work/app.log.gz to /root/compress-demo/work/app-restored.log
[WARNING] [echo] orig=2d9aea616572147c20ac38a68841cfd0
[WARNING] [echo] restored=2d9aea616572147c20ac38a68841cfd0
[INFO] Executed tasks
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.828 s
[INFO] Finished at: 2026-10-15T06:37:53Z
[INFO] ------------------------------------------------------------------------
验证点：BUILD SUCCESS、MD5 一致。[WARNING] 前缀是 antrun 3.x 转发 Ant 输出的固定风格，非错误。压缩产物在 work/ 目录，Maven 构建（如 mvn package）也会自动执行该目标（绑定在 generate-resources 阶段）。
五、Maven 坐标与传递依赖实测
本节确认依赖清单，评估与现有工程的兼容面。ant-compress 声明为工程依赖后，用 Maven 3.9.16 看完整依赖树：
/opt/demo-dep/pom.xml 的依赖片段：
<dependencies>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-compress</artifactId>
<version>1.5</version>
</dependency>
</dependencies>
cd /opt/demo-dep && mvn -B dependency:tree
[INFO] --- dependency:3.7.0:tree (default-cli) @ compress-dep-demo ---
[INFO] demo:compress-dep-demo:jar:1.0.0
[INFO] \- org.apache.ant:ant-compress:jar:1.5:compile
[INFO] +- org.apache.ant:ant:jar:1.10.18:compile
[INFO] | \- org.apache.ant:ant-launcher:jar:1.10.18:compile
[INFO] +- org.apache.commons:commons-compress:jar:1.14:compile
[INFO] +- org.tukaani:xz:jar:1.6:compile
[INFO] \- org.brotli:dec:jar:0.1.2:compile
依赖树解读：引入 ant-compress 1.5 一共带来 5 个传递 jar——Ant 本体（pom 声明版本区间 [1.8.0,)，Maven 自动解析到当时最新的 1.10.18）、Commons Compress 1.14（压缩引擎）、xz 1.6（xz/lzma 格式）、Brotli dec 0.1.2（unbrotli 解码）。落地提示：如果你的工程已经依赖 commons-compress 的更高版本（如 1.26+），依赖仲裁会替换掉 1.14，ant-compress 的核心任务仍可工作，但涉及低版本行为的边缘任务（如 cpio 细节）需回归测试。
💡 技术拓展：ant-compress 与「直接用 Commons Compress 写 Java 代码」的选择——前者声明式、零编码、Ant 增量判定内建，但功能冻结在 Commons Compress 1.14 能力；后者随引擎升级获得新格式与新修复，但要自己写代码。构建脚本场景选前者，应用内压缩选后者。
六、组合示例：一步产出 tar.gz
本节演示 Antlib 的招牌能力——归档任务嵌套进压缩任务，避免「先 tar 再 gzip」的中间文件。/root/quickstart/build-onestep.xml（完整内容）：
<?xml version="1.0" encoding="UTF-8"?>
<project name="compress-onestep" default="all" basedir="." xmlns:compress="antlib:org.apache.ant.compress">
<target name="all">
<mkdir dir="logs"/>
<echo file="logs/app.log">2026-10-15 10:00:00 INFO service started</echo>
<echo file="logs/db.log">2026-10-15 10:00:01 INFO db connected</echo>
<compress:gzip destfile="logs.tar.gz">
<compress:tar>
<fileset dir="logs" includes="*.log"/>
</compress:tar>
</compress:gzip>
</target>
</project>
写法要点：<compress:gzip> 不写 src，而是嵌套一个 <compress:tar> 作为数据源；tar 的 <fileset> 指定归档内容；gzip 只写 destfile——不能再给 gzip 添加嵌套 <dest>，否则报错（见第八章坑 2）。执行：
cd /root/quickstart && ant -lib /root/compress-dl/apache-ant-compress-1.5 -f build-onestep.xml
all:
[mkdir] Created dir: /root/quickstart/logs
[compress:gzip] Building: logs.tar.gz
BUILD SUCCESSFUL
Total time: 0 seconds
用系统工具验证产物结构与内容（实测）：
tar -tzf logs.tar.gz
app.log
db.log
tar -xzf logs.tar.gz -O app.log
2026-10-15 10:00:00 INFO service started
验证点：标准 tar -tzf 能列出条目、能读回内容，说明一步产出的 tar.gz 与系统工具完全互通。同理 <compress:bzip2>、<compress:xz> 都可以这样嵌套归档任务，产出 tar.bz2/tar.xz。
七、验证清单与预期结果
快速入门完成后，以下 5 项应全部满足（每项的实测依据已在前文给出）：
| # | 验证项 | 命令 | 预期结果 |
|---|---|---|---|
| 1 | 任务解析 | ant -lib <目录> -f build-min.xml | BUILD SUCCESSFUL，无 The name is undefined |
| 2 | 三格式无损往返 | 脚本内 4 个 <checksum> MD5 | 四值完全一致 |
| 3 | 产物格式标准 | gzip -t / bzip2 -t / xz -t | 全部通过 |
| 4 | Maven 集成 | mvn -B antrun:run@compress-logs | BUILD SUCCESS，MD5 一致 |
| 5 | 一步 tar.gz | tar -tzf logs.tar.gz | 列出全部条目且内容可读回 |
八、常见坑与排障
本节收录快速入门阶段实测踩到的 5 个坑，均给出真实报错与解法。
坑 1：failed to create task or type antlib:org.apache.ant.compress:gzip / Cause: The name is undefined
命名空间 URI 正确但类路径上没有 jar。解法：ant -lib <jar 目录>；或把 jar 拷入 ANT_HOME/lib；或脚本内 <taskdef uri="antlib:org.apache.ant.compress" resource="org/apache/ant/compress/antlib.xml" classpath="..."/>。若 URI 本身写错（如把 org.apache.ant.compress 写成 org.apache.commons.compress），报错会出现 URI 解析问题——URI 与 jar 内资源路径必须逐字符对应。
坑 2：Can only have one destination resource
一步 tar.gz 时既写了 destfile 又写了嵌套 <dest>（实测报错原文）。gzip 的输出来源只能有一个：要么 destfile/dest 属性，要么嵌套 <dest> 资源，二者不可兼得。
坑 3：No sources, nothing to do（BUILD FAILED）
<compress:zip whenempty="fail"> 的 fileset 匹配到 0 个文件时默认失败（实测报错原文）。明确不想报错就写 whenempty="skip"，任务静默跳过且不生成归档。
坑 4：ClassNotFoundException: java.util.jar.Pack200
JDK 17 上执行 <pack200>/<unpack200>/<pack200normalize> 必然报错——Pack200 API 已从 JDK 14 移除，ant-compress 1.5 未跟进（实测复现，完整栈见《常用 API 与任务详解》篇）。解法：pack200 目标放到 JDK 8–13 环境执行，或放弃 pack200。
坑 5：Maven 里 compress: 任务全部无法解析
ant-compress 写在了工程顶层 <dependencies> 而非 maven-antrun-plugin 的 <dependencies>。插件执行 Ant 时用的是插件自身的类路径，把依赖挪到插件里即可（见 4.1 节）。
九、参考链接
- Apache Compress Antlib 官方主页与手册：https://ant.apache.org/antlibs/compress/
- Maven 中央仓库坐标页：https://repo1.maven.org/maven2/org/apache/ant/ant-compress/
- Ant 手册 Antlib 机制：https://ant.apache.org/manual/antlib.html
- Apache Commons Compress 项目：https://commons.apache.org/proper/commons-compress/
- 系列前篇：《Ubuntu 22.04 安装 Apache Compress Ant Library 指南》《CentOS 8 安装 Apache Compress Ant Library 指南》