大文件分块上传的Java后端实战：从分片到合并的完整实现

1. 为什么超大附件必须分块上传

先说一个我早年踩过的坑：一个文件上传功能，页面上传一个几百MB的文件，结果Tomcat直接抛 java.lang.OutOfMemoryError: Insufficient memory，应用瞬间不可用。当时第一反应是调大JVM堆内存，但治标不治本。后来才意识到，问题不在于堆内存不够大，而在于上传方案本身就不该让大文件一次性挤进内存。

传统表单上传走的是 multipart/form-data，Servlet容器会把整个请求体读入内存或者临时文件。Spring MVC 的 MultipartFile 如果不对 max-file-size 做限制，大文件会瞬间打爆堆内存；就算你设置了 max-file-size，也会直接返回一个让人摸不着头脑的异常，用户上传的大文件根本没法落地。

分块上传的核心思路其实特别朴素：把一个大文件在客户端切成若干小块，逐个上传到服务器，等所有分块传完之后，再由服务器按顺序把分块合并成一个完整文件。整个过程中，任何时刻占用的内存、带宽、单次请求体积都是可控的。

我习惯用一个类比来解释这个方案：你往另一个城市寄一个特大号沙发，快递公司不会把整个沙发塞进一辆车里，而是拆成几个部件分车运输，到了目的地再组装。分块上传本质就是“拆件运输，到站组装”。如果你的业务涉及视频素材、高清图纸、数据库备份、安装包这类动不动几百MB甚至上GB的文件，分块上传不是可选项，而是刚需。

2. 分块上传的整体设计思路

2.1 先拆解需求：超大连附件到底卡在哪

在设计方案之前，先搞清楚超大连附件到底卡在哪几个环节。我把它拆成四个维度：

• 内存维度：整个文件一次性进入内存，JVM堆被撑爆，即使不爆也会频繁GC，拖垮整个应用。
• 超时维度：一个文件传几十分钟，无论是Nginx的 proxy_read_timeout 还是网关层的超时配置，很难容忍一个HTTP请求持续这么久，中途断线就前功尽弃。
• 网络维度：弱网环境下，一次大文件传输失败的概率随文件大小指数上升。断了就全重来，用户体验极差。
• 校验维度：大文件在传输过程中一旦出现比特位翻转、数据损坏，传统上传无法定位损坏位置，只能全量重传。

这四个维度如果不处理，无论你用多好的服务器、多大的带宽，大文件上传依然不稳。

2.2 分块上传的三个核心阶段

整个方案分成三个阶段，形成一套完整的传输闭环。

第一阶段：客户端切片

客户端读取文件，按固定大小（比如每块5MB）切成分片，每一个分片拥有独立的序号（index）。这一步不会对文件本身做任何转码或压缩，只是逻辑上的切割。在浏览器端用 File.slice() 就能做到，不需要服务端参与。

第二阶段：分片上传

客户端逐个或并发地把分片通过HTTP请求发送到服务端。服务端把每个分片先存到一个临时目录里，并记录该分片的上传状态。这一步里最关键的任务是：不合并、不校验完整性、不做额外处理，只负责接收和落盘。

第三阶段：合并与校验

当服务端确认某个上传任务的全部分片都已到位时，触发合并逻辑：按分片顺序把临时文件的内容拼接成完整文件。合并完成后计算整个文件的MD5，与客户端上报的MD5比对。一致则上传成功，不一致则说明有分片损坏，定位后补传对应分片。

2.3 关键参数怎么定

分块大小是方案里最重要的参数。它不是拍脑袋定的，需要考虑几个因素。

• 单分片太小（如512KB）：分片数暴涨，HTTP请求数量过多，网络开销和服务器处理开销都很大，反而降低效率。
• 单分片太大（如100MB）：分片上传的优势几乎消失，一旦失败重试成本很高，而且单请求需要更多内存缓冲。
• 通用选择：我实测下来，5MB-20MB是一个比较合理的区间。局域网上传可以选20MB，公网弱网环境建议选5MB，具体可以用上传测试数据来调整，不要盲从。

