JSP老项目大文件分片上传：文件夹整包上传与断点续传完整方案-代码聚汇网

前段时间接了个内部系统的需求，业务方要求把一整年的门店巡检照片和合同扫描件归档到服务器。照片是按门店、日期、楼层分文件夹整理好的，大几十个文件夹加起来接近10个GB。传统的文件上传控件一次只能选一个文件，选完还得一个个等，传到一半断网就得重来。最后我在这套JSP老项目里落地了文件夹分片上传方案，今天把完整实现思路和踩坑记录整理出来。

这套方案的核心其实不复杂：前端用 webkitdirectory 让用户选择整个文件夹，通过 File.slice 把大文件切成若干分片，用并发请求传到后端Servlet接口，后端先落临时分片，等所有分片到齐后再按顺序合并成完整文件，并且通过 webkitRelativePath 保留目录结构。JSP页面本身只负责展示和承载前端脚本，上传的后端逻辑全部写在Servlet里。正在维护JSP老系统、或者想搞懂大文件分片上传原理的朋友，这篇文章可以直接参考。

1. 先搞清楚：文件夹分片上传到底在解决什么问题

1.1 我最常被问到的三个真实场景

我在Java Web项目里被问到最多的需求，不是登录、不是权限，而是“怎么把整个文件夹传上来”。这三个场景出现的频率最高：

第一个是内部办公系统的资料归档。业务人员电脑上一堆文件夹，按年份、项目、客户分类整理好了，需要原封不动传到服务器存档。如果用传统input文件框，只能一次选一个文件，传完还要自己建目录，操作成本极高，业务人员根本不买账。

第二个是素材包上传。运营要传一整包活动物料，里面有图片、视频、PDF、压缩包，混在同一个文件夹里，大小加起来几个GB。这类需求对上传速度有要求，不能让人盯着页面等十分钟。

第三个是后端管理系统的数据导入。比如批量导入某个月份的交易明细Excel，或者批量上传某个批次的证件照。这类文件往往命名有规律，传上去之后还要按文件夹结构做二次解析。

这三个场景的共同点就是：文件数量多、总体积大、目录层级复杂。传统的单文件上传控件根本招架不住，所以才需要专门设计一套“文件夹 + 分片”的上传方案。

1.2 分片上传为什么能解决大文件问题

网页端上传的本质是HTTP请求，而HTTP请求有一个天然的短板：请求体太大时，服务器、网关、代理都可能因为超时或者内存限制直接掐断连接。我见过不少Tomcat部署的项目，上传超过100MB的文件就报 MaxUploadSizeExceededException，要么就是传着传着页面转圈然后提示连接重置。

分片上传的思路就是不让单个请求承载太大的数据量。它把一个大文件按照固定大小切成很多个小块，比如一个500MB的文件按5MB切，能切成100片。每个分片单独发一个HTTP请求，后端逐个接收并暂存，全部到齐后再按照顺序拼接成完整文件。

这个思路用快递来类比特别好理解：一整箱书从A城寄到B城，可能因为箱子太大超重超限根本发不出去；但拆成几十个小包裹分批发，每个包裹都在限制范围内，到了目的地再按编号拆箱装订，问题就解决了。分片上传的好处不仅是绕开了请求体大小限制，更重要的是某个分片失败了只需要重新传那一个分片，不用整个文件从头再来，断点续传就是这么实现的。

1.3 在JSP项目里，这个功能的代码落在哪一层

这里要先说一个很多初学者容易踩的坑。JSP页面虽然能写Java代码，但上传这种涉及IO读写、请求处理的逻辑，千万不要直接写在JSP的 <% %> 脚本片段里。JSP本质上是View层，职责是把动态数据渲染成HTML页面，如果你在JSP里处理文件写入，代码会非常难维护，而且每次请求都要走一遍页面生命周期，性能也差。

正确的分层是：JSP页面只负责展示上传界面，内部放HTML和JavaScript代码；后端用一个Servlet专门接收上传请求，处理分片接收、文件合并、进度查询这些接口。如果项目里用了Spring MVC，那用Controller替代Servlet也是一样的道理。

