Ubuntu 22.04 安装 Apache Commons DbUtils 指南

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

一、环境信息

本章先确认操作系统版本，再安装 JDK 17 与 Maven，为后续获取 Commons DbUtils 做准备。Commons DbUtils 1.8.1 编译目标为 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 与 curl（约 1~2 分钟，取决于网络）：

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

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

Reading package lists...
Building dependency tree...
Reading state information...
The following additional packages will be installed:
  adwaita-icon-theme alsa-topology-conf alsa-ucm-conf at-spi2-core
  ca-certificates-java dbus-user-session dconf-gsettings-backend dconf-service
  default-jre-headless fontconfig fontconfig-config fonts-dejavu-core
...
Setting up openjdk-17-jre-headless:amd64 (17.0.20.1+1-1~22.04) ...
Setting up ca-certificates-java (20190909ubuntu1.3) ...
Setting up maven (3.6.3-5) ...
Setting up openjdk-17-jdk-headless:amd64 (17.0.20.1+1-1~22.04) ...
Setting up openjdk-17-jre:amd64 (17.0.20.1+1-1~22.04) ...
Setting up openjdk-17-jdk:amd64 (17.0.20.1+1-1~22.04) ...

验证安装结果：

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

输出中 Java version: 17.0.20.1 说明 Maven 已经用上了刚安装的 JDK 17。注意最后一行 platform encoding: ANSI_X3.4-1968：默认语言环境不是 UTF-8，会导致 Java 程序打印中文时出现乱码。设置 UTF-8 语言环境后再看：

export LANG=C.UTF-8
mvn -v | grep encoding

实测回显：

Default locale: en, platform encoding: UTF-8

platform encoding 变为 UTF-8 后，中文回显正常。若希望长期生效，把 export LANG=C.UTF-8 追加进 ~/.bashrc 即可。

二、版本选型

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

版本	发布状态	JDK 编译目标（实测清单）	编译该 jar 的 JDK	适用场景
1.8.1	最新稳定版	Java 8（`X-Compile-Target-JDK: 1.8`）	Build-Jdk-Spec: 17	新项目首选
1.8.0	稳定版	Java 8（`X-Compile-Target-JDK: 1.8`）	Build-Jdk-Spec: 11	1.8.1 有兼容顾虑时的回退
1.7	旧版	Java 6（`X-Compile-Target-JDK: 1.6`）	Build-Jdk: 1.8.0_102	老系统 low-JDK 兼容
1.6	更早版本	Java 6（`X-Compile-Target-JDK: 1.6`）	Build-Jdk: 1.7.0_60	仅历史项目使用

关键差异与选型：1.8.1 与 1.8.0 的字节码目标都是 Java 8，JDK 8/11/17/21 均可运行；1.7 及更早的目标是 Java 6，只在必须兼容极老运行时（JDK 6/7）时才选。本文统一使用 1.8.1。

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

Maven 坐标：commons-dbutils:commons-dbutils:1.8.1
发行包：https://downloads.apache.org/commons/dbutils/binaries/commons-dbutils-1.8.1-bin.tar.gz
校验文件：https://downloads.apache.org/commons/dbutils/binaries/commons-dbutils-1.8.1-bin.tar.gz.sha512
sha512（实测）：
458dbca14ef7dbb034dcc01ed806bb4fa6fbf772b3bec7edfb1c530c0239cac9662a9733208ab68e4d3e436efd06bf9b97344595476c855637db2fae22992813

三个实测结论需要提前知道：

Maven 坐标的 groupId 是 commons-dbutils（不是 org.apache.commons）。实测访问 https://repo1.maven.org/maven2/org/apache/commons/commons-dbutils/1.8.1/commons-dbutils-1.8.1.pom 返回 HTTP 404，正确路径为 https://repo1.maven.org/maven2/commons-dbutils/commons-dbutils/1.8.1/。
Commons DbUtils 没有任何编译期传递依赖：其 pom 只声明了 test 作用域依赖（junit-vintage-engine、mockito-core、hamcrest-all），jar 清单里也只有 Import-Package: javax.sql。这意味着运行时只需主 jar 加一个 JDBC 驱动即可。
downloads.apache.org 只保留最新版。旧版（如 1.7）需到 Maven 中央仓库或 https://archive.apache.org/dist/commons/dbutils/ 下载。

