做Java网页开发这些年,文件上传这块我踩过的坑确实不少。尤其是超大附件,动辄几个G的安装包、素材压缩包、音视频文件,直接走普通表单提交,十有八九传不完:请求超时、内存溢出、中途断连、进度条卡死,用户只能咬牙从头再来。今天我把处理超大附件分段上传与断点续传的一套完整方案整理出来,从设计思路到前后端代码,再到实战中的坑,一次性讲清楚。这套方案适用于自建服务器、文件存储服务,也能迁移到对象存储的分片上传场景,适合正被大文件上传折磨的Java后端开发人员和全栈工程师参考。
1. 先看透超大附件直传的痛点,再谈分段上传
1.1 大文件直传为什么总是失败
很多人第一次接触大文件上传时,第一反应是“不让传就调大限制”。于是Spring Boot里把 spring.servlet.multipart.max-file-size 和 max-request-size 拉到10G,Nginx的 client_max_body_size 也同步放大。结果呢?文件小的时候没事,一旦到了几个G,问题接踵而至。
第一个是请求超时。浏览器和服务端之间隔着一层层代理,Nginx默认的 proxy_read_timeout 通常只有60秒,Tomcat默认的连接超时也不长。大文件传输过程中,只要某个环节卡了那么一下就断,整个请求直接失败。用户看到“上传失败”四个字,只能重新来。
第二个是内存压力。Java后端处理上传时,MultipartFile 虽然走的是临时文件落盘,但框架在解析请求、转换数据时依然要吃大量内存。并发上来之后,多个大文件同时上传,堆内存瞬间被打满,常见的 java.lang.OutOfMemoryError: Java heap space 就是这么来的。很多服务器配置不高,几个并发大文件就能把进程拖死。
第三个是重传代价太高。大文件一旦失败,全部重来,带宽、时间、用户耐心全部被消耗掉。这也是直传模式最让人头疼的地方——失败不可怕,可怕的是没有“恢复能力”。
1.2 分段上传解决的是什么
分段上传(也叫Chunk Upload)思路很直接:把一个大文件在前端切成若干个固定大小的分片,一片一片传给后端。每片都是独立的HTTP请求,独立成功或失败。所有分片传完后,后端再按顺序拼接成完整文件。
它能解决三件事:把“一个很长的请求”拆成“很多个短请求”,每个请求控制在几秒到十几秒内返回,规避超时问题;每片内存占用可控,避免大文件整体读入堆内存;失败时只需要重传失败的那一片,而不是整个文件。配合断点续传,用户中断后再次上传,只要文件标识不变,已经传完的分片可以直接跳过,体验完全是两个档次。
分段上传也不是万能的。它解决不了服务器磁盘空间不足、带宽瓶颈、文件校验缺失这些基础问题。分段只是把大任务拆小了,合并后的完整性校验、临时分片的磁盘清理仍然要自己做。想清楚这一点,后续设计才不会跑偏。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 分段上传与断点续传的方案设计与核心细节
2.1 分片大小怎么定
分片大小是方案设计里最先要拍板的事。片太大等于没拆,片太小请求数量惊人。假设一个21G的文件,按不同分片大小看请求数量:
| 分片大小 | 分片数量 | 单次失败重传代价 | 适用场景 |
|---|---|---|---|
| 1MB | 约21504个 | 很低,但请求太多,网络往返开销大 | 极不稳定网络 |
| 5MB | 约4301个 | 较低,请求数量可接受 | 通用外网 |
| 10MB | 约2151个 | 中等,数量与代价平衡 | 推荐,通用场景 |
| 50MB | 约431个 | 较高,单次失败重传代价大 | 内网高带宽 |
我在项目里用得最多的是10MB。原因是外网环境下,10MB的单个请求传输时间通常在几秒到几十秒之间,既能避开代理超时,又不会因为分片太多导致HTTP请求开销过大。内网带宽足、网络稳定,可以放大到50MB甚至100MB,降低请求数量。另外还要考虑浏览器对同域并发连接数有限制,现代浏览器一般在6个左右,分片太小会导致大量排队,实际吞吐反而上不去。
2.2 续传的关键:文件唯一标识
断点续传实现的前提,是能够判断“这次上传的文件”和“上次没传完的文件”是不是同一个。浏览器本地文件通常用 文件大小 + 最后修改时间 来区分,为了更稳妥,也可以把文件名拼接进去,生成一个字符串,然后做哈希得到 fileId。
不要用文件名直接当标识。同名文件内容可能完全不一样,用户稍作修改再传一次,就会和后端残留的旧分片混在一起,导致合并后文件损坏。我用的是类似这样的生成规则:
javascript复制const raw = file.name + '_' + file.size + '_' + file.lastModified;
const fileId = md5(raw);
前端在开始上传前,先调用后端接口查询这个 fileId 下已传完的分片索引,然后跳过这些分片,只传缺失的部分。这就是断点续传的全部秘密——不是魔法,而是“记录 + 跳过”。
2.3 前后端的分工与交互流程
整个上传流程,前后端的职责要划分清楚,否则很容易写出乱糟糟的接口。
前端负责:读取文件、计算 fileId、切片、查询已上传分片、控制并发上传、展示进度、在失败后重试缺失分片、全部完成后触发合并。
后端负责:接收单个分片、按 fileId 和分片索引存储、提供一个查询接口返回已上传分片索引、提供一个合并接口把所有分片拼成完整文件、合并时校验文件完整性、补充清理临时分片。
交互流程看起来是这样的:
- 用户选择文件,前端计算
fileId。 - 前端调用查询接口,拿到已上传分片索引列表。
- 前端切片,跳过已上传的分片,按并发控制批量上传缺失分片。
- 全部完成后,前端调用合并接口。
- 后端合并分片并返回最终文件信息。
3. 后端实现:接口设计、分片存储与合并逻辑
3.1 分片存储结构如何设计
后端落地分片时,我建议用这个目录结构:
text复制/data/upload/temp/{fileId}/{chunkIndex}.part
/data/upload/temp/{fil