关于并发上传数量，不要无脑调高。浏览器对同一域名的TCP连接数有限制（HTTP/1.1通常是6个），并发上传超过这个数量并不会提速，反而会因为排队和内存占用导致页面卡死。我的建议是并发控制在3-5个，现代浏览器配合HTTP/2可以适当放宽，但收益有限。

另一个容易被忽略的参数是临时文件的存储空间。分片全部落盘到服务器，一个2GB的文件、5MB一个分片，就是400个临时文件。如果同时有几十个人上传，磁盘空间消耗非常快。必须有清理机制，超时未合并的分片要定时删除。

3. Java后端的核心实现

3.1 接口设计总览

后端需要提供三个核心接口，职责分离是设计的关键。

初始化接口十分重要却被很多人省略。有的项目不做初始化，直接让客户端把 uploadId 通过UUID自行生成传上来，这样做的缺陷在于：服务端无法在初始化阶段就知道这个文件有多大、分了多少片，也没法提前做配额校验和重复检查。

3.2 初始化上传任务

java复制@PostMapping("/upload/init")
public Result<UploadInitVO> init(@RequestBody UploadInitDTO dto) {
    // 1. 检查磁盘剩余空间，提前拒绝明显无法承载的大文件
    File storageDir = new File(storagePath);
    long usableSpace = storageDir.getUsableSpace();
    if (usableSpace < dto.getFileSize() * 2) {
        return Result.error("服务器存储空间不足");
    }

    // 2. 生成全局唯一上传ID
    String uploadId = UUID.randomUUID().toString().replace("-", "");

    // 3. 记录上传任务元数据
    UploadTask task = new UploadTask();
    task.setUploadId(uploadId);
    task.setFileName(dto.getFileName());
    task.setFileSize(dto.getFileSize());
    task.setChunkSize(dto.getChunkSize());
    task.setChunkCount(calculateChunkCount(dto.getFileSize(), dto.getChunkSize()));
    task.setMd5(dto.getMd5());
    task.setStatus(UploadStatus.INIT);
    uploadTaskMapper.insert(task);

    // 4. 创建临时分片目录
    File chunkDir = new File(tempChunkPath + uploadId);
    if (!chunkDir.exists()) {
        chunkDir.mkdirs();
    }

    UploadInitVO vo = new UploadInitVO();
    vo.setUploadId(uploadId);
    vo.setChunkCount(task.getChunkCount());
    return Result.success(vo);
}

private int calculateChunkCount(long fileSize, long chunkSize) {
    return (int) ((fileSize + chunkSize - 1) / chunkSize);
}

这里有个关键的边界处理：(fileSize + chunkSize - 1) / chunkSize 这个向上取整公式，避免了 fileSize 刚好能被 chunkSize 整除时分片数少算一块的问题。比如文件100MB、分片5MB，按直觉是20片，但用 fileSize / chunkSize 会得到20，这没问题；但如果文件100MB+1字节，100MB / 5MB 得到20，实际上需要21片，因为最后多出来的1字节也必须传一次。

3.3 上传分片接口

这是整个流程中调用最频繁的接口，它必须做到快、准、稳。

java复制@PostMapping("/upload/chunk")
public Result<String> uploadChunk(UploadChunkDTO dto,
                                  @RequestParam("file") MultipartFile file) {
    String uploadId = dto.getUploadId();
    Integer chunkIndex = dto.getChunkIndex();

    // 1. 校验分片序号是否在合法范围内
    UploadTask task = uploadTaskMapper.selectByUploadId(uploadId);
    if (task == null) {
        return Result.error("上传任务不存在");
    }
    if (chunkIndex < 0 || chunkIndex >= task.getChunkCount()) {
        return Result.error("非法分片序号");
    }

    // 2. 校验分片大小是否符合预期
    if (file.getSize() > task.getChunkSize()) {
        return Result.error("分片大小超出限制");
    }

    // 3. 落盘保存，以 uploadId/chunkIndex 命名
    File chunkFile = new File(tempChunkPath + uploadId + "/" + chunkIndex + ".part");
    try {
        file.transferTo(chunkFile);
    } catch (IOException e) {
        log.error("分片保存失败, uploadId={}, chunkIndex={}", uploadId, chunkIndex, e);
        return Result.error("分片保存失败");
    }

    // 4. 记录分片上传状态（去重处理）
    ChunkRecord record = new ChunkRecord();
    record.setUploadId(uploadId);
    record.setChunkIndex(chunkIndex);
    record.setSize(file.getSize());
    chunkRecordMapper.insertIgnoreDuplicate(record);

    return Result.success("分片上传成功");
}

