做过Web文件上传的人应该都有类似的体会:单体小文件还好,一旦遇到动辄几GB的视频素材、成百上千个文件的文件夹,用普通的multipart上传几乎必挂——要么超时,要么内存爆掉,要么传了一半网络抖动又得从头再来。我自己在给团队搭内部素材管理系统的时候,就被这个需求磨了很久。标题里提到的“JAVA网页上的文件夹结构分块上传与断点续传”,本质上就是在浏览器端把一个大文件切成若干块,逐块上传到Java后端,然后再按顺序合并,同时记录进度以便断点续传;如果是文件夹,还需要保留相对路径结构。这篇文章我会把从方案设计、前端实现到Spring Boot后端的完整落地过程讲清楚,包括怎么设计分块大小、怎么组织临时目录、怎么避免传完又合并出问题,以及那些不太容易在文档里翻到的坑。
需要说明的是,这里给的是基于常见实践的通用方案,不依赖任何特殊平台,适合大多数Java Web项目直接参考。适合正在做文件上传模块、或者被大文件传输折磨过的后端、全栈开发同学。
1. 整体方案设计与核心逻辑拆解
1.1 分块、断点续传、秒传三者是什么关系
很多人容易把分块上传和断点续传混为一谈,其实它们是三层能力:
- 分块上传:把文件按固定大小切成多个块,分别请求上传。这是基础,一切其他能力都建立在这上面。
- 断点续传:在某一块上传失败后,下次点击上传时,跳过已经存在的分块,只补传缺失的块。
- 秒传:上传前先计算文件的唯一标识(一般是内容哈希),如果服务器上已经有相同文件,直接跳过上传,返回成功。
一句话概括:分块是手段,续传是容错机制,秒传是体验优化。三者通常一起出现,因为实现路径高度重叠——分块信息天然就是“断点”的记录方式,而文件唯一标识又是判断“是否已存在”的关键。
从架构上看,我建议把整个流程拆成四个接口:
- 上传前查询:前端把文件哈希发过来,后端返回“该文件是否已存在、已存在哪些分块”。
- 分块上传:接收前端传来的单个分块数据,写入临时目录。
- 分块校验:可选接口,用于确认某个分块是否完整。
- 合并文件:前端确认所有分块上传完毕后,请求后端把临时分块合并成完整文件。
这样的设计有一个很直接的好处:前端可以随时暂停,后端不需要维护复杂状态机,所有状态都体现在“已上传分块”上。哪怕用户关掉浏览器重新打开,只要文件哈希不变,就能从已传的分块继续。
1.2 文件夹结构如何保留,临时目录如何组织
文件夹上传的核心难点不是“传”,而是“结构”。浏览器端通过input[webkitdirectory]拿到的File对象带一个webkitRelativePath属性,比如"素材/2025/宣传片/片头.mp4"。但如果只按文件名上传,到了服务端就变成一堆平铺文件,目录层级全丢了。
我的处理方式是:在上传元数据里额外传一个relativePath字段,后端把它当作虚拟路径保存。临时目录按“文件唯一标识”隔离,而不是按“用户”或“上传会话”隔离,这样同一个文件即使是不同人重复上传,分块也能共用,秒传逻辑自然就通了。
具体目录组织逻辑:
code复制{临时根目录}/{md5值}/
chunks/
chunk_00001
chunk_00002
...
{原始文件名}/{相对路径的目录结构}/
片头.mp4
字幕.srt
注意合并时的落盘方式:不要直接把分块拼成一个临时文件后再移动,而是按relativePath逐级创建目录,把合并好的文件直接写到目标路径,这样文件夹结构在落盘那一刻就已经恢复了。如果后续要把文件搬到对象存储,再循环遍历这个目录逐个上传即可。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心细节解析与实操要点
2.1 分块大小怎么定,不是越小越好
分块大小是整套方案里最重要的参数,没有之一。分块太小,比如1MB,一个2GB文件就有2048个分块,每个分块都是一次完整HTTP请求,光请求开销就大得惊人。分块太大,比如50MB,一旦网络抖动丢了,重传成本太高,而且浏览器端读取分块时的内存峰值也会上去。
我在实际项目里常用的配置是5MB到20MB之间,具体取值看业务场景:
| 场景 | 推荐分块大小 | 原因 |
|---|---|---|
| 内网传输、带宽充裕 | 20MB | 减少请求数量,吞吐率更高 |
| 公网传输、网络不稳 | 5MB | 单块失败成本低,续传粒度细 |
| 移动端或弱网环境 | 2MB~5MB | 避免长时间连接中断导致整块失败 |
如果你的文件绝大多数在200MB以内,我建议直接定10MB,这个值在大多数场景下兼顾了请求数量和重传成本,也便于计算。分块总数控制在几十到几百这个量级最舒服,后端合并时也不至于打开太多文件句柄。
另外还有一个容易被忽略的地方:最后一块的大小通常小于分块大小,这是正常的,前端代码里需要兼容这个边界,不能默认每块大小都一样。
2.2 文件唯一标识的计算:MD5全量算还是抽样算
分块上传的续传机制依赖一个稳定且唯一的标识把“同一文件”关联起来。最可靠的做法是计算整个文件的MD5或SHA-1,但大文件全量计算会占用大量时间,尤其是浏览器端,可能卡顿几秒甚至几十秒,用户感知非常明显。
我试过两种策略:
- 全量MD5:准确无误,但对大文件不友好。2GB文件在前端用JS算MD5,实测大概要5到10秒,期间页面会卡。
- 抽样哈希:只取文件头部256KB、中间256KB、尾部256KB拼接后计算MD5。速度快,基本不卡,但理论上存在极小概率的碰撞误判(两个不同文件抽样部分相同)。对于内部系统、素材管理这种场景,我倾向抽样哈希,因为在“识别同一文件”的语义下,它已经足够用了,而且还要配合文件大小做二次校验,误判率可以忽略。
这里有一个关键点:文件大小必须参与哈希计算。我在工程里会把抽样后的MD5和文件总长度拼接为fileId,格式类似md5(抽样内容) + "_" + size。这样即使抽样发生极端碰撞,大小不同也能区分。
2.3 前端并发控制:别把所有分块一窝蜂发出去
分块上传天然适合并发,但并发数不是越多越好。浏览器对同一域名的HTTP连接数是有限制的,HTTP/1.1下Chrome默认6个并发连接,强行开20个并发反而会造成排队和资源抢占。而且后端如果用的是Tomcat默认线程池,大量并发上传请求可能拖垮其他接口的响应。
我建议前端采用控制并发数的方式上传分块,并发量控制在3到6个之间。这里用简单的信号量机制就能控制,不需要引入额外依赖。如果用的是HTTP/2,并发数可以适当放宽到8到10个,但考虑到大多数内网环境还是HTTP/1.1