JSP老项目中，Servlet的配置方式要看你项目的web.xml版本。Servlet 3.0及以上可以直接在类上写 @WebServlet("/upload/chunk") 注解，不用去web.xml里手动注册；如果是比较老的Servlet 2.5项目，就得在web.xml里配 <servlet> 和 <servlet-mapping>。我在后面第4部分会给出完整的Servlet代码，两种方式都兼顾。

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

2. 整体架构设计与关键参数选型

2.1 一条完整的上传链路

整个文件夹上传功能跑通的完整链路是这样的：

用户在JSP页面点击选择文件夹按钮，浏览器弹出目录选择框。
用户选定文件夹后，前端JS拿到文件列表，每个File对象都带有 webkitRelativePath 属性，这个属性保存了文件相对于所选文件夹的路径，比如 2025年合同/华东区/上海门店.pdf。
前端遍历文件列表，对每个文件按固定大小切片，每个分片包成一个FormData请求，带上文件标识、分片序号、总分片数等信息。
前端控制并发数，一批一批把分片POST到后端Servlet。
Servlet收到分片后，把它们暂存在服务器的临时目录中，文件名带上分片序号，方便后续排序。
所有分片传完后，前端向后端发一个“合并”请求。
Servlet校验分片数量，确认没缺失，然后按序号顺序读出分片内容写入目标文件。
写入完成后，清理临时分片文件，返回给前端合并结果。

这里面每一步看起来都不复杂，但环环相扣，任何一个环节出了问题，比如分片丢了一个、顺序乱了、目录创建不了，最终合出来的文件都会异常。所以下面几个环节需要重点关注：切片的大小怎么定、并发控制在多少合适、后端临时文件的组织方式、合并前怎么校验。

2.2 核心参数怎么定：分片大小和并发数

分片大小和并发数是整个方案里最影响体验的两个参数，我实测过几组数据，给你参考。

分片大小方面，我一般推荐 5MB。分片太小，比如1MB，意味着每个文件要发起很多次HTTP请求，请求头、响应头的开销占比太大，总传输效率反而下降。分片太大，比如50MB，遇到网络抖动时重传代价高，而且也没法有效绕开服务器的请求体大小限制。5MB是我在普通企业内网和公网环境下都比较均衡的选择，内网千兆带宽下传大文件也很快，公网慢速带宽下重传一个5MB分片也能接受。

分片大小	适合场景	缺点
1MB	弱网环境、移动网络	请求数量多，HTTP开销占比高
5MB	企业内网、普通宽带，通用推荐	无明显短板
10MB~20MB	内网高带宽、文件普遍较大	弱网下单个分片重传成本高

并发数的选择直接决定了带宽利用率和服务器压力。串行上传时，每个分片之间都有请求响应的时间空档，带宽在空转；并发数提高后，多个请求同时传输，带宽能被充分利用。但并发也不是越大越好，并发太高会让服务器频繁切换线程处理请求，反而增加整体延迟。

我的经验值是 3~5个并发。在千兆内网环境下，4个并发基本可以打满带宽；在公网环境下，4个并发配合5MB分片，上传速度能比串行快3倍左右，同时服务器也扛得住。如果你的服务器配置比较低，或者带宽只有几Mbps，并发数可以降到2；如果上传的都是超大文件且服务器性能好，可以试着开到6，但一般不建议超过8。

2.3 文件夹上传和多文件上传的本质差别

很多朋友说，我已经会做多文件上传了，文件夹上传是不是多加一个multiple属性就行。还真不是。文件夹上传比多文件上传多了一个关键问题：目录结构怎么保留。

多文件上传时，每个文件都是独立的，传上去之后只能扁平化放在目标目录里，原来的子文件夹层级全部丢失。文件夹上传的核心价值恰恰在于 webkitRelativePath，这个属性把文件在用户本地的相对路径带了过来，比如用户选了 素材包 这个文件夹，里面有 images/logo.png 和 docs/readme.txt，前端拿到的File对象就带有 素材包/images/logo.png 这样的路径信息。

后端的任务就是解析这个相对路径：合并文件时，从相对路径里取出目录部分，在服务器上递归创建对应的文件夹，然后把文件写到正确的位置。这样用户在服务器上看到的目录结构和本地完全一致。这个能力是文件夹上传和多文件上传最本质的差别，也是整个实现过程里最容易出错的地方，尤其是中文路径和文件的编码问题，我在第5部分会详细讲。

