前阵子接了个企业网盘的项目,用户量不大,但需求很具体:能在网页上直接拖入整个项目文件夹,几十个文件带着层级目录一次性传上去,而且网络不稳定时不能从头再来。我最初想着“这不就是个上传吗”,等到真做起来才发现里面的坑比预想的多。断点续传、文件夹结构还原、分块合并、并发控制、MD5计算、秒传……一串问题串下来,最后沉淀出一整套方案。如果你也在用 Java 做网页端的大文件上传,尤其是带文件夹结构的批量上传,这篇文章应该能帮你少走不少弯路。
1. 整体设计与方案选型
1.1 为什么传统表单上传撑不住文件夹场景
先说一个基础认知问题。浏览器原生的文件上传,走的是 multipart/form-data,一次请求一个文件,服务端等请求完整到达后落盘。这个模式在几十 KB 的文档、几百 KB 的图片上没问题,但放到“文件夹上传 + 大文件 + 弱网”的场景里,三个缺陷直接暴露。
第一个缺陷是浏览器默认表单控件根本拿不到文件夹内部结构。你选择 <input type="file"> 时只能拿到文件列表,没有目录树。就算用 webkitdirectory 拿到文件,也需要自己处理 webkitRelativePath。如果后端只按“一个文件对象”接收,不额外传相对路径,那目录结构到了服务端就全丢了。
第二个缺陷是中断之后全部重来。假设一个文件 500MB,上传到 90% 断网了,重新上传又得从 0% 开始。在公网环境,尤其是办公室 Wi-Fi 不稳定的情况下,这个体验完全不可接受。
第三个缺陷是服务端内存压力。传统方案里如果直接在代码里写 file.getInputStream() 然后读进 byte[],一个 500MB 的文件理论上要吃掉至少 500MB 堆内存,并发上来直接 OOM。这就是很多人说的“Java 大文件上传容易爆内存”的根源。
所以结论很直接:要做文件夹结构 + 大文件 + 可靠的批量上传,就必须放弃“整文件一次传”的思路,改成“分块 + 断点 + 目录映射”的组合方案。
1.2 分块上传与断点续传的核心思路
分块上传的计算模型其实不复杂。把一个大文件均匀切成长度固定的分块,例如每块 5MB,那么一个 500MB 的文件就有 100 块。前端逐个(或并发)把分块发送给服务端,服务端把每个分块写成独立的临时文件,所有分块都上传完成后,服务端再按顺序把这些临时文件合并成完整文件。
断点续传的做法是:前端在开始上传之前,先向服务端查询“这个文件我已经传过哪些分块了”。服务端根据自己的记录返回已上传的分块序号集合,前端跳过这些分块,只上传缺失的部分。这样一来,断网、刷新页面、关闭浏览器再回来,都能从上次断掉的位置继续。
文件夹结构的做法是:每个文件除了文件名之外,还携带一个相对路径,例如“项目资料/设计稿/首页改版-v2.fig”。服务端在合并分块时,先根据相对路径创建对应目录,再把文件写入这个目录,从而完整还原整个文件夹层级。
这三个机制互相配合,才是一个完整可用的方案。不能只做分块,不做断点;也不能只做断点,丢弃目录信息。下面我把每一步的原理和实操细节拆开讲。
1.3 技术栈选型:Spring Boot + Vue,我为什么没选现成组件
我最终用的组合是:Java 后端 Spring Boot 2.7,前端 Vue 3 + Element Plus + axios,文件分块计算用 SparkMD5。
你可能会问,前端不是有 WebUploader、Plupload 这类成熟上传组件吗,为什么不用?我以前也在项目里用过,但 WebUploader 对文件夹递归的支持不够顺手,尤其在新版浏览器下面处理 webkitRelativePath 时经常要写不少兼容代码。其次,这类组件一旦要接入自定义的断点查询逻辑、自定义合并接口和秒传判断,反而比直接封装 File API 更绕。所以我最后决定自己写一个轻量的上传调度层,只依赖 axios 和 SparkMD5,整体代码量并不大,但可控性比引第三方组件好太多。
技术上还有一点要注意:Spring MVC 自带的 MultipartFile 完全够用,不需要额外引入专门的分块上传框架。分块的本质就是接收一个 MultipartFile 和一个序号,把它写到磁盘临时目录,逻辑简单清晰。如果项目里没有特殊约束,我建议不要为了“省事”引入重量级组件,先把基础链路跑通,后面真有需要再换成更适合生产的对象存储工具。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 三个核心机制必须想清楚
2.1 分块大小怎么定:不是越大越好也不是越小越好
分块大小是整个方案里最重要、也最容易被忽略的参数。5MB 是我比较常用的默认值,但这个值不是随便拍的,需要考虑三个因素。
第一是 HTTP 服务器和反向代理的请求体大小限制。Tomcat 默认对单个 POST 请求体有限制,Nginx 的默认 client_max_body_size 是 1MB。如果你分块定成 20MB、50MB,必须同步改 Nginx 配置,否则上传请求到 Nginx 就被拦截,返回 413,前端会一脸懵。5MB 的分块通常只需要把 Nginx 的 client_max_body_size 改成 10m 或 20m,留足余量即可。
第二是网络因素。分块越大,单次请求所需时间越长,某一块在传输过程中失败的代价就越大。2G/3G 弱网环境下,5MB 一块可能要好几十秒,断了重传这一块的耗时也不小。如果面向公网弱网用户,2MB 分块会更稳;如果只在局域网内使用,10MB 也没有问题。分块太小的问题同样存在:一个 1GB 文件如果切成 1MB,那就是 1024 个请求,请求数量翻倍,服务端要处理的连接和 IO 次数也翻倍,整体吞吐反而下降。
第三是服务端合并时的成本。分块越小,合并时需要打开和读取的小文件越多,磁盘随机读写越多。5MB 分块下,1GB 文件只需要合并 200 个分块文件,这个数量级在普通磁盘上合并也就一两秒,完全可以接受。
我现在的经验公式是:局域网或内网部署用 10MB 分块,公网用户默认 5MB,弱网(移动端热点)建议 2MB。前端根据运行环境动态调整,不要写死。
2.2 文件唯一标识与断点定位:MD5之外的取舍
断点续传的前提是服务端要知道“你传的是哪个文件”。所以必须有一个文件唯一标识。最稳妥的方案是 MD5,而且是整个文件的 MD5。但这里有个现实问题:大文件在浏览器端计算完整 MD5 需要时间。一个 1GB 的文件,用 SparkMD5 分片计算,普通笔记本大概要二十秒到一分钟,这个等待体验对用户来说不够友好。
我的做法是分两级处理。第一级是“快标识”,由文件大小 + 最后修改时间 + 文件名做拼接,例如 projects-20240511-184532-104857600,用于 init 接口判断这个文件是否已经上传过;第二级是“最终校验”,在分块合并完成后,后台计算完整 MD5,和前端上传前异步算出的 MD5 比对,确保文件内容没有问题。
前端可以这样计算 MD5,按块读
