JavaWeb原生实现文件夹分片上传：JSP+Servlet实战指南-代码聚汇网

JavaWeb原生实现文件夹分片上传：JSP+Servlet实战指南

永远雪山·2026-09-12·阅读 107 GEO检测（免费）

文件上传分片上传JavaWeb

|难度：普通|阅读约 24 分钟

做 JavaWeb 开发的朋友，十有八九都被问过文件上传的需求，但“文件夹级别的分片上传”这种组合拳，真正上手做过的人就少很多了。最近我正好在一个老项目里把这块完整落地了一遍，用的是 JSP + Servlet 的原生方案，没有额外引入 Spring Boot 那套重型框架。今天把整个设计思路、前端切片逻辑、后端合并细节和踩过的坑一次性讲清楚，方便你直接在项目里改造复用。

这篇文章适合正在做 JavaWeb 老项目维护、或者想在不依赖前端框架的前提下给系统加上传能力的同学。你用 JSP 还是 FreeMarker 都不影响，核心逻辑在前端用原生 JavaScript 实现，后端只要是一个能够接收 multipart 请求的 Servlet 就行，JSP 在这里只承担页面渲染和进度展示的工作。这套方案实测下来，单文件最大支持到 2GB 没有问题，文件夹内的层级结构可以完整保留，同时支持并发上传和断点续传的扩展。

1. 分片上传到底在解决什么问题

1.1 文件夹上传的常见痛点

先想明白一件事：为什么不直接用一个 input 把整个文件夹压缩成 zip 再传？因为大多数业务场景里，用户上传完文件后，系统还需要对每个文件单独做处理、做预览、做权限控制。如果你把整个文件夹压成一个 zip，后端还得解压、还要处理压缩包炸弹的风险、还要重新扫描目录结构，这一圈绕下来性能损耗非常大。

更关键的是，文件夹里通常有大量的小文件和一些体积比较大的单个文件。如果逐个文件单独发起上传请求，一个包含 500 个文件的文件夹就要产生 500 次 HTTP 连接，网络开销和服务器负载都难以接受。如果整个文件夹一次性提交，后端存储时会遇到单个请求体过大、内存溢出、网络中断全盘重传等一系列问题。

分片上传解决的就是这个平衡问题。把每个文件切成若干小块，每一块独立上传，后端接收后按序号合并。好处非常明显：

单个请求的数据量可控，不会撑爆服务器的内存和带宽
上传过程中某一片失败只需要重传这一片，而不是整个文件重新来
可以同时并发上传多个分片，充分利用带宽
切片时可以记录进度，实现真正的断点续传

文件夹和单文件的区别在于，文件夹多了一层目录结构信息要保留，所以前端遍历时要把每个文件相对于根目录的路径记录下来，这就是整个方案的设计核心。

1.2 JSP 在整个体系里扮演什么角色

很多初学者容易有个误解，觉得 JSP 既然是 Java 的页面技术，那上传逻辑就应该写在 JSP 里。其实这是不合适的。我见过有人把大段 Java 代码塞进 JSP 脚本片段里处理文件流，维护起来就是一场灾难。

在这次方案里，JSP 只负责两件事：

展示上传页面，包含文件夹选择控件、上传进度条、日志展示区域
通过 Ajax 请求向后端发起文件分片上传的调用

真正接收分片、存储临时文件、合并分片、清理缓存这些脏活累活，全部放在一个独立的 Servlet 中完成。这样做的好处是职责清晰，目录结构和 Servlet 的映射关系可以直接通过注解配置，不用在 web.xml 里写一堆配置。页面和后端逻辑解耦之后，后续想要把前端升级成 Vue 或者 React，后端 Servlet 完全不需要改动。

项目结构上我建议这样安排：

text复制src/main/java
  └── com/example/upload
      ├── UploadServlet.java        # 接收分片的核心接口
      └── MergeServlet.java         # 分片合并与状态查询接口
src/main/webapp
  ├── upload.jsp                    # 上传页面
  └── WEB-INF/web.xml               # Servlet 3.1 之后可以用注解，web.xml 保留兜底

这里强调一点，Servlet 版本要保证在 3.1 以上，这样前端用 FormData 提交 multipart 请求时，后端可以直接用 request.getPart("file") 来获取文件流，不需要再依赖 commons-fileupload 之类的第三方库。如果是 Servlet 3.0 及以下的旧项目，后面我会单独说明兼容方案。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 前端切片：核心逻辑全部在浏览器完成