为什么分片文件用 uploadId/chunkIndex.part 这种命名方式？

因为后续合并时要按分片顺序读取，如果文件名里没有序号信息，合并时就得靠数据库去查记录，或者读目录再排序，复杂度高了还容易出错。直接在文件名上带上 chunkIndex，合并时按文件名解析序号、排个序，就能稳稳地按顺序拼接。

这一阶段要小心一个坑：分片重复提交。

网络抖动时，客户端以为分片没传成功，实际上服务端已经落盘了，重试就会导致重复写入。这里用 insertIgnoreDuplicate 配合唯一索引 (upload_id, chunk_index) 解决。如果已存在，就静默忽略，客户端收到成功响应，一举两得。

3.4 合并分片文件

所有分片到位后，客户端调用合并接口。

java复制@PostMapping("/upload/merge")
public Result<String> merge(@RequestBody UploadMergeDTO dto) {
    String uploadId = dto.getUploadId();
    UploadTask task = uploadTaskMapper.selectByUploadId(uploadId);
    if (task == null) {
        return Result.error("上传任务不存在");
    }

    long start = System.currentTimeMillis();
    File chunkDir = new File(tempChunkPath + uploadId);
    File[] chunkFiles = chunkDir.listFiles((dir, name) -> name.endsWith(".part"));
    if (chunkFiles == null || chunkFiles.length != task.getChunkCount()) {
        return Result.error("分片未全部上传完成");
    }

    // 1. 按文件名中的序号排序
    Arrays.sort(chunkFiles, Comparator.comparingInt(this::extractChunkIndex));

    // 2. 逐块写入目标文件
    File targetFile = new File(storagePath + genStorageFileName(task.getFileName()));
    try (FileChannel outChannel = FileChannel.open(targetFile.toPath(),
            StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE)) {
        for (File chunkFile : chunkFiles) {
            try (FileChannel inChannel = FileChannel.open(chunkFile.toPath(), StandardOpenOption.READ)) {
                // 使用零拷贝传输，避免大文件占用堆内存
                inChannel.transferTo(0, inChannel.size(), outChannel);
            }
        }
    } catch (IOException e) {
        log.error("文件合并失败, uploadId={}", uploadId, e);
        return Result.error("文件合并失败");
    }

    // 3. 计算最终文件的 MD5，与客户端上报值比对
    String finalMd5 = FileDigestUtil.md5(targetFile);
    if (!finalMd5.equalsIgnoreCase(task.getMd5())) {
        targetFile.delete();
        return Result.error("文件校验失败，请重新上传");
    }

    // 4. 清理临时目录，更新任务状态
    FileUtil.deleteDir(chunkDir);
    task.setStatus(UploadStatus.MERGED);
    uploadTaskMapper.update(task);

    long cost = System.currentTimeMillis() - start;
    log.info("文件合并完成, uploadId={}, size={}, cost={}ms", uploadId, targetFile.length(), cost);

    return Result.success("上传成功");
}

private int extractChunkIndex(File file) {
    String name = file.getName();
    return Integer.parseInt(name.substring(0, name.indexOf(".part")));
}

3.5 合并的两种实现路径对比

合并文件有两种常见实现方式，我分别说一下优劣。

第一种是字节流拼接：用 InputStream 一个个读入，再写入目标文件。代码写起来直观，但每个字节都要经过JVM堆内存中转，文件一大就容易触发GC压力。

