Ubuntu 22.04 安装 Apache Commons Codec 指南

在 Ubuntu 22.04 从零安装 Commons Codec 1.23.0：安装 JDK 17 与 Maven，Maven 依赖与官方发行包双方案、sha512 校验、最小验证代码、多版本管理与卸载，命令与回显全部实测。

Apache Commons CodecApache Commons Codec2026/10/13

Ubuntu 22.04 安装 Apache Commons Codec 指南

目标：在 Ubuntu 22.04 服务器上从零搭建可编译、可运行 Apache Commons Codec 的 Java 环境，覆盖「Maven 依赖」与「官方发行包手动安装」两种方案、sha512 完整性校验、最小验证代码、多版本管理与卸载，已在 Ubuntu 22.04（OpenJDK 17、Maven 3.6.3）实测通过。

一、环境信息

本篇所有命令与回显均在以下环境中实测采集，复现时请保持相近版本：

  • 操作系统：Ubuntu 22.04（jammy），x86_64
  • JDK：OpenJDK 17.0.20.1（openjdk-17-jdk-headless，apt 官方仓库）
  • 构建工具：Apache Maven 3.6.3（maven，apt 官方仓库）
  • 组件版本：Apache Commons Codec 1.23.0（downloads.apache.org 当前最新版，2026-10 实测）
  • 对照工具：OpenSSL 3.0.2、coreutils sha512sum/md5sum（用于摘要互验）
  • 实验目录：/opt/lab（方案 A 工程 /opt/lab/codec-maven，方案 B 目录 /opt/lab/codec-manual）
  • 执行用户：root

二、前置条件

本节确认系统版本、网络可达性与基础工具，保证后续下载与依赖解析能顺利完成。

2.1 确认系统与网络

先确认操作系统版本与架构，再确认能访问 Apache 官方下载站与 Maven 中央仓库：

cat /etc/os-release | head -2

回显（实测）：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

uname -m

回显（实测）：

x86_64

curl -sI https://downloads.apache.org/commons/codec/ | head -3

回显（实测）：

HTTP/1.1 200 OK
Server: Apache
Content-Type: text/html;charset=UTF-8

两条探测命令返回 x86_64 与 HTTP/1.1 200 OK，说明系统为 64 位且官方下载站可达，可以继续安装。

2.2 安装基础工具

安装 curl 与 wget，用于后续下载发行包：

apt-get update -qq

回显（实测，-qq 静默模式成功无输出）：

DEBIAN_FRONTEND=noninteractive apt-get install -y curl wget

输出节选（实测首尾）：

Reading package lists...
Building dependency tree...
Reading state information...
The following NEW packages will be installed:
  curl wget
0 upgraded, 2 newly installed, 0 to remove and 1 not upgraded.
Need to get 533 kB of archives.
After this operation, 1407 kB of additional disk space will be used.
Unpacking curl (7.81.0-1ubuntu1.29) ...
Setting up wget (1.21.2-2ubuntu1.5) ...
Setting up curl (7.81.0-1ubuntu1.29) ...

验证工具已就位：

wget --version | head -1

回显（实测）：

GNU Wget 1.21.2 built on linux-gnu.

wget 版本号正常输出，基础工具安装完成。

三、版本选型说明

Commons Codec 是纯 Java 库，没有独立进程，选型核心是「库版本 + JDK 版本」的匹配。先实测确认官方当前最新版本号：

curl -s https://downloads.apache.org/commons/codec/binaries/ | grep -oE 'commons-codec-[0-9.]+-bin\.tar\.gz' | sort -u

回显（实测）：

commons-codec-1.23.0-bin.tar.gz
commons-codec-1.23.0-bin.tar.gz.sha512

版本与 JDK 要求对照如下（1.23.0 与 1.18.0 的 class 文件 major version 均实测为 52，即 Java 8 字节码）：

组件版本JDK 要求获取渠道说明
Commons Codec1.23.0Java 8+downloads.apache.org（官方最新）本文采用，sha512 实测校验通过
Commons Codec1.18.0Java 8+Maven 中央仓库 / archive.apache.org旧版本，存量工程常见
JDKOpenJDK 17.0.20.1—Ubuntu 官方 apt 仓库运行与编译库示例均正常
Maven3.6.3Java 8+Ubuntu 官方 apt 仓库方案 A 依赖解析使用

关键差异与选型建议：新工程直接用官方最新 1.23.0（本文实测版本）；维护旧工程时保持其原有版本即可，1.18.0 仍可从中央仓库与 archive 站正常获取（实测 HTTP 200）。JDK 侧只需满足 Java 8 及以上，本文用 OpenJDK 17 验证。