2.1 让浏览器支持“选择文件夹”

HTML 里实现文件夹选择其实非常简洁，只需要在 input 标签上增加一个 webkitdirectory 属性：

html复制<input type="file" id="folderPicker" webkitdirectory multiple />
<button id="uploadBtn">上传</button>
<div id="progressArea"></div>

浏览器对 webkitdirectory 的支持已经很多年了，Chrome、Edge、Firefox 和 Safari 桌面版都能正常使用，移动端 Safari 对文件夹选择支持有限，但桌面管理后台场景完全够用。点击选择文件夹后，input.files 返回的是一个 FileList，里面的每个文件对象除了常规的 name、size、type 属性之外，还多了一个 webkitRelativePath 属性，这个属性返回的就是该文件相对于所选文件夹根目录的完整路径。

比如你选择了一个叫 myfolder 的文件夹，里面有子目录 images，这个目录下有一张 a.png，那么这张图片的 webkitRelativePath 就是 myfolder/images/a.png。这就是我们保留文件夹层级结构的关键。

这里有一个平时不太会注意的点：FileList 本身不是数组，直接用 forEach 会报错。我一般先转成真正的数组再遍历：

javascript复制const files = Array.from(event.target.files);

之所以强调这一点，是因为后面做并发控制、统计文件总数时，你会频繁地操作这个列表，用数组的方法（filter、map、reduce）会顺手很多。

2.2 分片大小怎么定才算合理

分片的大小没有绝对标准，要根据实际网络环境和服务器配置来定。我这里给一个经验范围：

2MB：适合上传带宽较小（比如 10Mbps 以下）的场景，丢片重传成本低
5MB：最好的通用起点，服务器压力适中，请求次数不算太多
10MB：内网环境、带宽充足时可以用，减少请求数量，减轻服务器并发压力

我项目里的做法是根据文件大小动态调整分片大小，小文件用统一算法，大文件自动增大分片。具体逻辑是：

javascript复制function calcChunkSize(fileSize) {
  if (fileSize < 100 * 1024 * 1024) {
    return 2 * 1024 * 1024; // 100MB 以下：2MB 分片
  }
  if (fileSize < 1024 * 1024 * 1024) {
    return 5 * 1024 * 1024; // 1GB 以下：5MB 分片
  }
  return 10 * 1024 * 1024; // 1GB 以上：10MB 分片
}

算好分片大小之后，每个文件的分片总数就是：

javascript复制const totalChunks = Math.ceil(file.size / chunkSize);

然后通过 file.slice() 方法切割出每一片的数据。需要注意的是 slice() 的区间是左闭右开的，最后一片的大小可能不足 chunkSize，这是正常的，后端合并时只需要按顺序把所有分片拼接即可，不需要额外处理最后一片。

2.3 并发控制：不要一股脑把浏览器打爆

文件夹里可能有几十个文件，每个文件又切成几十片，如果全部同时发请求，一方面会占满浏览器的连接数，另一方面服务器的线程池会瞬间被打满，表现为页面卡死、请求超时。

我的做法是维护一个全局并发计数器，同时只允许 3 个分片在上传。每完成一个就立即取出队列里下一个，直到全部完成。简单实现如下：

javascript复制const queue = []; // 所有待上传分片
let activeCount = 0;
const MAX_CONCURRENCY = 3;

function scheduleUpload() {
  while (activeCount < MAX_CONCURRENCY && queue.length > 0) {
    const task = queue.shift();
    activeCount++;
    uploadChunk(task).finally(() => {
      activeCount--;
      scheduleUpload();
    });
  }
}

并发数设为 3 是经过实测的。并发太低，网络利用率上不去，上传速度慢；并发太高，后端合并和临时文件写入容易 IO 拥堵，反而拖慢整体速度。3 到 5 这个区间在绝大多数服务器上表现都比较稳。文件夹里全是小文件时，并发数反而可以适当调高，因为每个分片很小，请求处理时间极短。

每个分片上传时，需要在 FormData 中附带这些参数，后端才能正确识别这个分片属于哪个文件的哪个位置：

javascript复制const formData = new FormData();
formData.append("file", chunk, file.name);
formData.append("fileName", encodeURIComponent(file.name));
formData.append("relativePath", encodeURIComponent(file.webkitRelativePath));
formData.append("fileSize", file.size);
formData.append("chunkIndex", index);
formData.append("totalChunks", totalChunks);
formData.append("uuid", uploadId);