另外还需要注意一点：webkitdirectory 是Chrome、Edge、Firefox都支持的属性，但Safari对它的支持在不同版本上不一致。如果这个功能要面向外部用户，前端一定加一个能力检测，不支持的时候给个友情提示，或者降级成多文件选择加上传。内部系统如果都是Chrome，这个问题就可以忽略。

3. JSP页面前端实操：选文件夹、切片、并发上传

3.1 页面上的关键代码：webkitdirectory

先看JSP页面这一层。JSP里不需要写Java处理逻辑，只需要放HTML结构和JavaScript。核心的文件夹选择控件就是这个：

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

webkitdirectory 是让浏览器弹出文件夹选择框的关键属性。加上 multiple 是因为选择文件夹时，浏览器会把文件夹内的所有文件作为一个FileList返回，这个属性的存在能确保兼容性更好。用户选择完后，监听change事件拿到的是文件夹里所有文件的列表，而不是单个文件。

前端拿到的每个File对象里有两个关键属性：一个是 size，文件大小；另一个是 webkitRelativePath，形如 素材包/images/logo.png，这个值在后续上传和合并时非常关键，需要原样传给后端。

还需要加一个能力检测，避免不支持的浏览器里用户点了没反应还以为是bug：

javascript复制const folderInput = document.getElementById('folderPicker');
if (!('webkitdirectory' in folderInput)) {
    alert('当前浏览器不支持文件夹选择，请使用Chrome或Edge浏览器');
}

3.2 切片与并发控制实现

拿到文件列表后，就可以开始切片和上传了。下面我贴出一份可以直接落地的完整前端代码，核心逻辑都做了注释。

javascript复制const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB分片
const CONCURRENCY = 4;              // 并发数
const UPLOAD_URL = '/upload/chunk'; // 后端接口

let fileList = [];

folderInput.addEventListener('change', function (e) {
    fileList = Array.from(e.target.files);
});

uploadBtn.addEventListener('click', async function () {
    for (const file of fileList) {
        await uploadOneFile(file);
    }
});

// 根据相对路径、大小、修改时间生成一个上传任务ID
function generateUploadId(file) {
    const raw = file.webkitRelativePath + '_' + file.size + '_' + file.lastModified;
    let hash = 0;
    for (let i = 0; i < raw.length; i++) {
        hash = ((hash << 5) - hash + raw.charCodeAt(i)) | 0;
    }
    return file.webkitRelativePath.replace(/[^a-zA-Z0-9]/g, '_') + '_' + Math.abs(hash);
}

// 查询这个任务已上传了哪些分片
async function checkUploadedChunks(uploadId) {
    const resp = await fetch(UPLOAD_URL + '?action=check&uploadId=' + encodeURIComponent(uploadId));
    const data = await resp.json();
    return new Set(data.uploaded || []);
}

// 上传单个分片
function uploadChunk(uploadId, file, chunkIndex, totalChunks, blob) {
    return new Promise((resolve, reject) => {
        const formData = new FormData();
        formData.append('action', 'uploadChunk');
        formData.append('uploadId', uploadId);
        formData.append('relativePath', file.webkitRelativePath);
        formData.append('chunkIndex', chunkIndex);
        formData.append('totalChunks', totalChunks);
        formData.append('file', blob, 'chunk_' + chunkIndex + '.part');

        const xhr = new XMLHttpRequest();
        xhr.open('POST', UPLOAD_URL, true);
        xhr.onload = function () {
            if (xhr.status === 200) {
                resolve();
            } else {
                reject(new Error('分片上传失败，HTTP状态: ' + xhr.status));
            }
        };
        xhr.onerror = function () {
            reject(new Error('网络错误，分片上传中断'));
        };
        xhr.send(formData);
    });
}

// 并发控制
async function concurrentUpload(tasks, limit) {
    const queue = [...tasks];
    const workers = [];
    for (let i = 0; i < Math.min(limit, queue.length); i++) {
        workers.push(runWorker(queue));
    }
    await Promise.all(workers);

    function runWorker(q) {
        return (async function () {
            while (q.length) {
                const task = q.shift();
                await task();
            }
        })();
    }
}