四、安装方案 A：Maven 依赖安装（在线，推荐）

方案 A 通过 Maven 中央仓库自动拉取 commons-codec jar，依赖清单写入 pom.xml，适合所有使用 Maven 的工程。本节完成 JDK/Maven 安装、工程创建、依赖解析与最小验证。

4.1 安装 JDK 17 与 Maven

一条命令装齐编译运行所需组件：

DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk-headless maven

输出节选（实测首尾）：

debconf: delaying package configuration, since apt-utils is not installed
Selecting previously unselected package openssl.
(Reading database ... 5230 files and directories currently installed.)
Preparing to unpack .../00-openssl_3.0.2-0ubuntu1.30_amd64.deb ...
Running hooks in /etc/ca-certificates/update.d...

done.

分别验证 JDK 与 Maven：

java -version

回显（实测）：

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)

mvn -version

回显（实测）：

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_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

java -version 与 mvn -version 均正常回显，且 Maven 使用的 Java 版本为 17.0.20.1，说明两者链路一致。注意 platform encoding 显示 ANSI_X3.4-1968，这在第八节 FAQ Q1 中会处理，避免中文乱码。

4.2 创建工程与 pom.xml

创建 Maven 工程骨架并写入最小 pom：

mkdir -p /opt/lab/codec-maven/src/main/java/demo

回显（实测，无输出即成功）：

cat > /opt/lab/codec-maven/pom.xml <<'EOF'
<?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>codec-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <properties>
    <maven.compiler.source>8</maven.compiler.source>
    <maven.compiler.target>8</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>commons-codec</groupId>
      <artifactId>commons-codec</artifactId>
      <version>1.23.0</version>
    </dependency>
  </dependencies>
</project>
EOF

回显（实测，无输出即成功）：

pom 逐项说明：groupId/artifactId/version 标识本示例工程；maven.compiler.source/target 设为 8，与 Codec 1.23.0 的最低 Java 8 要求对齐；project.build.sourceEncoding 固定 UTF-8，保证源码里的中文字符串按 UTF-8 编译；dependencies 中的 commons-codec:commons-codec:1.23.0 就是本篇的主角，Maven 首次编译时会自动从中央仓库下载该 jar 及其传递依赖（Codec 1.23.0 无传递依赖，单 jar 即可用）。

4.3 编译并解析依赖

首次编译触发依赖下载：

cd /opt/lab/codec-maven && mvn compile

输出节选（实测首尾）：

