下面给你一篇 清晰、完整、可直接用于学习或写技术文档的
《org.apache.commons.fileupload 使用教程》（含示例代码 + 常见问题）。
如果你需要，我也可以帮你生成 Spring MVC / Spring Boot 版本的文件上传 Demo。
org.apache.commons.fileupload 使用详解（最实用教程）
适用于：Java Web、Servlet、Tomcat、JSP 上传文件
commons-fileupload 是 Apache 最经典的文件上传组件，常与 commons-io 搭配，用于 Servlet 3.0 之前的文件上传处理。
🧩 1. 环境依赖
在 Maven 项目中加入：
<dependency>
<groupId>commons-fileupload</groupId>
<artifactId>commons-fileupload</artifactId>
<version>1.4</version>
</dependency>
<dependency>
<groupId>commons-io</groupId>
<artifactId>commons-io</artifactId>
<version>2.11.0</version>
</dependency>
如果不是 Maven，则加入 JAR：
- commons-fileupload-x.x.jar
- commons-io-x.x.jar
🧩 2. 前端上传表单（JSP / HTML）
必须包含两点：
method="post"enctype="multipart/form-data"
<form action="/upload" method="post" enctype="multipart/form-data">
<input type="file" name="file"><br>
<input type="submit" value="上传">
</form>
🧩 3. 核心处理：Servlet 处理上传文件
下面是最经典的原生 Servlet 上传代码。
@WebServlet("/upload")
public class UploadServlet extends HttpServlet {
@Override
protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
// 首先判断是否为 multipart/form-data
boolean isMultipart = ServletFileUpload.isMultipartContent(request);
if (!isMultipart) {
response.getWriter().println("Error: 表单必须包含 enctype=multipart/form-data");
return;
}
// 1. 创建文件工厂（临时文件）
DiskFileItemFactory factory = new DiskFileItemFactory();
factory.setSizeThreshold(1024 * 1024); // 设置内存缓冲区大小 (1MB)
factory.setRepository(new File("D:/temp")); // 临时目录
// 2. 创建文件上传解析器
ServletFileUpload upload = new ServletFileUpload(factory);
upload.setHeaderEncoding("UTF-8"); // 避免中文文件名乱码
// 3. 设置单个文件 / 结合大小限制
upload.setFileSizeMax(10 * 1024 * 1024); // 10MB
upload.setSizeMax(20 * 1024 * 1024); // 请求总大小 20MB
try {
// 4. 解析请求
List<FileItem> formItems = upload.parseRequest(request);
if (formItems != null && formItems.size() > 0) {
for (FileItem item : formItems) {
if (!item.isFormField()) {
// 5. 处理文件字段
String fileName = new File(item.getName()).getName();
String uploadPath = "D:/upload/";
File storeFile = new File(uploadPath + fileName);
// 创建目录
storeFile.getParentFile().mkdirs();
// 6. 保存文件
item.write(storeFile);
response.getWriter().println("上传成功: " + fileName);
} else {
// 处理普通表单字段
String fieldName = item.getFieldName();
String fieldValue = item.getString("UTF-8");
System.out.println(fieldName + "=" + fieldValue);
}
}
}
} catch (Exception ex) {
response.getWriter().println("上传失败：" + ex.getMessage());
}
}
}
🧩 4. 关键 API 解释
✔ DiskFileItemFactory
用于管理上传的文件和临时缓冲：
| 方法 | 作用 |
|---|---|
setSizeThreshold() | 内存缓冲区大小 |
setRepository() | 临时文件目录（存硬盘的地方） |
✔ ServletFileUpload
| 方法 | 作用 |
|---|---|
parseRequest() | 解析上传请求 |
setFileSizeMax() | 单个文件限制 |
setSizeMax() | 总大小限制 |
setHeaderEncoding("UTF-8") | 避免中文字段乱码 |
✔ FileItem
| 方法 | 作用 |
|---|---|
isFormField() | 判断是否为普通表单项 |
getName() | 获取文件名 |
write(File) | 保存文件 |
🧩 5. 文件名乱码、路径问题（常见错误）
问题 1：中文文件名乱码
解决：
upload.setHeaderEncoding("UTF-8");
item.getString("UTF-8");
问题 2：上传目录无法写入
确保：
- Tomcat 有写权限
- Windows 目录不能包含中文
问题 3：文件太大，报：SizeLimitExceededException
增加：
upload.setFileSizeMax(50 * 1024 * 1024);
upload.setSizeMax(100 * 1024 * 1024);
🧩 6. 多文件上传示例
<input type="file" name="files" multiple>
后端自动遍历：
if (!item.isFormField()) {
File storeFile = new File(uploadPath + item.getName());
item.write(storeFile);
}
🧩 7. 结合 Spring MVC 的使用（你需要我可以写更完整）
只需使用：
CommonsMultipartResolver
更现代的项目使用：
- Spring Boot →
MultipartFile - Servlet 3.1+ 内置文件上传 API → 不需要 fileupload
如你需要，我可以写：
✔ Spring MVC + fileupload 配置
✔ Spring Boot 版本（无需 fileupload）
✔ JSP 上传页面 + Controller
✔ 完整 Demo 工程结构
发表回复