这里的 uuid 是整个上传任务的唯一标识，前端可以简单用 Date.now() + Math.random() 生成，也可以引入更严谨的 UUID 算法。同一个文件的所有分片都带相同的 uuid，后端就是靠这个字段把分片归类到同一个临时目录里的。

这里有一个我踩过的坑：文件名和相对路径里包含中文时，如果直接放到 FormData 里，后端获取后常常会出现乱码，导致合并时拼出的路径不对。最稳妥的做法是前端先 encodeURIComponent 编码，后端拿到后再 URLDecoder.decode() 解码。我会在后面的常见问题里详细展开。

3. 后端接收与合并：Servlet 里的一整套流程

后端处理分片的第一步，是先想清楚文件落地策略。我的方案里把存储分成了两个目录：

临时目录：用来存放接收到的分片文件，命名规则是 uuid/序号.part
正式目录：分片全部到齐后，按相对路径还原出目录结构，写入正式文件

临时目录建议放到系统临时目录下，比如 System.getProperty("java.io.tmpdir") 下的一个子目录。这样服务器重启时操作系统会自动清理，不会因为某个上传任务中断而残留大量垃圾文件。正式目录则放在你项目配置的上传根目录下，需要做持久化存储。

目录结构大概是这样的：

text复制/tmp/
  └── webupload/
      └── 1699999999999_abc123/       # 每个上传任务一个目录，用 uuid 命名
          ├── 0.part
          ├── 1.part
          └── 2.part

/var/data/uploads/
  └── myfolder/
      ├── images/
      │   └── a.png
      └── docs/
          └── b.pdf

临时目录与正式目录物理隔离，还有很多好处。如果用户在传输过程中关闭了页面，临时目录里的分片可以保留一段时间，下次重新上传时通过秒传校验跳过已存在的分片，这就是断点续传的基础。任务全部完成之后，再把整个临时目录递归删除，整个流程很干净。

3.2 接收分片的 Servlet 完整代码

接收分片的核心逻辑并不复杂，就是三个动作：识别参数、保存分片、返回状态。我直接给出一个可运行的实现：

java复制@WebServlet("/api/upload")
@MultipartConfig
public class UploadServlet extends HttpServlet {

    private static final String TEMP_ROOT = System.getProperty("java.io.tmpdir") 
            + File.separator + "webupload";

    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
            throws ServletException, IOException {
        request.setCharacterEncoding("UTF-8");
        response.setContentType("application/json;charset=UTF-8");

        String uuid = request.getParameter("uuid");
        String fileName = URLDecoder.decode(request.getParameter("fileName"), "UTF-8");
        String relativePath = URLDecoder.decode(request.getParameter("relativePath"), "UTF-8");
        int chunkIndex = Integer.parseInt(request.getParameter("chunkIndex"));
        int totalChunks = Integer.parseInt(request.getParameter("totalChunks"));
        long fileSize = Long.parseLong(request.getParameter("fileSize"));

        // 每个上传任务的临时目录
        File taskDir = new File(TEMP_ROOT, uuid);
        if (!taskDir.exists()) {
            taskDir.mkdirs();
        }

        // 保存当前分片
        Part part = request.getPart("file");
        File chunkFile = new File(taskDir, chunkIndex + ".part");
        try (InputStream in = part.getInputStream()) {
            Files.copy(in, chunkFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
        }

        // 返回当前进度
        File[] uploaded = taskDir.listFiles((dir, name) -> name.endsWith(".part"));
        PrintWriter out = response.getWriter();
        out.write("{\"code\":0,\"uploadedChunks\":" + (uploaded == null ? 0 : uploaded.length) 
                + ",\"totalChunks\":" + totalChunks + "}");
    }
}

这段代码里有两个细节值得展开讲。

第一，分片文件以 chunkIndex + ".part" 命名而不是用原始文件名拼接，这样在合并时只需要按文件名升序排列，就能天然得到正确的分片顺序。如果自定义命名规则，比如 filename_chunk_0.part，合并前还得解析文件名提取序号做排序，多一层不必要的复杂逻辑。

第二，这里用了 Files.copy() 的 REPLACE_EXISTING 选项，同一片重复传会自动覆盖。这个特性是实现断点续传的基础，前端在重新上传时可以先检查哪些分片已经存在，只传缺失的部分，服务器端不用做额外的去重逻辑。

3.3 分片合并与目录结构还原

所有分片都到齐后，前端发起一个合并请求。合并接口需要读取该上传任务的 uuid，然后做三件事：检查分片完整性、按顺序拼接文件、还原文件夹路径。

java复制@WebServlet("/api/merge")
public class MergeServlet extends HttpServlet {

