异常教程

JSP 文件上传（千字长文）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

  • 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;
  • 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 82w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 2900+ 小伙伴加入学习 ，欢迎点击围观

前言

在 Web 开发中，文件上传是一个核心功能，无论是用户头像上传、文档提交还是多媒体内容管理，都离不开这一技术。作为 Java Web 开发的重要组成部分，JSP（JavaServer Pages）结合 Servlet 技术，为开发者提供了灵活的文件上传解决方案。本文将从零开始，逐步解析 JSP 文件上传的实现原理、代码细节以及常见问题，帮助编程初学者和中级开发者快速掌握这一技能。

一、JSP 文件上传的基本原理

1.1 文件上传的底层逻辑

文件上传本质上是一个 客户端与服务器端的数据交互过程。可以将其类比为快递运输：

  • 客户端（如浏览器）负责将文件打包成特定格式（如 multipart/form-data）并发送；
  • 服务器端（如 JSP/Servlet 环境）负责接收、解析文件内容，并最终保存到指定路径。

1.2 关键技术组件

  • HTML 表单：提供用户选择和提交文件的界面；
  • Servlet：处理 HTTP 请求，解析上传的文件数据；
  • Apache Commons FileUpload：一个开源工具库，简化文件上传的复杂逻辑。

二、实现文件上传的步骤分解

2.1 步骤 1：设计 HTML 表单

表单需要满足两个核心条件：

  1. 设置 enctype="multipart/form-data"：告诉浏览器以二进制流传输文件数据；
  2. 设置 method="POST"：确保数据通过 POST 请求发送（GET 不支持文件上传）。

示例代码：

<form action="uploadServlet" method="POST" enctype="multipart/form-data">
    <input type="file" name="userFile" accept=".jpg, .png, .pdf" />
    <input type="submit" value="上传文件" />
</form>

2.2 步骤 2：配置 Servlet 处理请求

在 Web 应用中，Servlet 负责接收并处理上传的文件。以下是关键实现逻辑：

  1. 依赖库引入：使用 Apache Commons FileUpload 和 Apache Commons IO 库；
  2. 解析请求数据：将 HttpServletRequest 转换为 MultipartRequest 对象；
  3. 保存文件：根据业务需求指定文件保存路径。

示例代码（Servlet 类）：

@WebServlet("/uploadServlet")
public class FileUploadServlet extends HttpServlet {
    private static final long serialVersionUID = 1L;
    
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
        throws ServletException, IOException {
        
        // 1. 配置上传参数
        int maxFileSize = 1024 * 1024 * 5; // 最大 5MB
        String uploadPath = getServletContext().getRealPath("/uploads/");
        
        // 2. 创建 DiskFileItemFactory 对象
        DiskFileItemFactory factory = new DiskFileItemFactory();
        factory.setSizeThreshold(1024 * 100); // 内存阈值 100KB
        factory.setRepository(new File(System.getProperty("java.io.tmpdir")));
        
        // 3. 初始化 ServletFileUpload 对象
        ServletFileUpload upload = new ServletFileUpload(factory);
        upload.setSizeMax(maxFileSize);
        
        try {
            // 4. 解析请求，获取文件项
            List<FileItem> items = upload.parseRequest(request);
            for (FileItem item : items) {
                if (!item.isFormField()) { // 判断是否为文件域
                    String fileName = new File(item.getName()).getName();
                    File uploadedFile = new File(uploadPath + fileName);
                    
                    // 5. 保存文件到服务器
                    item.write(uploadedFile);
                    
                    response.getWriter().println("文件上传成功！路径：" + uploadedFile.getAbsolutePath());
                }
            }
        } catch (Exception e) {
            response.getWriter().println("上传失败：" + e.getMessage());
        }
    }
}

三、优化与扩展：提升文件上传的健壮性

3.1 文件类型与大小限制

通过 accept 属性（HTML 层）和 ServletFileUpload.setSizeMax()（服务端）双重验证，防止非法文件上传。

3.2 中文文件名乱码问题

