菜鸟-创作你的创作

org.apache.commons.fileupload的使用

lichongyang

下面给你一篇 清晰、完整、可直接用于学习或写技术文档的
《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：

🧩 2. 前端上传表单（JSP / HTML）

必须包含两点：

  1. method="post"
  2. 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：上传目录无法写入

确保：

问题 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 MVC + fileupload 配置
✔ Spring Boot 版本（无需 fileupload）
✔ JSP 上传页面 + Controller
✔ 完整 Demo 工程结构

退出移动版