Apache Commons FileUpload 常用 CLI 命令与工具详解

以命令行实操演示 Apache Commons FileUpload 2.0.0-M5：jar 查看解包、javac/java 编译运行、mvn 构建、curl -F 上传 multipart、sha512sum 校验，命令均附实测回显。

Apache Commons FileUploadApache Commons FileUpload2026/10/14

Apache Commons FileUpload 常用 CLI 命令与工具详解

目标：梳理 Apache Commons FileUpload 2.0.0-M5 配套的全部命令行工具与高频命令（jar、javac、java、mvn、curl -F、sha512sum 等），每条命令给出实测回显，已在 Ubuntu 22.04.5 服务器实测通过。

一、环境信息

本节列出文档实测的服务器基础信息。

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • JDK：OpenJDK 17.0.20.1（含 jar/javac/java 工具链）
  • 构建工具：Apache Maven 3.6.3
  • 组件版本：Apache Commons FileUpload 2.0.0-M5
  • 依赖：commons-io 2.21.0、jakarta.servlet-api 5.0.0、Jetty 11.0.26（验证用）
  • 实验目录：/opt/fu-lab

二、工具概览

本节说明 FileUpload 作为 Java 库对应的命令行工具集及其分工。

FileUpload 本身没有可执行 CLI（它是 jar 库），真正面向命令行的工具是 Java 生态工具链，按使用阶段分为五类：

工具阶段作用
curl下载与验证下载 bin 包、发起 multipart 上传测试
sha512sum完整性校验下载包哈希
jar构件检查查看/解包 jar 内容与清单
javac/java编译运行编译运行最小验证程序
mvn构建坐标拉依赖、打包、生成 classpath

💡 技术拓展：Java 依赖库的"命令行工具集"不止 Maven 系——

工具链特点适用场景
javac + java零依赖、最底层无构建工具的最小验证
Maven（mvn）坐标管理 + 生命周期主流 Java 工程
Gradle构建脚本即代码多模块/复杂构建
sdkman / jenvJDK 版本管理开发机多版本切换

本文全部命令基于 javac + Maven 组合实测，覆盖从下载到验证的完整链路。

三、前置条件

本节说明执行后续命令所需的环境（完整安装步骤见《Ubuntu 22.04 安装 Apache Commons FileUpload 指南》篇）。

  • 已安装 JDK 17 与 Maven：java -version / mvn -version 可用
  • 已下载 FileUpload 2.0.0-M5 bin 包至 /opt/fu-lab 并解压

确认环境：

java -version 2>&1 | head -1
mvn -version 2>&1 | head -1
ls /opt/fu-lab/commons-fileupload2-2.0.0-M5/

实测回显：

openjdk version "17.0.20.1" 2026-08-18
Apache Maven 3.6.3
LICENSE.txt  NOTICE.txt  RELEASE-NOTES.txt
commons-fileupload2-core-2.0.0-M5.jar
commons-fileupload2-jakarta-servlet5-2.0.0-M5.jar
commons-fileupload2-jakarta-servlet6-2.0.0-M5.jar
commons-fileupload2-javax-2.0.0-M5.jar
commons-fileupload2-portlet-2.0.0-M5.jar

四、curl 命令（下载与上传实测）

本节详解 curl 在 FileUpload 生命周期中的两类用途：下载构件与 multipart 上传测试。

4.1 下载 bin 包与校验文件

cd /opt/fu-lab
curl -LO https://downloads.apache.org/commons/fileupload/binaries/commons-fileupload2-2.0.0-M5-bin.tar.gz
curl -LO https://downloads.apache.org/commons/fileupload/binaries/commons-fileupload2-2.0.0-M5-bin.tar.gz.sha512

参数说明：-L 跟随重定向（downloads.apache.org 会 302 重定向到就近下载节点），-O 以 URL 末尾文件名保存。实测文件落盘：

ls -la commons-fileupload2-2.0.0-M5-bin.tar.gz*