第二种是** FileChannel.transferTo() 零拷贝**：上面的代码用的就是这种。transferTo() 在多数操作系统上会走内核态的直接IO传输，数据不经过用户态缓冲区，合并速度和内存占用都优于字节流方式。实测合并1GB文件，零拷贝方式大约能比字节流快30%-50%，而且堆内存占用趋近于零。

4. 前端切片与配合实现

4.1 前端切片其实不难

标题侧重Java后端，但前端切片这块也得说清楚，不然整个链路没法闭环。浏览器端用的是 File.slice() 方法，代码不长：

javascript复制const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB

function sliceFile(file) {
  const chunks = [];
  let start = 0;
  let index = 0;

  while (start < file.size) {
    const end = Math.min(start + CHUNK_SIZE, file.size);
    const blob = file.slice(start, end);
    chunks.push({
      index: index,
      blob: blob,
      size: blob.size
    });
    start = end;
    index++;
  }

  return chunks;
}

切完之后，前端维护一个待上传队列，并发上传3个分片，每个分片独立成一个 FormData 发送请求。

javascript复制async function uploadChunk(uploadId, chunk) {
  const formData = new FormData();
  formData.append('uploadId', uploadId);
  formData.append('chunkIndex', chunk.index);
  formData.append('file', chunk.blob, `chunk-${chunk.index}`);

  const resp = await fetch('/upload/chunk', {
    method: 'POST',
    body: formData
  });
  return resp.json();
}

4.2 断点续传和进度显示的落地方式

前端每成功上传一个分片，就把 chunkIndex 记录到 localStorage 或内存数组中。如果过程中断，重新连接时可以先把已上传的分片列表发给后端查询，后端把已存在的分片序号返回，前端只重传缺失分片即可。

进度显示不要简单用 (已传分片数 / 总分片数) * 100%，因为文件最后一块往往小于 CHUNK_SIZE，按分片数量算进度会和实际字节数有偏差。更准的做法是：

javascript复制const totalBytesUploaded = uploadedChunks.reduce((sum, chunk) => sum + chunk.size, 0);
const progress = Math.round((totalBytesUploaded / file.size) * 100);

4.3 文件秒传的简单实现

秒传的原理不复杂：初始化上传时，后端先拿客户端上报的文件MD5去数据库查，如果存在相同MD5的文件，说明之前已经有人传过了，直接返回一个“假的上传成功”状态，前端都不用切片了。

注意：MD5的计算很耗时。一个1GB的文件，前端用 crypto.subtle.digest 计算MD5可能耗时数秒，这个时间开销是值得的，因为它能省下整个文件的上传时间。如果文件大于2GB，建议用抽样MD5（取头、中、尾各几MB计算）做初步判断，再对拍完整MD5确认，避免前端卡死。

5. 常见问题与排查技巧实录

5.1 分片序号从0还是从1开始

这个问题看起来小，但真的会坑人。我见过一个项目前端从1开始编号，后端合并时按字符串排序，“10.part”排在“2.part”前面，合并出来的文件内容顺序错乱。我的建议是：

• 分片索引统一从0开始，符合数组习惯，前后端不容易对不上。
• 文件名中的序号用数字填充到固定长度，比如 00000.part、00001.part，排序不会出错，日志排查也方便。

5.2 合并时“最后一块大小小于分片大小”的判断

很多时候，合并接口会判断“分片数量 == 总分片数”就够了，不用过度校验每个分片的大小。但如果严谨一点，可以校验最后一块的大小是否等于 fileSize - chunkSize * (chunkCount - 1)。如果客户端传的分片大小不对，很可能是切片逻辑有bug。

5.3 临时文件清理策略

临时分片目录一定要有清理策略，否则时间一长就会堆满磁盘。我常用的方案是：

• 上传任务如果超过24小时未合并，自动清理所有分片和任务记录。
• 合并成功后立即删除临时目录。
• 定期扫描临时目录，删除最后修改时间超过24小时的文件。

可以用Spring的 @Scheduled 注解做定时清理，代码不复杂，但能避免一次生产事故。

5.4 2GB以上文件的特殊情况