// 上传一个文件的全流程
async function uploadOneFile(file) {
    if (file.size === 0) {
        console.log('跳过空文件: ' + file.webkitRelativePath);
        return;
    }

    const uploadId = generateUploadId(file);
    const uploadedSet = await checkUploadedChunks(uploadId);
    const totalChunks = Math.ceil(file.size / CHUNK_SIZE);
    const tasks = [];

    for (let i = 0; i < totalChunks; i++) {
        if (uploadedSet.has(i)) {
            continue;
        }
        const start = i * CHUNK_SIZE;
        const end = Math.min(start + CHUNK_SIZE, file.size);
        const blob = file.slice(start, end);
        tasks.push(() => uploadChunk(uploadId, file, i, totalChunks, blob));
    }

    await concurrentUpload(tasks, CONCURRENCY);

    // 所有分片传完，请求后端合并
    const mergeResp = await fetch(
        UPLOAD_URL + '?action=merge&uploadId=' + encodeURIComponent(uploadId) +
        '&relativePath=' + encodeURIComponent(file.webkitRelativePath) +
        '&totalChunks=' + totalChunks,
        { method: 'POST' }
    );
    const mergeData = await mergeResp.json();
    if (mergeData.code !== 0) {
        throw new Error('文件合并失败: ' + file.webkitRelativePath);
    }
    updateProgress(file.webkitRelativePath);
}

这里有几个要点需要说明。

第一，generateUploadId 这个函数生成的是一个任务唯一标识。我用了“相对路径 + 大小 + 最后修改时间”拼起来做个简单的哈希。它不涉及读取文件内容，所以速度非常快。有些方案会计算文件的MD5作为唯一标识，但大文件算MD5要读取整个文件内容，几百MB甚至几个GB的文件会卡住页面好几秒，用户体验很差，我没采用。

第二，为什么用 XMLHttpRequest 而不是 fetch。因为上传场景需要依赖 xhr.upload.onprogress 事件来展示上传进度，虽然fetch也能实现，但XHR的进度事件支持更加稳定，代码语义也更清晰。而且FormData配合XHR发送文件，几乎不需要额外处理Content-Type，浏览器会自动带上 multipart/form-data 边界。

第三，并发控制这里用了一个简单的worker池模式。先启动固定数量的worker，每个worker从任务队列里取任务执行，取完再去取下一个。这个方案比 Promise.all 一次性发出全部请求要稳得多，因为如果10个分片一次性发出，服务器同时收到10个请求，在高并发场景下容易把Tomcat线程池打满。

3.3 断点续传的前端配合

断点续传是分片上传方案天然自带的价值，因为分片是独立上传的，任何一个分片失败都不会影响其他分片。但要让断点续传真正可用，前端必须在每次上传前做一次“已上传分片查询”。

代码里我已经写好了 checkUploadedChunks 函数。它的逻辑是：在开始上传前，先拿着uploadId去后端查一下这个任务已经收到了哪些分片序号，返回一个Set集合。遍历切片时，如果某个分片的序号已经在这个Set里，就直接跳过，不用重复上传。

这个机制解决了一个很实际的问题：传了80%的时候网络断了，刷新页面重新选择文件夹，程序发现前面80%的分片已经在服务器上了，只需要补传剩下的20%，然后直接合并。对大文件来说，这个体验的提升是非常明显的。

需要提醒的是，断点续传依赖后端的查询接口和临时分片的保留。如果服务器上设置了定时清理临时分片的任务，清理周期内断点续传才有意义，如果临时分片被清了，前端查询到的已上传列表就是空的，只能全量重传。这个我在第5部分的临时文件清理策略里会详细说。

3.4 上传进度怎么展示

进度展示这块可以根据项目需求做简单或复杂。简单的方式是每个文件传完后再更新一次页面，展示“已完成 12/58 个文件”；复杂一点可以用 xhr.upload.onprogress 实现实时进度条。

监听上传进度的事件代码很简单，在 uploadChunk 函数里加一行：

javascript复制xhr.upload.onprogress = function (e) {
    if (e.lengthComputable) {
        const percent = Math.round((e.loaded / e.total) * 100);
        // 更新页面上对应的进度条
    }
};

注意这个 e.loaded 是单个分片的已传输字节数，不是整个文件的。如果你要展示“当前文件上传到68%”，需要用 “已上传的分片数 + 当前分片的进度占比 / 总分片数” 来换算。如果只是展示总体的“已传了多少个文件”，那直接在每个文件合并成功后更新计数就行。