    private static final String UPLOAD_ROOT = "/var/data/uploads";
    private static final String TEMP_ROOT = System.getProperty("java.io.tmpdir") 
            + File.separator + "webupload";

    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        request.setCharacterEncoding("UTF-8");
        String uuid = request.getParameter("uuid");
        String relativePath = URLDecoder.decode(request.getParameter("relativePath"), "UTF-8");
        String fileName = URLDecoder.decode(request.getParameter("fileName"), "UTF-8");
        int totalChunks = Integer.parseInt(request.getParameter("totalChunks"));

        File taskDir = new File(TEMP_ROOT, uuid);
        File targetDir = new File(UPLOAD_ROOT, new File(relativePath).getParent());
        if (!targetDir.exists()) {
            targetDir.mkdirs();
        }

        File targetFile = new File(targetDir, fileName);
        try (FileOutputStream fos = new FileOutputStream(targetFile)) {
            for (int i = 0; i < totalChunks; i++) {
                File chunkFile = new File(taskDir, i + ".part");
                if (!chunkFile.exists()) {
                    // 分片缺失，返回错误信息让前端补传
                    response.getWriter().write("{\"code\":1,\"msg\":\"chunk " + i + " missing\"}");
                    return;
                }
                Files.copy(chunkFile.toPath(), fos);
            }
        }

        // 合并成功后删除临时目录
        deleteDir(taskDir);
        response.getWriter().write("{\"code\":0,\"msg\":\"merge success\"}");
    }

    private void deleteDir(File dir) {
        File[] files = dir.listFiles();
        if (files != null) {
            for (File f : files) {
                if (f.isDirectory()) {
                    deleteDir(f);
                } else {
                    f.delete();
                }
            }
        }
        dir.delete();
    }
}

合并的逻辑用 FileOutputStream 加 Files.copy 逐片写入，每次只读取一个分片的大小进内存，所以即使是 2GB 的大文件，合并时服务器的内存占用也稳定在 10MB 以下，完全不用担心内存溢出。

目录还原这里有个容易忽略的点：new File(relativePath).getParent() 拿到的是文件在虚拟目录中的相对路径的父目录，如果前端传过来的 relativePath 是 myfolder/images/a.png，那么 getParent() 返回的是 myfolder/images，直接作为 UPLOAD_ROOT 的子目录创建即可，全程不会用到真实文件系统里的绝对路径，杜绝了路径穿越的安全隐患。

4. 实操中遇到的经典问题与排查方案

4.1 中文文件名乱码

这个问题几乎百分之百会遇到。前端把文件名放进 FormData 时，浏览器会按照页面编码进行传输，再加上 Tomcat 对 URL 参数的默认编码是 ISO-8859-1，中文参数到后端直接就变成了问号。

我的处理方案分三层，缺一不可：

前端传参前对文件名和相对路径做 encodeURIComponent() 编码
后端在解析参数前调用 request.setCharacterEncoding("UTF-8")
用 URLDecoder.decode() 还原文件名字符串

如果用了 encodeURIComponent，后端拿到的 fileName 参数值是经过 URL 编码的百分号形式，这时候 URLDecoder.decode(..., "UTF-8") 才会正确还原。如果是 Tomcat 8.5 及以上版本，还需要在 server.xml 的 Connector 上确认 URIEncoding="UTF-8"，否则路径参数部分还是可能乱码。

4.2 上传完成但合并时提示分片缺失

这个问题的典型表现是：前端进度条已经显示 100%，但点击“合并”按钮后后端报 chunk xx missing。

原因一般有两个。第一个是前端并发上传时，某个分片因为网络原因发送失败，但前端代码里没有做失败重试，只是简单地把这个任务从队列里移除了。第二个是后端接收分片时写文件异常，比如磁盘空间不足，但异常被吞掉了，前端还以为上传成功。

排查思路是：合并失败后先不要着急重传整个文件，而是去临时目录里看看到底少了哪几片文件。日志里记录一下缺失分片的序号，前端根据这些序号做定向补传，效率会高很多。