实测回显：

-rw-r--r-- 1 root root 1309645 Oct 13 17:59 commons-fileupload2-2.0.0-M5-bin.tar.gz
-rw-r--r-- 1 root root     129 Oct 13 17:59 commons-fileupload2-2.0.0-M5-bin.tar.gz.sha512

4.2 列出官方发布目录

curl -s https://downloads.apache.org/commons/fileupload/binaries/ | grep -oE 'href="[^"]+\.tar\.gz"' | sort -u

实测回显（输出节选）：

href="commons-fileupload-1.6.0-bin.tar.gz"
href="commons-fileupload2-2.0.0-M5-bin.tar.gz"

4.3 multipart 上传实测（curl -F）

-F 以 multipart/form-data 编码发送表单；-F "name=value" 为普通字段，-F "name=@文件;type=MIME" 为文件字段：

printf "hello from curl -F upload test\nline2: multipart parsing ok\n" > /opt/fu-lab/REPORT.txt
curl -s http://127.0.0.1:18080/upload -F "author=Apache Commons FileUpload 2.0.0-M5" -F "report=@/opt/fu-lab/REPORT.txt;type=text/plain"

实测回显（服务端为 5.2 节 Servlet 回显）：

Parsed FileItem count: 2
  fieldName=author | isFormField=true | fileName=null | contentType=null | size=34 | value=Apache Commons FileUpload 2.0.0-M5
  fieldName=report | isFormField=false | fileName=REPORT.txt | contentType=text/plain | size=65 | value=hello from curl -F upload test
line2: multipart parsing ok

size=65 与文件实际字节数一致，fileName=REPORT.txt 为 -F 上传的文件名回显，multipart 编码正确。

五、sha512sum 命令（完整性校验）

本节说明如何用官方 sha512 校验下载包。

sha512sum commons-fileupload2-2.0.0-M5-bin.tar.gz
cat commons-fileupload2-2.0.0-M5-bin.tar.gz.sha512

实测回显：

7e050be0187813dfa6fac3e9679a9be71a7956a97ff3e8e762ad2fd5552f3883ecfbe92c013c2f66409a998600c7167d8749eecbdf61ba50f69472af8a9ec533  commons-fileupload2-2.0.0-M5-bin.tar.gz
7e050be0187813dfa6fac3e9679a9be71a7956a97ff3e8e762ad2fd5552f3883ecfbe92c013c2f66409a998600c7167d8749eecbdf61ba50f69472af8a9ec533

两行哈希一致即校验通过；若不一致说明下载损坏或包被篡改。

六、jar 命令（构件查看与解包）

本节详解 jar 工具查看 FileUpload 构件的三类命令。

6.1 查看 jar 版本与类结构（jar tf）

cd /opt/fu-lab
jar tf commons-fileupload2-2.0.0-M5/commons-fileupload2-core-2.0.0-M5.jar | head -8

实测回显：

META-INF/
META-INF/MANIFEST.MF
org/
org/apache/
org/apache/commons/
org/apache/commons/fileupload2/
org/apache/commons/fileupload2/core/
META-INF/maven/

jar tf 列出的 org/apache/commons/fileupload2/core/ 即 2.x 核心包路径（1.x 为 org/apache/commons/fileupload/，无 2）。

6.2 查看工具版本（jar --version）

jar --version

实测回显：

jar 17.0.20.1

6.3 解包查看 MANIFEST 元数据（jar xf）

MANIFEST 中含构件版本、OSGi 导出包、所需 Java 版本等关键元数据：

mkdir -p /tmp/mf && cd /tmp/mf
jar xf /opt/fu-lab/commons-fileupload2-2.0.0-M5/commons-fileupload2-core-2.0.0-M5.jar META-INF/MANIFEST.MF
grep -E "Implementation-Version|Java-Version|Specification-Version" META-INF/MANIFEST.MF

实测回显：