如果文件数量很多，我建议前端做两层进度：一层是文件总进度，显示当前是第几个文件、剩余多少个；另一层是当前文件的进度条。这样用户心里有数，不会以为页面卡死了。

4. Servlet后端实操：接收分片与合并文件

4.1 后端接口设计概览

后端我设计成一个Servlet统一处理三个动作，通过 action 参数区分。这种方式在JSP老项目里最省事，不用配一堆Servlet，web.xml里只加一个映射就行。

接口action	请求方式	作用
uploadChunk	POST	接收一个分片，保存到临时目录
merge	POST	所有分片到齐后，合并出完整文件
check	GET	查询某上传任务已收到的分片序号

Servlet的入口如下：

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

    private static final String TEMP_BASE = "/data/upload_temp/";
    private static final String FILE_BASE = "/data/upload_files/";

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

        String action = request.getParameter("action");
        if ("uploadChunk".equals(action)) {
            handleUploadChunk(request, response);
        } else if ("merge".equals(action)) {
            handleMerge(request, response);
        } else {
            writeJson(response, "{\"code\":1,\"msg\":\"unknown action\"}");
        }
    }

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

        if ("check".equals(request.getParameter("action"))) {
            handleCheck(request, response);
        } else {
            writeJson(response, "{\"code\":1,\"msg\":\"unknown action\"}");
        }
    }
}

如果你的项目用的是Servlet 2.5，没有 @WebServlet 注解可用，那就需要去web.xml里配映射：

xml复制<servlet>
    <servlet-name>chunkUpload</servlet-name>
    <servlet-class>com.example.UploadServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>chunkUpload</servlet-name>
    <url-pattern>/upload/chunk</url-pattern>
</servlet-mapping>

4.2 接收分片：temp目录落盘

接收分片是这个Servlet里最核心的方法。前端传来的FormData里有五个参数：action、uploadId、relativePath、chunkIndex、totalChunks，外加一个文件Part。后端要做的事情是：以uploadId为目录名创建临时目录，把当前分片写入这个目录。

注意分片文件名的设计非常关键。我用的是 uploadId + "_" + chunkIndex + ".part" 这种格式，因为后面合并时需要根据chunkIndex排序，文件名里带上序号可以很方便地解析出来。分片文件本身不需要保留原始文件名，真实文件名在relativePath里，合并的时候再取出来用。

java复制private void handleUploadChunk(HttpServletRequest request, HttpServletResponse response)
        throws IOException, ServletException {
    String uploadId = request.getParameter("uploadId");
    String relativePath = request.getParameter("relativePath");
    int chunkIndex = Integer.parseInt(request.getParameter("chunkIndex"));
    int totalChunks = Integer.parseInt(request.getParameter("totalChunks"));

    if (uploadId == null || !uploadId.matches("[a-zA-Z0-9_]+")) {
        writeJson(response, "{\"code\":1,\"msg\":\"invalid uploadId\"}");
        return;
    }

    Part filePart = request.getPart("file");
    if (filePart == null) {
        writeJson(response, "{\"code\":1,\"msg\":\"file part missing\"}");
        return;
    }

    File chunkDir = new File(TEMP_BASE, uploadId);
    if (!chunkDir.exists()) {
        chunkDir.mkdirs();
    }

    File chunkFile = new File(chunkDir, uploadId + "_" + chunkIndex + ".part");

    try (InputStream in = filePart.getInputStream();
         FileOutputStream out = new FileOutputStream(chunkFile)) {
        byte[] buffer = new byte[8192];
        int len;
        while ((len = in.read(buffer)) != -1) {
            out.write(buffer, 0, len);
        }
    }

    int uploadedChunks = countChunks(chunkDir);
    writeJson(response, "{\"code\":0,\"uploadedChunks\":" + uploadedChunks + ",\"totalChunks\":" + totalChunks + "}");
}

这个方法用到了Servlet 3.0的 request.getPart("file") 接口，Tomcat 7.0及以上都支持。如果你的生产环境是比较老的Tomcat 6，没有Part接口，那就得改用Apache Commons FileUpload组件，代码会稍微绕一些，但思路完全一致。