我当时的做法是在上传队列里给每个任务增加两次重试机会：

javascript复制async function uploadChunk(task, retryCount = 0) {
  try {
    await sendRequest(task);
  } catch (e) {
    if (retryCount < 2) {
      return uploadChunk(task, retryCount + 1);
    }
    // 超过重试次数，记录错误，等合并时统一处理
    failedList.push(task);
  }
}

重试两次能解决绝大多数的临时网络抖动问题。如果两次之后还是失败，就先记录到失败列表里，等所有正常任务上传完成后，集中对失败任务再做一轮重试。

4.3 文件夹层级结构丢失

合并完成后发现所有文件都平铺在同一个目录下，没有按文件夹的原始结构分开。这个问题多半是 relativePath 参数在传输过程中丢失或者被覆盖了。

有一种隐蔽的情况：前端在循环遍历文件列表时，如果 relativePath 是从某个全局变量里取的，而不是从当前 file 对象上取的，那所有文件的上传请求里带的 relativePath 都是同一个值，合并后自然所有文件都堆在一起。这种问题通过浏览器开发者工具打开网络面板，查看每个请求的实际提交参数就能快速定位。

另外要提醒一下，后端合并时 new File(relativePath).getParent() 依赖分隔符，跨操作系统时要格外留意。Windows 上 relativePath 的分隔符是反斜杠 \，而 Linux 上是正斜杠 /。我建议前端在提交前统一把路径里的 \ 全部替换成 /，后端用 / 作为分隔符来切分路径，这样代码在 Windows 开发机和 Linux 服务器上都能正确运行。

4.4 大文件上传时的超时问题

默认情况下，大多数应用服务器和浏览器的请求超时时间都在 30 秒左右。一个 50MB 的分片在带宽有限的情况下可能超过这个时间还没传完，请求直接被中断。

我的解决方案是对上传相关的接口做超时豁免，并配合前端的超时重试机制。后端如果是 Tomcat，可以通过在 web.xml 中给 Servlet 配置更长的 async-supported 超时时间，但更简单的做法是把分片大小调小，让每个请求能在 30 秒内完成。实际上，2MB 分片在 1Mbps 的弱网环境下大约需要 16 秒，还留有余量；如果网络连 1Mbps 都达不到，那这个上传本身就是失败的，再调小分片意义也不大。

前端这边，我给 XMLHttpRequest 设置了 60 秒的超时时间，超时自动触发重试机制。实测下来，这个策略在弱网环境下比后端单方面延长超时靠谱得多。

4.5 临时目录垃圾文件堆积

项目上线跑了一段时间后，发现服务器磁盘空间快满了，一查全是 /tmp/webupload/ 下的历史任务残留。有的上传任务用户只传了一半就关闭了页面，临时分片永远不会被合并，也就永远不会触发清理逻辑。

我的对策是写了一个定时清理任务，删除创建时间超过 24 小时的临时任务目录。实现的方式是在创建任务目录时，在目录里放一个 task.properties 文件记录任务创建时间，然后在每天凌晨调用一个清理 Servlet：

java复制File tempRoot = new File(TEMP_ROOT);
File[] taskDirs = tempRoot.listFiles();
if (taskDirs != null) {
    for (File dir : taskDirs) {
        long lastModified = dir.lastModified();
        if (System.currentTimeMillis() - lastModified > 24 * 60 * 60 * 1000) {
            deleteDir(dir);
        }
    }
}

这里用 lastModified() 有一个小问题：只要这个目录里的任何一个分片文件还在上传，目录的修改时间就会不断更新。如果你想让清理策略更精确，就以每个分片文件的最后写入时间为准，超过 24 小时没有新分片写入的任务目录才清理。

根据我个人的实测经验，这套方案上线后稳定运行了几个月，最大的一次上传是 1.8GB 的素材文件夹，包含 300 多个文件，整体耗时取决于带宽，内存占用始终没有超过 200MB，服务器负载一直很平稳。

另外再分享一个扩展思路：如果你后续想支持“秒传”和“断点续传”，只需要在上传前增加一个校验接口，把前端 fileSize 和文件内容计算的 MD5 值传给后端，后端检查正式目录中是否存在相同 MD5 的文件。存在就直接返回秒传成功；不存在就把已上传的分片序号列表返回给前端，前端只传缺失分片即可。这个改动只需要加一个接口和一个 MD5 计算工具类，对原有代码的侵入很小。