MultipartFile 在处理超大分片时，如果分片本身也很大（比如50MB一个），仍然建议把 spring.servlet.multipart.max-file-size 设为50MB以上，否则分片请求会被容器提前拦截。

另外注意 FileChannel.transferTo() 在部分操作系统上传输超过2GB数据时需要循环调用：

java复制long position = 0;
long remaining = inChannel.size();
while (remaining > 0) {
    long transferred = inChannel.transferTo(position, remaining, outChannel);
    if (transferred <= 0) {
        break; // 防止死循环
    }
    position += transferred;
    remaining -= transferred;
}

5.5 上传时Nginx报413 Request Entity Too Large

这个问题不在后端代码里，但很常见。Nginx默认 client_max_body_size 为1MB，路由层直接就把大请求挡掉了。需要在 server 或 location 块中调大：

nginx复制location /upload/ {
    client_max_body_size 50m;
    proxy_request_buffering off;
    proxy_read_timeout 300s;
}

注意 proxy_request_buffering off; 这个配置，它让Nginx不缓冲整个请求体再转发给后端，而是边收边转，对大文件上传非常关键。如果不关，Nginx会先把整个请求体缓存到本地，内存和磁盘都会被拖累。

5.6 多实例部署时的分片存储问题

如果你的应用部署在多个节点后面，分片落盘到本地磁盘就会出问题：第一个分片传到节点A，第二个分片被负载均衡转发到节点B，合并时就找不齐了。

解决方案通常有两种：

• 使用共享存储（NFS、OSS这类对象存储）存放分片文件，保证所有节点访问同一份数据。
• 在负载均衡层配置基于 uploadId 的会话保持（或者用一致性哈希），让同一个上传任务的请求都落到同一个节点。

如果不想引入额外的复杂度，我建议直接用对象存储存分片。云厂商的OSS/S3都提供了分片上传的SDK，Java侧用 MultipartUpload API能省掉很多自己写合并逻辑的麻烦，而且天然支持断点续传和流式上传。不过自建分片上传可以让你对流程有完全控制权，适合对数据私密性要求更高的场景。

5.7 上传中断后重新上传的幂等性

幂等设计在上传场景里容易被忽略。我的经验是：

• uploadId 一旦生成，就代表整个上传任务的标识，重复初始化时，如果传入相同的MD5且任务处于未完成状态，直接返回已存在的 uploadId。
• 重复上传同一个分片时，如果分片已经存在，直接返回成功，而不是报错。

这样即使用户卡顿后点击了两次上传按钮，也不会产生脏数据。

6. 我自己在实操过程中的几点体会

做分块上传这个功能，真正费时间的不是写代码，而是把边界情况都考虑到。上传流程中每一个条件分支，我都建议在联调阶段专门写测试用例去覆盖。

一个我印象很深的坑：在测试时发现，偶发出现了合并后文件MD5不一致的问题。查了很久才发现是文件分片上传时，某个分片在上传过程中网络抖动，客户端重试时的 chunkIndex 写错了，导致同一个分片被覆盖成错误数据。后来在客户端对每个分片单独记录上传状态，并且在上传前核对一次当前 chunkIndex 和已传列表，问题才彻底消失。

还有一个经验：分片并发数不是越多越快。我试过把并发调到8，结果浏览器端因为连接数限制，很多请求排队等待，页面内存占用反而涨了几十MB。后来固定在3-4个并发，整体速度和稳定性都更好。

另外，日志一定要记全。分片上传这种高频接口，正常排查问题的时候，如果日志里有 uploadId、chunkIndex、文件大小、耗时这些关键字段，定位问题会快很多。我有一次就是靠日志里的“某个分片耗时异常高”定位到了磁盘IO瓶颈。

最后再小声建议一句：分块上传的思路不难，但工程实现里细节非常多。只要把一个项目完整走通，后面再做其他上传需求（断点续传、秒传、进度展示）都是在这个骨架上做加法。先把临时目录、分片命名、合并排序这几个基础逻辑做扎实，剩下的都是锦上添花。