分片落盘之后，临时分片直接以文件形式写在服务器上，不占Java堆内存。这一点要特别注意：如果把分片读到byte数组里再写文件，大文件几十个分片同时上传，内存很快会被撑爆，Tomcat直接OutOfMemory。所以一定要用流的方式，边读边写。

4.3 合并文件：顺序校验与写入

合并是另一个重头戏。前端在所有分片传完后调用merge接口，后端要做的第一件事是校验分片是不是真的齐了。校验的方法很简单：统计临时目录里 .part 文件的数量，跟前端传上来的 totalChunks 做比较，不相等直接拒绝合并。

这里有个细节我踩过坑：File.listFiles() 返回的文件顺序是不确定的，千万不能拿这个顺序直接当分片顺序合并。必须先从文件名里解析出 chunkIndex，按照序号从小到大排好序，再依次写入。

合并的完整代码：

java复制private void handleMerge(HttpServletRequest request, HttpServletResponse response)
        throws IOException {
    String uploadId = request.getParameter("uploadId");
    String relativePath = request.getParameter("relativePath");
    int totalChunks = Integer.parseInt(request.getParameter("totalChunks"));

    File chunkDir = new File(TEMP_BASE, uploadId);
    if (!chunkDir.exists()) {
        writeJson(response, "{\"code\":1,\"msg\":\"chunk dir not found\"}");
        return;
    }

    File[] parts = chunkDir.listFiles((dir, name) -> name.endsWith(".part"));
    if (parts == null || parts.length != totalChunks) {
        writeJson(response, "{\"code\":1,\"msg\":\"chunks incomplete, expected "
                + totalChunks + ", got " + (parts == null ? 0 : parts.length) + "\"}");
        return;
    }

    // 解析出每个分片的序号，按序号升序排列
    Arrays.sort(parts, (a, b) -> {
        int idxA = parseChunkIndex(a.getName());
        int idxB = parseChunkIndex(b.getName());
        return Integer.compare(idxA, idxB);
    });

    // 安全校验：目标文件必须落在基础目录之内
    File target = new File(FILE_BASE, relativePath);
    String canonicalBase = new File(FILE_BASE).getCanonicalPath();
    String canonicalTarget = target.getCanonicalPath();
    if (!canonicalTarget.startsWith(canonicalBase + File.separator)) {
        writeJson(response, "{\"code\":1,\"msg\":\"invalid relativePath\"}");
        return;
    }

    File parentDir = target.getParentFile();
    if (parentDir != null && !parentDir.exists()) {
        parentDir.mkdirs();
    }

    try (FileOutputStream fos = new FileOutputStream(target)) {
        byte[] buffer = new byte[8192];
        for (File part : parts) {
            try (FileInputStream fis = new FileInputStream(part)) {
                int len;
                while ((len = fis.read(buffer)) != -1) {
                    fos.write(buffer, 0, len);
                }
            }
        }
    }

    deleteDirectory(chunkDir);

    writeJson(response, "{\"code\":0,\"path\":\"" + target.getPath() + "\"}");
}

private int parseChunkIndex(String fileName) {
    // 文件名格式: uploadId_0.part
    String[] arr = fileName.split("_");
    String last = arr[arr.length - 1];
    return Integer.parseInt(last.replace(".part", ""));
}

合并时每个分片末尾之间不能有多余的换行符或者分隔符，直接把分片的二进制流按顺序拼接写进目标文件就行。前端切片的时候用的是 file.slice(start, end)，切出来的每个blob是不包含任何额外信息的原始二进制数据，所以后端无脑拼接就能还原出原始文件。

关于合并后临时分片目录的清理，我是在合并成功之后直接删掉整个 chunkDir 目录。这里要注意，如果合并过程出错，比如某个分片文件读不出来，尽量不要删除临时目录，保留现场方便排查问题。所以我是在合并成功后再调 deleteDirectory。

4.4 断点续传的查询接口

最后是check接口，它支撑了断点续传和秒传的能力。实现逻辑很简单：读取临时目录下所有 .part 文件，从文件名里解析出分片序号，排好序返回给前端。

