C#大文件分片上传实现方法与断点续传合并文件块教程

C#大文件分片上传：从原理到实战的完整避坑指南

在C#项目中实现大文件上传，其核心流程可以概括为：客户端负责将文件切割为多个数据块并进行并发上传，服务端则负责接收、验证这些分片，并在所有分片就绪后按序合并为完整文件。然而，看似简单的逻辑背后隐藏着诸多技术细节，任何一个环节的设计疏漏都可能导致上传失败、文件损坏或性能瓶颈。

大文件分片上传必须自己管理块序号和校验

使用 HttpClient 发起多个并发 POST 请求上传文件块在技术上并不困难。真正的挑战在于，服务端如何准确识别接收到的数据块：它们属于哪个文件？顺序是否正确？数据是否完整无误？

因此，C#客户端在每次上传请求中，必须明确携带以下四个关键元数据：文件的全局唯一标识（例如 Guid）、当前分片的索引序号（chunkIndex）、总分片数量（totalChunks），以及该分片数据的哈希校验值（chunkHash）。缺少任何一项，服务端都无法可靠地完成文件重组。

实践中常见两大误区：一是仅传递 chunkIndex 而遗漏了 Guid，导致不同用户上传的同名文件分片在服务器端混杂，无法区分。二是为了简化流程而省略哈希校验，致使某个分片在传输过程中发生静默损坏，最终合并出的文件无法使用，且难以定位问题根源。

• 唯一标识是基石：切勿依赖原始文件名作为标识。建议使用 Guid.NewGuid().ToString() 为每个上传会话生成唯一ID，并在整个上传生命周期内保持一致。
• 分片大小需权衡：推荐将分片大小固定为 4 * 1024 * 1024（即4MB）。分片过小会导致HTTP请求头开销比例过高；分片过大则会使单次传输内存占用激增，且一旦失败需要重传的数据量也更大。
• 校验算法应选对：计算分片哈希时，请使用 SHA256.HashData(chunkBytes)。避免使用已被标记为不安全的 MD5 算法，尤其是在 .NET 6 及更高版本中。

断点续传靠服务端返回已上传块列表，不是客户端“记住”

许多开发者误以为断点续传只需客户端本地记录上传进度。这种方案非常脆弱——一旦应用程序崩溃、浏览器刷新或本地缓存被清除，上传状态将彻底丢失。

真正健壮的断点续传机制，其核心在于由服务端告知客户端哪些分片已成功接收。具体实现是：在上传开始前，客户端首先发起一个 GET /api/upload/chunks?fileId=xxx 查询请求。服务端根据文件ID查询持久化存储（如数据库），并返回一个已成功接收的 chunkIndex 列表。

如果服务端未提供此状态查询接口，那么所谓的“断点续传”功能将形同虚设。

• 接口设计需幂等高效：该查询接口应设计为轻量级，并充分利用HTTP缓存机制。客户端请求时可附带 If-None-Match 等缓存控制头。
• 善用ETag缓存：服务端可为响应设置 ETag（例如 ETag: "chunks-{fileId}-v1"）。当分片列表未发生变化时，直接返回 304 Not Modified，客户端即可复用本地缓存，避免不必要的网络请求。
• 精准续传缺失块：客户端解析服务端返回的JSON数组（如 [0,2,4,5]）后，即可计算出缺失的分片索引（例如1, 3, 6…），并仅上传这些缺失块，实现高效精准的续传。

合并文件块必须用 FileStream 流式写入，禁用 File.WriteAllBytes

合并环节最易犯的错误是将所有分片数据一次性加载到内存，拼接成巨大的 byte[] 后再写入文件。设想一个1GB的文件，内存占用也将接近1GB，极易引发 OutOfMemoryException 异常。

正确的做法是采用流式处理：首先以写入模式打开目标文件的 FileStream，然后按照分片索引顺序，逐个打开对应的临时分片文件，读取其数据并追加写入目标流中。

同样需要注意：读取单个分片文件时，也应避免使用 File.ReadAllBytes，对于大分片而言内存压力依然存在。推荐使用 FileStream 配合 BufferedStream 进行缓冲读取，以控制内存占用。

• 合并前务必二次校验：在将每个分片写入最终文件前，应再次校验其哈希值。任何分片校验失败，都应立即中止合并过程并抛出异常，防止生成无效的中间文件。
• 明确文件打开模式：使用 FileMode.Create 打开目标文件以确保清空旧内容；使用 FileAccess.Write 和 FileShare.None 来防止其他进程并发写入造成冲突。
• 及时清理临时文件：每个分片文件合并完成后，应立即调用 File.Delete(chunkPath) 将其删除。切勿依赖全局的清理任务，因为进程意外退出时，这些临时文件将成为磁盘空间的“僵尸文件”。

.NET 6+ 推荐用 IAsyncEnumerable 做流式分片读取

传统的 FileStream.Read 配合 while 循环进行分片读取，边界条件处理较为繁琐，例如最后一块不足4MB时容易出错。.NET 6 引入的异步可枚举流（IAsyncEnumerable）为此提供了更优雅、更安全的解决方案：

async IAsyncEnumerable ReadChunks(string filePath, int chunkSize = 4 * 1024 * 1024)
{
    await using var fs = new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.Read, 4096, true);
    var buffer = new byte[chunkSize];
    int bytesRead;
    while ((bytesRead = await fs.ReadAsync(buffer, CancellationToken.None)) > 0)
    {
        yield return bytesRead == buffer.Length 
            ? buffer.Clone() as byte[] 
            : buffer.Take(bytesRead).ToArray();
    }
}

此模式具备多重优势：首先，每次 yield return 返回的都是一个独立的新数组，避免了后续操作意外修改已返回分片的数据。其次，使用 buffer.Clone() 比重新分配 new byte[buffer.Length] 并复制数据更为高效。最后，创建 FileStream 时务必传入 FileOptions.Asynchronous 为 true，否则 ReadAsync 可能仅是同步调用的包装，无法充分发挥异步I/O的性能优势。

此外，该模式天然支持通过 CancellationToken 实现取消操作，并易于集成进度报告（在 yield 前更新进度）和 IProgress 接口。但需注意，避免在 yield return 之间执行耗时操作，否则会阻塞整个枚举流程。

最后强调一个极易被忽视却至关重要的细节：服务端计算总分片数的逻辑必须与客户端保持绝对一致。例如，双方都应使用 Math.Ceiling((double)fileLength / chunkSize) 这样的公式进行向上取整。如果一方使用向上取整而另一方使用向下取整，将导致最后一块分片的索引错位，最终合并出的文件必然是错误的。