Java-Version: 11
Implementation-Version: 2.0.0-M5
Specification-Version: 2.0.0-M5

解读：Java-Version: 11 说明该构件最低要求 Java 11（与发布说明一致）；Implementation-Version/Specification-Version 均为 2.0.0-M5，版本自洽。

七、javac / java 命令（编译与运行）

本节详解编译运行 FileUpload 验证程序的命令形态。

7.1 编译（javac -cp -d -encoding）

mkdir -p /opt/fu-lab/out
javac -encoding UTF-8 -cp "/opt/fu-lab/commons-fileupload2-2.0.0-M5/commons-fileupload2-core-2.0.0-M5.jar:/opt/fu-lab/deps/commons-io-2.21.0.jar" -d /opt/fu-lab/out /opt/fu-lab/src/FileUpload2CoreDemo.java

参数说明：-encoding UTF-8 指定源码编码（服务器 locale 为 POSIX 时必加，否则中文注释报 unmappable）；-cp 以冒号分隔列出 core jar 与 commons-io；-d 指定类输出目录。编译无输出即成功（退出码 0）：

echo $?

实测回显：

0

7.2 运行（java -Xms/-Xmx 限制堆内存）

JVM 堆内存按规范限制在 256–512MB 区间，避免默认大堆占用：

java -Xms256m -Xmx256m -cp "/opt/fu-lab/out:/opt/fu-lab/commons-fileupload2-2.0.0-M5/commons-fileupload2-core-2.0.0-M5.jar:/opt/fu-lab/deps/commons-io-2.21.0.jar" FileUpload2CoreDemo

实测回显：

Parsed FileItem count: 2
  fieldName=author | isFormField=true | fileName=null | contentType=null | value=Apache Commons FileUpload 2.0.0-M5
  fieldName=report | isFormField=false | fileName=demo.txt | contentType=text/plain | value=hello from commons-fileupload2-core

-Xms256m -Xmx256m 将初始与最大堆均限为 256MB，multipart 解析正常完成。

八、mvn 命令（构建与依赖管理）

本节详解 Maven 在 FileUpload 工程中的四个常用目标。

8.1 构建打包（mvn package）

cd /opt/fu-lab/jetty-demo && mvn -q -DskipTests package
echo $?

实测回显：

0

-q 静默模式只输出错误；-DskipTests 跳过测试（FileUpload 集成验证通过 Servlet 运行时实测完成）。退出码 0 打包成功，产物在 target/。

8.2 生成依赖 classpath（mvn dependency:build-classpath）

启动 Jetty 时需要一个不含旧包干扰的完整 classpath：

cd /opt/fu-lab/jetty-demo && mvn -q dependency:build-classpath -Dmdep.outputFile=cp.txt
grep -oE "commons-fileupload2[^:]*|commons-io[^:]*" cp.txt | sort -u

实测回显：

/root/.m2/repository/commons-io/commons-io/2.21.0/commons-io-2.21.0.jar
/root/.m2/repository/org/apache/commons/commons-fileupload2-core/2.0.0-M5/commons-fileupload2-core-2.0.0-M5.jar
/root/.m2/repository/org/apache/commons/commons-fileupload2-jakarta-servlet5/2.0.0-M5/commons-fileupload2-jakarta-servlet5-2.0.0-M5.jar

输出确认传递依赖链：jakarta-servlet5 → core → commons-io 2.21.0，无旧版污染。

8.3 查看依赖树（mvn dependency:tree）

cd /opt/fu-lab/jetty-demo && mvn dependency:tree 2>&1 | grep -E "fileupload|commons-io|jetty-server|jakarta.servlet"

实测回显（输出节选）：

org.apache.commons:commons-fileupload2-jakarta-servlet5:jar:2.0.0-M5:compile
  \- org.apache.commons:commons-fileupload2-core:jar:2.0.0-M5:compile
     \- commons-io:commons-io:jar:2.21.0:compile