java复制private void handleCheck(HttpServletRequest request, HttpServletResponse response)
        throws IOException {
    String uploadId = request.getParameter("uploadId");
    if (uploadId == null || !uploadId.matches("[a-zA-Z0-9_]+")) {
        writeJson(response, "{\"code\":1,\"msg\":\"invalid uploadId\"}");
        return;
    }

    File chunkDir = new File(TEMP_BASE, uploadId);
    List<Integer> uploaded = new ArrayList<>();

    if (chunkDir.exists()) {
        File[] parts = chunkDir.listFiles((dir, name) -> name.endsWith(".part"));
        if (parts != null) {
            for (File part : parts) {
                uploaded.add(parseChunkIndex(part.getName()));
            }
        }
    }

    Collections.sort(uploaded);
    StringBuilder sb = new StringBuilder();
    sb.append("{\"code\":0,\"uploaded\":[");
    for (int i = 0; i < uploaded.size(); i++) {
        if (i > 0) sb.append(",");
        sb.append(uploaded.get(i));
    }
    sb.append("]}");
    writeJson(response, sb.toString());
}

这个接口配合前端 checkUploadedChunks 函数使用。前端拿着uploadId来查询，返回的集合里有哪些序号，前端就跳过哪些分片。要注意的是，uploadId 是基于文件相对路径、大小、修改时间生成的，如果用户上传完80%后修改了文件内容，文件大小或者修改时间变了，生成的uploadId也会变，后端查不到旧的分片，自然就会全量重传。这个行为是合理的，因为内容变了，旧分片确实不能复用。

5. 常见问题与排查实录

5.1 中文文件名乱码问题

这是JSP老项目里最常见的坑。用户在本地建了一个 2025年合同 文件夹，里面的文件名也是中文，传到服务器后发现文件名变成了一堆乱码，更严重的直接导致合并后文件路径错误。

乱码的根源在于编码不一致。前端FormData提交时默认按UTF-8编码，后端Servlet必须显式调用 request.setCharacterEncoding("UTF-8") 才能正确解码中文字段。我在Servlet入口已经写上了这一行。还有一个需要注意的地方是，如果前端在URL参数里传中文的relativePath，比如merge接口里用 encodeURIComponent(file.webkitRelativePath) 转义了，后端拿到的已经是UTF-8编码后的值，用 request.getParameter 读出来应该没问题。但Tomcat的GET参数解码默认不是UTF-8，需要在Tomcat的 server.xml 里给Connector加上 URIEncoding="UTF-8"，否则URL中的中文参数照样乱码。

如果你做的项目是Spring MVC，还需要检查Spring的CharacterEncodingFilter是否配置了 forceEncoding=true。我之前排查过一个问题，filter配了但用的是默认编码ISO-8859-1，前端传中文文件名进来全是问号，改完forceEncoding之后问题消失。

5.2 合并后的文件大小不对或者文件损坏

这类问题的现象是：文件传完了，合并也提示成功，但打开文件发现损坏了，或者文件大小比原本少了几KB甚至少一个完整分片。我排查这种问题的心得是先把问题分两类。

第一类是文件正好少了几个分片的大小。这种通常是前端并发上传时有几个请求失败了，但前端没有正确捕获错误，仍然调用了merge接口。解决方法是前端在并发上传后加一层严格的判断：合并请求发出前必须确认所有分片都已成功，不要依赖后端合并时的数量校验兜底，因为后端校验发现分片缺失会返回错误，但用户体验已经很差了。

第二类是文件大小和原始文件一致，但文件内容错乱。这种情况九成是合并顺序弄错了，分片没有按序号排序，而是用了 File.listFiles() 的随机顺序。我在4.3节的代码里特意用了 Arrays.sort 加上自定义比较器，就是为了避免这个坑。顺带说一下，有些文件因为格式特殊，即使在错误的位置插入了其他分片也能打开，但内容已经错乱，这种最迷惑人，排查时一定要对比文件大小和哈希值。

5.3 路径穿越与安全校验

这个坑比较隐蔽，但影响非常大。用户选择的文件夹里可能存在起名特殊的文件，比如 ../../../../etc/passwd，正常情况下用户不会这么起名，但恶意用户可以构造一个包含路径穿越的文件名上传。如果后端直接拿 relativePath 拼路径，就有可能导致文件写到服务器的任意目录，跟经典的zip解压路径穿越漏洞一样。