💡 技术拓展：Java 里「把 ResultSet 转成对象」有多种实现路线，选型前先看清各自定位。下表对比常见方案：

方案	定位	依赖	对象映射	适用场景
原生 JDBC	JDK 内置接口	无	手写 `rs.getXxx()` 循环	逻辑极简单、零依赖
Spring JdbcTemplate	Spring 生态的 JDBC 封装	spring-jdbc	`RowMapper` 手动映射或 `BeanPropertyRowMapper`	已用 Spring 的工程
Commons DbUtils	轻量 JDBC 结果集工具	仅 JDBC 驱动	内置 Bean/Map/Scalar 等 Handler	不想引入 Spring 的轻量项目
MyBatis	全功能持久层框架	mybatis 等	XML/注解 + 内部映射器	需要 SQL 管理、缓存、动态 SQL

本文使用 Commons DbUtils：它只做「执行 SQL + 结果集到对象的转换」，不接管连接池与事务，体量小、零运行时依赖，适合在已有数据源之上做一层轻封装。

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

方案A通过 Maven 自动下载 jar 及其全部传递依赖，是工程化项目的推荐做法。Commons DbUtils 本身无可选依赖，但要让验证程序连上真实数据库，还需要一个 JDBC 驱动——本文用零安装的 H2 内嵌数据库（坐标 com.h2database:h2，实测版本 2.5.252）。先创建项目骨架：

mkdir -p /opt/dbutils-demo/src/main/java/net/quzuo/demo
cd /opt/dbutils-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>dbutils-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>commons-dbutils</groupId>
      <artifactId>commons-dbutils</artifactId>
      <version>1.8.1</version>
    </dependency>
    <dependency>
      <groupId>com.h2database</groupId>
      <artifactId>h2</artifactId>
      <version>2.5.252</version>
    </dependency>
  </dependencies>
</project>

逐项说明：maven.compiler.source/target 指定按 Java 17 语法编译；project.build.sourceEncoding 强制源码按 UTF-8 读取；dependencies 里的 commons-dbutils 是本库，h2 是验证用的内嵌数据库驱动。

验证依赖解析结果：

mvn dependency:tree

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