org.eclipse.jetty:jetty-server:jar:11.0.26:compile
jakarta.servlet:jakarta.servlet-api:jar:5.0.0:provided

解读：compile scope 的 fileupload2-core 自动带入 commons-io；jakarta.servlet-api 为 provided（Web 服务器运行期自带）；jetty 仅验证用。

8.4 查看插件目标（mvn help:describe）

cd /opt/fu-lab/jetty-demo && mvn help:describe -Dplugin=org.codehaus.mojo:exec-maven-plugin -Dgoal=java 2>&1 | tail -12

实测回显（输出节选）：

Mojo: 'exec:java'
exec:java
  Description: Executes the supplied java class in the current VM with the
    enclosing project's dependencies as classpath.

For more information, run 'mvn help:describe' with the detail flag

[INFO] BUILD SUCCESS
[INFO] Total time:  0.743 s

解读：该目标（goal）为 exec:java，作用是"在当前 JVM 中执行给定的 Java 类，并把工程依赖作为 classpath"；-DmainClass 参数用于指定主类（本工程通过 exec-maven-plugin 配置的 mainClass 指向 upload.UploadServer）。

九、注意事项

本节汇总使用上述命令时的要点。

  • classpath 顺序：-cp 中先列工程类目录再列 jar；切勿把整个 /root/.m2/repository 用 find 拼进 classpath——会混入旧版 commons-io（如 1.4）导致 NoSuchMethodError: FileUtils.getTempDirectoryPath()，应用 mvn dependency:build-classpath 生成的清单（见 8.2 实测）。
  • 编码一致性：javac 加 -encoding UTF-8，curl -F 文件名与表单值保持 UTF-8，Servlet 侧 getString(StandardCharsets.UTF_8)，任一处不一致即乱码。
  • JVM 堆限制：启动验证程序统一 -Xms256m -Xmx256m（256–512MB 区间），不上默认大堆。
  • 端口占用：Jetty 演示监听 18080，重复启动前确认无残留进程（ss -ltnp | grep 18080）。
  • 临时文件清理：超过阈值的上传会在 /tmp 生成 upload_*.tmp，验证后按需清理，避免磁盘膨胀。

十、常见问题

Q1：jar tf 列出的包路径与 1.x 不同？

定位：2.x 核心包为 org/apache/commons/fileupload2/core/，1.x 为 org/apache/commons/fileupload/。 解决：2.x 工程 import 一律用 org.apache.commons.fileupload2.*。

Q2：mvn dependency:build-classpath 与手工 find 的 classpath 有何区别？

定位：Maven 生成的是解析后的最小依赖集（含版本仲裁），find 会把本地仓库全部 jar 混入。 解决：一律用 Maven 生成；这是 4.x/6.x 篇实测遇到 NoSuchMethodError 后的标准解法。

Q3：curl -F 上传中文文件名乱码？

定位：multipart 头编码默认非 UTF-8，且未在服务端设置 headerCharset。 解决：upload.setHeaderCharset(StandardCharsets.UTF_8)（见《配置参数详解》6.5 节）。

Q4：java -Xmx256m 跑大文件上传内存不够？

定位：超过 threshold 的文件已落临时盘，堆内存仅承载缓冲与元数据；但整请求流式读入仍受 maxSize 保护。 解决：合理设置 maxSize/maxFileSize（见《配置参数详解》七、节模板），而非盲目加大堆。

十一、参考链接

  1. Apache Commons FileUpload 官网：https://commons.apache.org/proper/commons-fileupload/
  2. 官方 bin 发布目录：https://downloads.apache.org/commons/fileupload/binaries/
  3. JDK 工具（jar/javac/java）文档：https://docs.oracle.com/en/java/javase/17/tools/
  4. curl 手册：https://curl.se/docs/manpage.html
  5. Maven 依赖插件文档：https://maven.apache.org/plugins/maven-dependency-plugin/