解决方案在合并代码里已经写了：合并前用 getCanonicalPath() 规范化路径，然后校验规范后的路径是否以基础目录开头，不是就拒绝。这段校验不能省，因为 ../ 在路径拼接时会被操作系统直接解析，如果你只过滤字符串开头的 ../，遇到中间夹着 a/../../ 这种组合还是可能绕过。用 getCanonicalPath() 让系统帮你规范化，再比对前缀，是最稳妥的做法。

uploadId 也要做白名单校验。我在接收分片的代码里加了 matches("[a-zA-Z0-9_]+") 的判断，因为uploadId会作为临时目录名，如果前端传一个包含 ../ 的uploadId，同样会造成目录穿越。前端 generateUploadId 生成的时候已经过滤掉了特殊字符，但后端接口是公开的，不能假设调用方一定是我自己的前端，接口层该做的校验一步都不能少。

5.4 临时分片的清理策略

临时分片不清理会带来两个问题：一是磁盘空间被蚕食，用户传一半放弃的文件，分片会一直留着；二是上传任务多起来后，临时目录里的文件成千上万，影响文件系统性能。

我在实际项目里用了两个清理机制配合。第一个是合并成功后立即删除对应临时目录；第二个是定时清理过期临时目录，每天晚上凌晨跑一个定时任务，删除所有修改时间超过24小时的临时目录。

定时任务这块，简单项目可以直接写一个Java类，用 Timer 或者Spring的 @Scheduled 注解定时执行。如果项目没有定时任务框架，也可以用操作系统的cron跑一个清理脚本，把清理逻辑从Java代码里解耦出去。清理脚本的逻辑不复杂：遍历临时目录下的所有子目录，检查每个目录的最后修改时间，超过24小时的就整个删掉。

bash复制#!/bin/bash
find /data/upload_temp/ -mindepth 1 -maxdepth 1 -type d -mtime +1 -exec rm -rf {} \;

这个清理周期要和断点续传的预期匹配。如果你把清理周期设成1小时，用户传了30%之后隔了2小时回来继续传，临时分片已经被清了，断点续传就失效了。我建议服务端临时分片的保留时间至少设置24小时，对绝大多数业务场景来说都够用了。

5.5 跨浏览器兼容性与降级方案

webkitdirectory 在Chrome、Edge、Firefox上都能正常工作，但Safari的支持在不同系统版本上差别很大。如果你要兼容Safari，前端得做能力检测，检测不到就降级成普通的多文件上传，这时候 webkitRelativePath 属性不存在，就用文件本身的name代替，上传后直接放到目标目录下，不保留文件夹层级。

另外一个小细节是空文件夹的问题。文件夹里如果有个空子文件夹，前端拿到的FileList里根本不会有这个空文件夹对应的条目，因为浏览器只返回文件不返回目录。如果你需要连空文件夹也一并创建，得在前端做额外的目录检测，或者在后端合并时根据 relativePath 的目录部分自动创建，空文件夹场景一般很少用到，实在需要可以单独写一个“新建文件夹”的接口，让用户手动补建。

最后分享一点我个人在实际项目里的体会

这套分片上传方案我在JSP老项目里落地过，也移植到Spring Boot项目里用过，核心代码基本不用改。前端代码是纯JavaScript和HTML，跟后端框架无关；后端只要是一个能接收文件Part、能操作文件流的Servlet或者Controller都能承接。

真要说哪个环节最值得多花时间测试，我建议把精力放在弱网环境下的容错上。我在测试时用Chrome的Network面板模拟了各种网络条件，发现分片上传在弱网下的表现比大文件整体上传稳定得多，但前端对错误的处理一定要做足：每个分片上传失败要支持重试，连续失败多次要报错提醒用户，不能静默吞掉。我见过一些项目分片上传功能能跑通，但一断网就整个页面卡死，就是因为前端没做错误捕捉。

这套方案后续还可以继续扩展：给文件计算MD5，后端发现相同内容的文件已经存在就直接返回秒传；把临时分片存到云存储的临时目录，合并逻辑放在云端去做，服务器本地就不需要保留大文件；或者在前端加一个上传队列管理，支持暂停和恢复。分片上传的本质就是把复杂问题拆解成若干个可独立处理的小块，围绕这个思路，能做的优化方向非常多。

JSP老项目大文件分片上传：文件夹整包上传与断点续传完整方案