[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< demo:codec-demo >---------------------------
[INFO] Building codec-demo 1.0.0
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ codec-demo ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ codec-demo ---
[INFO] Nothing to compile - all classes are up to date
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

核对 jar 已落入本地仓库：

ls ~/.m2/repository/commons-codec/commons-codec/1.23.0/

回显（实测）：

commons-codec-1.23.0.jar  commons-codec-1.23.0.pom  _remote.repositories

BUILD SUCCESS 加本地仓库中出现 commons-codec-1.23.0.jar，依赖解析完成。

4.4 最小验证代码

写一个仅依赖 Codec 的验证类，覆盖「编码 + 解码」闭环：

cat > /opt/lab/codec-maven/src/main/java/demo/HelloCodec.java <<'EOF'
package demo;

import java.nio.charset.StandardCharsets;
import org.apache.commons.codec.binary.Base64;

public class HelloCodec {
    public static void main(String[] args) {
        String text = "Apache Commons Codec";
        String encoded = Base64.encodeBase64String(text.getBytes(StandardCharsets.UTF_8));
        System.out.println("encoded: " + encoded);
        System.out.println("decoded: " + new String(Base64.decodeBase64(encoded), StandardCharsets.UTF_8));
    }
}
EOF

回显（实测，无输出即成功）：

💡 技术拓展：Base64 并非只有一种形态，常见变体对比——

变体字母表差异换行补位符典型场景
标准（RFC 4648）A-Z a-z 0-9 + /否=HTTP Basic、常规二进制转文本
URL-safe- _ 替换 + /否无（URL-safe 编码不补）URL 参数、Cookie、JWT
MIME（RFC 2045）同标准每 76 字符 CRLF=邮件正文附件

本节验证代码采用「标准」变体（encodeBase64String），理由是最通用、与命令行 openssl base64 结果可直接互验；其余变体在《Apache Commons Codec 快速入门与集成示例》与《Apache Commons Codec 配置参数详解》中均有实测展开。

编译并运行验证类：

cd /opt/lab/codec-maven && mvn -q compile 2>/dev/null; java -cp target/classes:~/.m2/repository/commons-codec/commons-codec/1.23.0/commons-codec-1.23.0.jar demo.HelloCodec

回显（实测）：

encoded: QXBhY2hlIENvbW1vbnMgQ29kZWM=
decoded: Apache Commons Codec

编码结果与解码还原完全对应，方案 A 安装验证通过。

五、安装方案 B：官方发行包手动安装（下载 jar + java -cp 直跑）

方案 B 不依赖 Maven：从官方站点下载发行包，校验 sha512 后解压取 jar，用 javac/java -cp 直接编译运行，适合无 Maven 的服务器或离线环境。

5.1 下载发行包与校验文件

mkdir -p /opt/lab/codec-manual && cd /opt/lab/codec-manual && wget -q https://downloads.apache.org/commons/codec/binaries/commons-codec-1.23.0-bin.tar.gz && wget -q https://downloads.apache.org/commons/codec/binaries/commons-codec-1.23.0-bin.tar.gz.sha512 && ls -l

回显（实测）：

total 4244
-rw-r--r-- 1 root root 4329713 Oct 11 15:34 commons-codec-1.23.0-bin.tar.gz
-rw-r--r-- 1 root root     129 Oct 11 15:34 commons-codec-1.23.0-bin.tar.gz.sha512

两个文件均已下载，主包 4329713 字节。

5.2 sha512 完整性校验

官方 .sha512 文件内容为裸哈希值，先查看再校验：

cat commons-codec-1.23.0-bin.tar.gz.sha512

回显（实测）：

34a8cb4bafd3bb56fed56f1609b9c45f8cc25c31d7fdc9fca8df498d9b73efb4b8636b5f8a1c7d6439cca200b35a991867287b4ca14159af8cef4ca56a04559a

💡 技术拓展：摘要算法不止一种，常见选择对比——

算法摘要长度十六进制长度碰撞抗性现状适用场景
MD5128 位32 字符已可构造碰撞非安全场景的快速校验、兼容旧协议
SHA-1160 位40 字符已被实质攻破遗留系统兼容（如 git 对象）
SHA-256256 位64 字符目前安全通用完整性校验、数字签名
SHA-512512 位128 字符目前安全高安全要求、大文件校验

Apache 官方发行包现提供 .sha512 校验文件，本文遵循官方做法采用 SHA-512；Codec 库本身对以上算法均封装了 DigestUtils 方法（见《Apache Commons Codec 快速入门与集成示例》）。

用 sha512sum 完成校验（把裸哈希拼成「哈希 + 文件名」标准格式交给 sha512sum -c）：

cd /opt/lab/codec-manual && printf '%s  %s\n' "$(cat commons-codec-1.23.0-bin.tar.gz.sha512)" commons-codec-1.23.0-bin.tar.gz | sha512sum -c -

回显（实测）：

commons-codec-1.23.0-bin.tar.gz: OK

输出 OK 即校验通过；若输出 FAILED 说明下载不完整或被篡改，必须重新下载（真实失败样例见第八节 FAQ Q4）。

5.3 解压并取出 jar

cd /opt/lab/codec-manual && tar xzf commons-codec-1.23.0-bin.tar.gz && ls commons-codec-1.23.0/ && cp commons-codec-1.23.0/commons-codec-1.23.0.jar lib/ 2>/dev/null || (mkdir -p lib && cp commons-codec-1.23.0/commons-codec-1.23.0.jar lib/)

回显（实测，目录内容）：

LICENSE.txt
NOTICE.txt
RELEASE-NOTES.txt
apidocs
commons-codec-1.23.0-javadoc.jar
commons-codec-1.23.0-sources.jar
commons-codec-1.23.0-test-sources.jar
commons-codec-1.23.0-tests.jar
commons-codec-1.23.0.jar

ls -l /opt/lab/codec-manual/lib/

回显（实测）：

total 432
-rw-r--r-- 1 root root 440773 Oct 13 03:46 commons-codec-1.23.0.jar

发行包内含主 jar（440773 字节）、sources、javadoc 与测试包；运行只需要 commons-codec-1.23.0.jar，已复制到 lib/。

5.4 javac/java -cp 直接编译运行

沿用 4.4 节同样的验证代码（复制或重写均可），不经 Maven 直接编译：

mkdir -p /opt/lab/codec-manual/classes /opt/lab/codec-manual/src && cat > /opt/lab/codec-manual/src/HelloCodec.java <<'EOF'
import java.nio.charset.StandardCharsets;
import org.apache.commons.codec.binary.Base64;

public class HelloCodec {
    public static void main(String[] args) {
        String text = "Apache Commons Codec";
        String encoded = Base64.encodeBase64String(text.getBytes(StandardCharsets.UTF_8));
        System.out.println("encoded: " + encoded);
        System.out.println("decoded: " + new String(Base64.decodeBase64(encoded), StandardCharsets.UTF_8));
    }
}
EOF
cd /opt/lab/codec-manual && javac -encoding UTF-8 -cp lib/commons-codec-1.23.0.jar -d classes src/HelloCodec.java && java -cp classes:lib/commons-codec-1.23.0.jar HelloCodec

回显（实测）：

encoded: QXBhY2hlIENvbW1vbnMgQ29kZWM=
decoded: Apache Commons Codec

与方案 A 的运行结果完全一致，方案 B 验证通过。

5.5 核对 jar 内容与版本清单

用 jar tf 确认包内结构与 MANIFEST 中的版本号：

cd /opt/lab/codec-manual && jar tf lib/commons-codec-1.23.0.jar | wc -l

回显（实测）：

312

cd /tmp && jar xf /opt/lab/codec-manual/lib/commons-codec-1.23.0.jar META-INF/MANIFEST.MF && grep -E "Specification-Version|Implementation-Version" META-INF/MANIFEST.MF

回显（实测）：

Specification-Version: 1.23
Implementation-Version: 1.23.0

包内 312 个条目，MANIFEST.MF 确认 Implementation-Version 为 1.23.0，与下载意图一致。

六、方案对比与选择建议

维度方案 A：Maven 依赖方案 B：官方发行包手动安装
依赖来源Maven 中央仓库（自动）downloads.apache.org（手动）
是否需联网需（首次拉取依赖）需下载一次，之后可离线分发
版本管理改 pom.xml 版本号即可手动下载对应版本 jar、自行管理目录
完整性校验依赖 Maven 仓库校验机制需自行 sha512sum -c（官方提供 .sha512）
附带产物仅主 jar主 jar + sources + javadoc + apidocs
适用场景常规 Maven/SBT/Gradle 工程无构建工具的服务器、离线内网、源码研读

关键差异与选型建议：工程内使用一律选方案 A，版本升级只需改一个版本号；临时跑个验证、内网离线机器、或需要 sources/javadoc 离线查阅，用方案 B。两方案可以共存，本文环境即同时具备。

七、多版本管理与升级、降级

7.1 Maven 方式的多版本共存

Maven 本地仓库按「groupId/artifactId/version」目录存放，多版本天然共存。实测拉取旧版本 1.18.0：

cd /opt/lab/codec-maven && mvn -q dependency:get -Dartifact=commons-codec:commons-codec:1.18.0 && ls ~/.m2/repository/commons-codec/commons-codec/

回显（实测）：

1.18.0
1.23.0

升级或降级只需修改 pom.xml 中 dependency 的 version 值（如 1.23.0 改为 1.18.0），重新 mvn compile 即生效；用 mvn dependency:list 可核对实际解析到的版本。

7.2 手动方式的多版本共存

历史版本从 Apache 归档站获取（实测 1.18.0 仍可下载）：

curl -sI https://archive.apache.org/dist/commons/codec/binaries/commons-codec-1.18.0-bin.tar.gz | head -3

回显（实测）：

HTTP/1.1 200 OK
Date: Tue, 13 Oct 2026 03:55:07 GMT
Server: Apache

把不同版本的 jar 放入不同目录（如 lib/1.18.0/、lib/1.23.0/），运行时用 -cp 指定其一即可切换，建议在类路径中只保留一个 codec 版本，避免类冲突。

7.3 多 JDK 共存与切换

本机实测同时存在 OpenJDK 11 与 17：

update-alternatives --list java

回显（实测）：

/usr/lib/jvm/java-11-openjdk-amd64/bin/java
/usr/lib/jvm/java-17-openjdk-amd64/bin/java

切换默认 JDK：

update-alternatives --set java /usr/lib/jvm/java-17-openjdk-amd64/bin/java && java -version | head -1

回显（实测）：

openjdk version "17.0.20.1" 2026-08-18

Codec 1.23.0 在 Java 8 及以上均可运行，切换 JDK 后建议重跑 4.4 节的 HelloCodec 做回归验证。

八、常见问题（FAQ）

Q1：程序里的中文输出变成 ?（问号）怎么办？ 现象：mvn -version 显示 platform encoding: ANSI_X3.4-1968，Java 程序打印中文时输出 ?。这是系统 locale 未配置为 UTF-8 所致（本文实测环境默认 locale 即为 C/POSIX）。解决：运行 Java 前设置环境变量 LANG=C.UTF-8，例如 LANG=C.UTF-8 java -cp classes:lib/commons-codec-1.23.0.jar HelloCodec。实测设置后中文正常输出（本篇 5.4 节回显即在该设置下采集）。同时源码编译务必带 -encoding UTF-8（javac）或 pom 中 project.build.sourceEncoding=UTF-8（Maven）。

Q2：运行时报 NoSuchMethodError 或 ClassNotFoundException，怎么排查？ 通常是类路径上残留了另一个版本的 codec jar。排查两步：第一，echo $CLASSPATH 与运行命令的 -cp 检查是否混入旧 jar；第二，对实际加载的 jar 查看版本（见 5.5 节）：

cd /tmp && jar xf ~/.m2/repository/commons-codec/commons-codec/1.23.0/commons-codec-1.23.0.jar META-INF/MANIFEST.MF && grep Implementation-Version META-INF/MANIFEST.MF

回显（实测）：

Implementation-Version: 1.23.0

确认版本后，让 -cp 中只保留一个版本即可。

Q3：Maven 拉取依赖很慢或超时怎么办？ 先确认网络可达中央仓库：

curl -sI https://repo1.maven.org/maven2/commons-codec/commons-codec/1.23.0/commons-codec-1.23.0.jar | head -1

回显（实测）：

HTTP/1.1 200 OK

返回 200 说明链路正常，慢多为带宽问题，可重试或改用国内下载源：编辑 ~/.m2/settings.xml 的 <mirrors> 段添加阿里云公共仓库 https://maven.aliyun.com/repository/public（<id> 取 aliyun、<mirrorOf> 取 central），保存后重新 mvn compile。离线机器直接改走方案 B。

Q4：sha512 校验输出 FAILED 怎么处理？ 真实失败样例（把下载包追加一个字节后校验）：

cd /opt/lab/codec-manual && cp commons-codec-1.23.0-bin.tar.gz bad.tar.gz && printf X >> bad.tar.gz && printf '%s  %s\n' "$(cat commons-codec-1.23.0-bin.tar.gz.sha512)" bad.tar.gz | sha512sum -c -

回显（实测）：

bad.tar.gz: FAILED
sha512sum: WARNING: 1 computed checksum did NOT match

出现 FAILED 说明文件内容与官方哈希不一致：先删除坏包，重新用 wget 下载；若反复失败，检查下载链路中是否存在代理改写或磁盘空间不足。校验通过（输出 OK）前不要使用该发行包。

Q5：无 root 权限能装吗？ 可以。方案 B 完全不需要 root：发行包解压到用户目录（如 ~/opt/codec-manual），javac/java 用已安装的任意 JDK（Java 8+）即可；JDK 本身也可下载.tar.gz 版解压到用户目录后配置 PATH。方案 A 需要能写 ~/.m2，同样不要求 root，只是 apt-get 安装 Maven/JDK 那一步需要管理员权限（用户目录解压 JDK + Maven 同样可行）。

九、卸载与清理

按「工程 → 本地仓库 → 系统包」顺序清理。

删除实验工程与发行包目录：

rm -rf /opt/lab/codec-maven /opt/lab/codec-manual

回显（实测，无输出即成功）：

清理 Maven 本地仓库中的 codec 缓存：

rm -rf ~/.m2/repository/commons-codec && ls ~/.m2/repository/commons-codec

回显（实测）：

ls: cannot access '/root/.m2/repository/commons-codec': No such file or directory

卸载系统级 Maven 与 JDK：

DEBIAN_FRONTEND=noninteractive apt-get purge -y maven openjdk-17-jdk-headless openjdk-17-jre-headless && apt-get autoremove -y

输出节选（实测首尾）：

Removing maven (3.6.3-5) ...
Removing openjdk-17-jdk-headless:amd64 (17.0.20.1+1-1~22.04) ...
Removing maven (3.6.3-5) ...
Removing default-jre-headless (2:1.11-72build2) ...
Removing libapache-pom-java (18-1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

验证卸载结果：

java -version 2>&1; mvn -version 2>&1

回显（实测）：

bash: line 1: java: command not found
bash: line 1: mvn: command not found

两条命令均报 command not found，卸载完成。

十、参考链接

  1. Apache Commons Codec 官方下载：https://downloads.apache.org/commons/codec/
  2. Apache Commons Codec 项目主页：https://commons.apache.org/proper/commons-codec/
  3. Maven 中央仓库 commons-codec：https://mvnrepository.com/artifact/commons-codec/commons-codec
  4. Apache 归档站（历史版本）：https://archive.apache.org/dist/commons/codec/
  5. RFC 4648（Base64/Base32 标准）：https://datatracker.ietf.org/doc/html/rfc4648