[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ dbutils-demo ---
[INFO] net.quzuo.demo:dbutils-demo:jar:1.0.0
[INFO] +- commons-dbutils:commons-dbutils:jar:1.8.1:compile
[INFO] \- com.h2database:h2:jar:2.5.252:compile
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

依赖树只有 commons-dbutils 与 h2 两个 compile 节点，没有其它 +- 子树，这正是「DbUtils 无编译期传递依赖」的实测证据。写入最小验证程序 src/main/java/net/quzuo/demo/HelloDbUtils.java：

package net.quzuo.demo;

import org.apache.commons.dbutils.QueryRunner;
import org.apache.commons.dbutils.handlers.MapListHandler;

import java.sql.Connection;
import java.sql.DriverManager;
import java.util.List;
import java.util.Map;

public class HelloDbUtils {
    public static void main(String[] args) throws Exception {
        Connection conn = DriverManager.getConnection("jdbc:h2:mem:hellodb;DB_CLOSE_DELAY=-1");
        QueryRunner runner = new QueryRunner();
        runner.update(conn, "create table greeting(id int primary key, msg varchar(64))");
        runner.update(conn, "insert into greeting values(?, ?)", 1, "hello commons dbutils");
        List<Map<String, Object>> rows =
                runner.query(conn, "select id, msg from greeting", new MapListHandler());
        System.out.println("查询结果: " + rows);
        System.out.println("DbUtils 版本: "
                + QueryRunner.class.getPackage().getImplementationVersion());
        conn.close();
        System.out.println("验证通过");
    }
}

程序逻辑：用 DriverManager 连一个 H2 内存库（DB_CLOSE_DELAY=-1 让库在连接关闭后仍存活），QueryRunner.update 建表并插入一行，QueryRunner.query 配 MapListHandler 把查询结果读成 List<Map>，最后从 jar 清单读出版本号。编译运行：

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

说明：exec:java 来自 exec-maven-plugin，首次使用 Maven 会自动从中央仓库拉取该插件（实测拉取版本为 3.6.4）。实测回显：

查询结果: [{ID=1, MSG=hello commons dbutils}]
DbUtils 版本: 1.8.1
验证通过

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

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

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

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

实测回显：

total 1160
-rw-r--r-- 1 root root 1180308 Oct 13 16:27 commons-dbutils-1.8.1-bin.tar.gz
-rw-r--r-- 1 root root     129 Oct 13 16:27 commons-dbutils-1.8.1-bin.tar.gz.sha512

发行包 1,180,308 字节。.sha512 文件内容是裸哈希（129 字节：128 个十六进制字符加换行），校验时要把它拼成 哈希文件名 的标准格式再交给 sha512sum -c：

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

实测回显：

commons-dbutils-1.8.1-bin.tar.gz: OK

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

sudo tar xzf commons-dbutils-1.8.1-bin.tar.gz
ls commons-dbutils-1.8.1/

实测回显：

LICENSE.txt
NOTICE.txt
RELEASE-NOTES.txt
apidocs
commons-dbutils-1.8.1-javadoc.jar
commons-dbutils-1.8.1-sources.jar
commons-dbutils-1.8.1-test-sources.jar
commons-dbutils-1.8.1-tests.jar
commons-dbutils-1.8.1.jar

关键点：发行包里只有 commons-dbutils-1.8.1.jar 一个主 jar，没有 lib/ 目录。查看主 jar 的清单可确认版本与 JDK 目标：

cd commons-dbutils-1.8.1
jar xf commons-dbutils-1.8.1.jar META-INF/MANIFEST.MF
cat META-INF/MANIFEST.MF | grep -E "Implementation-Version|X-Compile-Target-JDK|Import-Package"

实测回显：

Implementation-Version: 1.8.1
X-Compile-Target-JDK: 1.8
Import-Package: javax.sql

清单里没有 Main-Class，因此这个 jar 不是可执行 jar，直接 java -jar 会报错：

java -jar commons-dbutils-1.8.1.jar

实测回显：

no main manifest attribute, in commons-dbutils-1.8.1.jar

要验证功能，需要自行准备一个 JDBC 驱动，并从中央仓库下载 H2 jar 到 lib/：

cd /opt/commons/commons-dbutils-1.8.1
sudo mkdir -p lib && cd lib
sudo curl -fsSLO https://repo1.maven.org/maven2/com/h2database/h2/2.5.252/h2-2.5.252.jar
ls -l

实测回显：

total 2632
-rw-r--r-- 1 root root 2693360 Oct 13 16:44 h2-2.5.252.jar

写入与方案A相同逻辑的 HelloDbUtils.java（放到 /opt/commons/ 并去掉 package net.quzuo.demo; 首行）。编译并运行：

cd /opt/commons
javac -encoding UTF-8 -cp "commons-dbutils-1.8.1/commons-dbutils-1.8.1.jar:commons-dbutils-1.8.1/lib/*" HelloDbUtils.java -d out
java -Dfile.encoding=UTF-8 -cp "out:commons-dbutils-1.8.1/commons-dbutils-1.8.1.jar:commons-dbutils-1.8.1/lib/*" HelloDbUtils

实测回显：

查询结果: [{ID=1, MSG=hello commons dbutils}]
DbUtils 版本: 1.8.1
验证通过

注意 Linux 类路径分隔符是冒号 :（Windows 是分号），lib/* 中的星号由 JVM 自己展开，不要加引号以避免 shell 误展开。再演示一个必踩的坑——类路径里漏掉 JDBC 驱动 jar 时：

java -Dfile.encoding=UTF-8 -cp "out:commons-dbutils-1.8.1/commons-dbutils-1.8.1.jar" HelloDbUtils

实测回显：

Exception in thread "main" java.sql.SQLException: No suitable driver found for jdbc:h2:mem:hellodb;DB_CLOSE_DELAY=-1
        at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:706)
        at java.sql/java.sql.DriverManager.getConnection(DriverManager.java:252)
        at HelloDbUtils.main(HelloDbUtils.java:11)

报错说明：DbUtils 自身零依赖，但运行时仍需数据库配套的 JDBC 驱动；把驱动 jar 放进类路径即可，方案B安装完成。

五、方案对比与选型建议

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

选型建议：开发/CI 环境一律方案A；目标机器没有 Maven 或需要临时排查时用方案B。方案B的驱动 jar（如 H2 2.5.252）也建议从中央仓库下载，保持与方案A一致的版本。

六、多版本管理

同一台机器上共存多个 Commons DbUtils 版本，推荐用「版本目录 + current 符号链接」的方式管理：所有版本平铺在 /opt/commons/ 下，current 指向当前生效版本，切换时只改链接。创建 1.8.1 与 1.7 两个版本目录：

cd /opt/commons
sudo mkdir -p commons-dbutils-1.8.1/lib commons-dbutils-1.7/lib
sudo curl -fsSL -o commons-dbutils-1.7/commons-dbutils-1.7.jar https://repo1.maven.org/maven2/commons-dbutils/commons-dbutils/1.7/commons-dbutils-1.7.jar
sudo curl -fsSL -o commons-dbutils-1.7/lib/h2-2.5.252.jar https://repo1.maven.org/maven2/com/h2database/h2/2.5.252/h2-2.5.252.jar
sudo ln -sfn commons-dbutils-1.8.1 current
ls -l

实测回显：

total 1176
-rw-r--r-- 1 root root    1013 Oct 13 16:32 HelloDbUtils.java
drwxr-xr-x 3 root root    4096 Oct 13 16:33 commons-dbutils-1.7
drwxr-xr-x 4 root root    4096 Oct 13 16:32 commons-dbutils-1.8.1
-rw-r--r-- 1 root root 1180308 Oct 13 16:27 commons-dbutils-1.8.1-bin.tar.gz
-rw-r--r-- 1 root root     129 Oct 13 16:27 commons-dbutils-1.8.1-bin.tar.gz.sha512
lrwxrwxrwx 1 root root      21 Oct 13 16:33 current -> commons-dbutils-1.8.1
drwxr-xr-x 2 root root    4096 Oct 13 16:32 out

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

cd /opt/commons
javac -encoding UTF-8 -cp "current/commons-dbutils-1.8.1.jar:current/lib/*" HelloDbUtils.java -d out
java -Dfile.encoding=UTF-8 -cp "out:current/commons-dbutils-1.8.1.jar:current/lib/*" HelloDbUtils

实测回显：

查询结果: [{ID=1, MSG=hello commons dbutils}]
DbUtils 版本: 1.8.1
验证通过

切换到 1.7 再运行（类路径改为 current/commons-dbutils-1.7.jar，版本号以程序打印为准）：

sudo ln -sfn commons-dbutils-1.7 current
ls -l current
java -Dfile.encoding=UTF-8 -cp "out:current/commons-dbutils-1.7.jar:current/lib/*" HelloDbUtils

实测回显：

lrwxrwxrwx 1 root root 19 Oct 13 16:33 current -> commons-dbutils-1.7
查询结果: [{ID=1, MSG=hello commons dbutils}]
DbUtils 版本: 1.7
验证通过

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

sudo ln -sfn commons-dbutils-1.8.1 current

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

七、卸载

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

sudo rm -rf /opt/commons

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

du -sh ~/.m2/repository/commons-dbutils
rm -rf ~/.m2/repository/commons-dbutils

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

128K    /root/.m2/repository/commons-dbutils

若 JDK 17 与 Maven 也不再有他用，可一并卸载：

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

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

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: mvn: command not found
bash: javac: command not found

mvn、javac 命令消失即卸载完成。注意：~/.m2 中其他项目的依赖缓存不受本次卸载影响；若机器上原本还有其它 JDK，卸载 JDK 17 后 java 命令会回退到那个 JDK。

八、FAQ

Q1：java -jar commons-dbutils-1.8.1.jar 为什么报 no main manifest attribute？ 因为 DbUtils 是库，不是可执行程序，jar 清单里没有 Main-Class。要用它必须自己写主类，并以 java -cp "主jar:驱动jar" 主类 的方式运行（见第四章实测命令），或把它作为依赖加入自己的工程。

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

Q3：只放 DbUtils jar 到类路径，运行时报 No suitable driver found for jdbc:h2:...？ DbUtils 只做结果集转换，不包含任何数据库驱动。请把对应数据库的 JDBC 驱动 jar（本文用 H2 2.5.252）一并加入类路径。这是第四章实测复现的报错。

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

Q5：Maven 里 org.apache.commons:commons-dbutils 拉不到依赖怎么办？ DbUtils 的 artifact groupId 是 commons-dbutils，不是 org.apache.commons。实测 org.apache.commons:commons-dbutils:1.8.1 对应 pom 地址 404。正确坐标是 commons-dbutils:commons-dbutils:1.8.1。

九、参考链接

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