文件名可能因编码问题导致乱码，需在解析时指定编码格式：

DiskFileItemFactory factory = new DiskFileItemFactory();
factory.setRepository(tempDir);
factory.setFileCleaningTracker(new NullFileCleaningTracker());

3.3 动态路径与重命名

避免文件覆盖，可通过时间戳或 UUID 生成唯一文件名：

String uniqueName = UUID.randomUUID().toString() + "_" + fileName;
File uploadedFile = new File(uploadPath + uniqueName);

四、常见问题与解决方案

4.1 上传失败：HTTP 500 错误

原因：未正确配置依赖库或文件存储路径权限不足。
解决：

  • 确保 commons-fileupload 和 commons-io 添加到项目依赖；
  • 检查服务器的 uploads 文件夹权限是否可写。

4.2 文件内容损坏

原因：未正确关闭流或未使用 FileItem.write() 方法。
解决：始终使用 FileItem.write(file) 直接写入文件，避免手动操作流。

五、实战案例：构建一个完整的文件管理功能

5.1 案例目标

实现一个支持多文件上传、展示上传记录的简单系统。

5.2 完整代码示例

HTML 表单（uploadForm.jsp）：

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<!DOCTYPE html>
<html>
<head>
    <title>JSP 文件上传示例</title>
</head>
<body>
    <h2>文件上传</h2>
    <form action="FileUploadServlet" method="POST" enctype="multipart/form-data">
        <input type="file" name="files" multiple accept="image/*, .pdf" />
        <input type="submit" value="上传" />
    </form>
</body>
</html>

Servlet（FileUploadServlet.java）：

@WebServlet("/FileUploadServlet")
public class FileUploadServlet extends HttpServlet {
    private static final long serialVersionUID = 1L;
    
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
        throws ServletException, IOException {
        
        String uploadPath = getServletContext().getRealPath("/uploads/");
        File dir = new File(uploadPath);
        if (!dir.exists()) dir.mkdirs();
        
        DiskFileItemFactory factory = new DiskFileItemFactory();
        ServletFileUpload upload = new ServletFileUpload(factory);
        
        try {
            List<FileItem> items = upload.parseRequest(request);
            for (FileItem item : items) {
                if (!item.isFormField()) {
                    String fileName = new File(item.getName()).getName();
                    File file = new File(uploadPath + fileName);
                    item.write(file);
                    System.out.println("Saved file: " + file.getAbsolutePath());
                }
            }
            response.sendRedirect("uploadSuccess.jsp");
        } catch (Exception e) {
            response.getWriter().println("错误：" + e.getMessage());
        }
    }
}

上传成功页面（uploadSuccess.jsp）：

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ page import="java.io.File" %>
<!DOCTYPE html>
<html>
<head>
    <title>上传成功</title>
</head>
<body>
    <h3>已上传文件列表</h3>
    <ul>
        <%
            String path = application.getRealPath("/uploads");
            File dir = new File(path);
            if (dir.exists()) {
                for (File f : dir.listFiles()) {
                    if (f.isFile()) {
        %>
        <li><a href="download?file=<%= f.getName() %>"><%= f.getName() %></a></li>
        <%
                    }
                }
            }
        %>
    </ul>
</body>
</html>

结论

通过本文的讲解，您已掌握了 JSP 文件上传的核心流程、代码实现以及常见问题的解决方案。从基础表单设计到复杂的功能扩展，这一技术不仅提升了 Web 应用的实用性，也为开发者提供了丰富的自定义空间。无论是构建个人博客的图片上传功能，还是企业级文档管理系统，本文提供的方法和示例代码都能为您提供有力支持。

下一步行动建议：

  1. 尝试将文件上传功能与数据库结合，记录文件元数据；
  2. 探索异步上传和进度条显示，提升用户体验；
  3. 学习 Spring Boot 等框架的文件上传实现，对比传统 JSP 的差异。

掌握文件上传技术，您将解锁更多 Web 开发的潜力！

最新发布

查看更多文章