网页大文件分片上传与断点续传：前端JS切片、后端C#合并全解

去年给公司内部做资料库系统的时候，用户经常要传几百MB甚至几个GB的安装包和日志包。最开始我想得太简单，直接写了个普通HTTP上传接口，本机测试一切正常，结果一上生产就被连续打脸：传到一半网关超时断开、服务器报413、用户重传又得从头开始。后来老老实实把方案改成分片上传加断点续传才算消停。这篇就把整套方案完整拆一遍，覆盖前端JS如何切片、后端C#如何接收合并、断点续传怎么设计，以及我实际踩过的坑。

先回应一个容易混淆的点：标题说"网页上C#代码"，但浏览器端真正负责切片的只能是JavaScript。除非你上Blazor WebAssembly把C#编译成WebAssembly跑在浏览器里，否则生产上99%的玩法是前端JS切片、后端用ASP.NET Core（也就是C#）接收和合并。Blazor方案对于几个GB的文件并不现实，因为它的File API流式读取能力很弱，做不到按偏移量随机切片。所以下面这套架构，就是JS做切片和断点续传调度，C#处理文件落盘、合并、校验，一前一后把事情接住。

1. 为什么“直传整个文件”在本机通、上了生产就挂

1.1 三个硬限制：超时、请求体上限、失败重试的成本

本机环境里，浏览器和IIS/Kestrel之间没有网关，没有反代，你传一个1GB的文件最多就是慢一点，不会断。生产环境完全不是这样。

第一个坑是网关超时。Nginx默认的proxy_read_timeout是60秒，IIS也有连接超时配置。用户的网络上行速度如果是2MB/s，传1GB理论需要512秒，早就超过超时阈值了。连接一旦被杀，请求直接失败，不管你传了多少。

第二个坑是服务器请求体大小限制。ASP.NET Core的Kestrel默认请求体上限大约是30MB，IIS的maxAllowedContentLength默认也是30MB左右。你传一个超过30MB的请求，Kestrel直接返回413，IIS干脆连请求都不给进。本机调试时为什么没发现？因为本机通常没有IIS限制这一层，而Kestrel限制可以通过RequestSizeLimit特性临时放开，传着传着就把这个限制忽略了。

第三个坑是失败重传的代价。直传方案下，1GB文件传到95%断开，用户就得从0%重传。如果用户网络本来就不稳定，或者中途切了Wi-Fi、锁了屏，一次都传不完。我曾经测过一个场景：手机热点传给服务器，1GB文件连续尝试5次，没有一次能完整传完。这已经不是技术问题了，是用户体验直接崩盘。

1.2 分片能解决什么，不能解决什么

分片的核心思路很简单：把1GB文件切成100个10MB的小块，每次只传一小块，单块请求时间短，超时风险小，失败后只需要重传那一小块，不用从头再来。

它能解决超时问题，能解决请求体限制问题，也能把失败重试的代价从“1GB”降级到“10MB”。但它不能解决带宽不够的问题，也不能解决服务器磁盘满了的问题。换句话说，分片是为了让上传过程更健壮，而不是让网络更快。这个预期要先摆正，不然你后面优化方向会跑偏。

2. 整体方案定案：分片大小、文件标识与续传状态设计

2.1 分片大小为什么选10MB

分片大小直接影响请求数量和续传粒度。片太小，比如1MB，1GB就是1000个请求，HTTP握手和表单解析的开销会吃掉大量时间；片太大，比如100MB，一个片传起来还是要几十秒，超时风险又回来了。

我最终选了10MB。理由有三个：一是10MB远小于Kestrel和IIS的默认30MB限制，就算不调大服务器限制也能先跑通；二是1GB文件切100片，请求数量可控；三是断点续传的粒度是10MB，用户重连后最多重传10MB，体感可以接受。如果你要传的文件普遍是10GB以上，可以把分片调到20MB甚至50MB，但不能超过网关的请求体限制，这是一个联动关系。

2.2 三个接口与状态约定

我设计的接口只有三个，没有引入数据库，也没有引入消息队列，整个方案把依赖降到了最低：

这里的核心变量是uploadId。前端在上传开始时生成一个GUID，作为这个文件在服务端的唯一标识。所有分片、状态查询、合并请求都围绕这个uploadId展开。服务端临时目录结构是：

uploadTemp/ {uploadId}/ chunks/ 0.part 1.part 2.part ... meta.json

meta.json记录文件原始名称、总分片数、文件大小。分片文件统一用数字索引作为文件名，后面会讲为什么必须这么做——这直接关系到路径穿越的安全性。

2.3 一个关键认知：网页端的切片逻辑是JavaScript，C#在服务端

再强调一次，避免后面代码看不懂：浏览器端切片用的是File.slice()，这是JavaScript的API。C#全程是在服务端处理分片落盘、状态查询、合并。如果你非要在浏览器端也跑C#，那就得用Blazor WebAssembly，但Blazor对超大文件的支持很弱，而且首次加载就要下载好几MB的运行时。我个人的建议是别纠结这个，JS做前端切片、C#做后端处理，是这个场景下工程上最成熟的组合。

3. 前端切片与上传：File API、整体进度与并发控制

3.1 File.slice切出一块10MB的Blob

用户通过<input type="file">选中文件后，前端拿到的是一个File对象。File继承自Blob，所以可以直接用slice(start, end)按字节区间切出子Blob，整个过程不需要把文件完整读进内存，浏览器底层的Blob实现是懒读取，只有在真正发送时才会读磁盘对应区域。对1GB文件来说，这个开销是可接受的。

const file = document.getElementById('fileInput').files[0]; const CHUNK_SIZE = 10 * 1024 * 1024; // 10MB const totalChunks = Math.ceil(file.size / CHUNK_SIZE); let uploadId = localStorage.getItem(`upload_${file.name}_${file.size}_${file.lastModified}`); if (!uploadId) { uploadId = crypto.randomUUID(); localStorage.setItem(`upload_${file.name}_${file.size}_${file.lastModified}`, uploadId); } for (let i = 0; i < totalChunks; i++) { const start = i * CHUNK_SIZE; const end = Math.min(start + CHUNK_SIZE, file.size); const chunk = file.slice(start, end); // 把 chunk 放入待上传队列 }

这里有个地方要注意：file.lastModified要放进localStorage的key里。如果用户重新选择了同一个文件但内容变了，lastModified大概率也会变，这时候会重新生成uploadId，避免用旧的uploadId去续传一个内容已经不存在的文件。当然这不是绝对可靠，但作为第一版够用了。

3.2 用XMLHttpRequest拿单片进度，按字节算总进度

上传分片时，我选择用XMLHttpRequest而不是fetch。原因很直接：fetch到现在都没有提供独立的上传进度事件，xhr.upload.onprogress才能拿到每一片的上传字节数。如果你想做实时进度条，这个是绕不过去的选择。

单片的请求结构是这样：

function uploadChunk(uploadId, chunk, index, totalChunks, fileName) { return new Promise((resolve, reject) => { const xhr = new XMLHttpRequest(); xhr.open('POST', '/api/upload/chunk'); const fd = new FormData(); fd.append('uploadId', uploadId); fd.append('chunkIndex', index); fd.append('totalChunks', totalChunks); fd.append('fileName', fileName); fd.append('file', chunk, `${index}.part`); xhr.upload.onprogress = (e) => { if (e.lengthComputable) { onChunkProgress(index, e.loaded); } }; xhr.onload = () => { if (xhr.status >= 200 && xhr.status < 300) resolve(); else reject(new Error(`HTTP ${xhr.status}`)); }; xhr.onerror = () => reject(new Error('network error')); xhr.send(fd); }); }

整体进度不能简单用“已完成片数/总片数”来算，因为最后一片可能不满10MB。我维护一个已确认完成的字节总数，对流中每一片用loaded累加当前进度，整体进度就是：

整体进度 = (已完成的字节数 + 所有正在上传的片的loaded之和) / 文件总大小

实现上不需要太复杂的结构，一个对象数组记录每片状态和已上传字节数就够了。

3.3 并发上限与失败重试：先跑通串行，再上并发

上传逻辑有两种做法：串行或并发。串行最简单，一片传完再传下一片，代码就是一个循环，出问题好排查。并发能明显提升带宽利用率，但引入两个新问题：一是服务端同时收到多个分片，磁盘写压力增大；二是整体进度的计算要追踪多个在传分片。

我建议第一版先跑串行，把链路通掉，再改成并发。并发时不要一股脑把100个请求全部发出去，浏览器对同域并发连接数本来就是有限制的，一般6个左右，超出之后反而排队。我最后用的是限制并发数为3的固定线程池模式，核心代码如下：

async function runWithConcurrency(tasks, limit) { const results = new Array(tasks.length); let cursor = 0; async function worker() { while (cursor < tasks.length) { const idx = cursor++; results[idx] = await tasks[idx](); } } const workers = Array.from({ length: Math.min(limit, tasks.length) }, () => worker()); await Promise.all(workers); return results; }

失败重试是必须的。Web环境里网络抖动很常见，某个分片失败一次不代表整个上传失败。我的做法是每片最多重试3次，失败后等待1秒、2秒、4秒指数退避再试。如果3次都失败，记录该片索引，等整个队列跑完后提示用户“以下分片失败：3、7、12”，并提供一个“继续重试”按钮。这个设计比自动无限重试要稳妥，因为有时候失败原因是断网，你再重试也只是白白耗电。

4. C#后端接收分片：请求限制调整、安全落盘与临时文件管理

4.1 不改Kestrel/IIS限制，分片再小也白搭

后端第一步不是写接收代码，是确认服务器允许接收分片大小。我在10MB分片方案下，把接收分片接口的单请求限制设为25MB，留出了multipart/form-data的头部和字段冗余量。

ASP.NET Core里有两种改法。第一种是在Program.cs里全局配置：

builder.WebHost.ConfigureKestrel(options => { options.Limits.MaxRequestBodySize = 25 * 1024 * 1024; });

第二种更推荐，只对当前接口生效，避免全局放开导致其他接口被大请求刷爆：

[HttpPost("chunk")] [RequestSizeLimit(25 * 1024 * 1024)] public async Task<IActionResult> UploadChunk(...)

如果你部署在IIS后面，web.config也要同步调整：

<system.webServer> <security> <requestFiltering> <requestLimits maxAllowedContentLength="26214400" /> </requestFiltering> </security> </system.webServer>

Nginx反代的话，client_max_body_size 25m;也要配上。这个三层限制缺一个，分片哪怕只有10MB也可能被不同层拦截，表现通常是“上传到一半突然收到413或者连接被重置”。

4.2 接收接口的完整实现：写.tmp再改名.part

接收分片接口是整个后端最重要的部分，核心逻辑是：校验参数、把分片写入临时目录、写完后从.tmp改成.part。为什么要多此一举先用.tmp后缀？因为客户端可能正在上传一个分片，此时状态查询接口如果扫描到.part文件，会把它当成“已传完”，但实际文件还没写完整。先写.tmp，写完再原子性改名成.part，就能保证状态查询看到的都是完整分片。

[HttpPost("chunk")] [RequestSizeLimit(25 * 1024 * 1024)] public async Task<IActionResult> UploadChunk( [FromForm] string uploadId, [FromForm] int chunkIndex, [FromForm] int totalChunks, [FromForm] string fileName, IFormFile file) { if (!Guid.TryParse(uploadId, out var id) || chunkIndex < 0 || chunkIndex >= totalChunks) return BadRequest("参数非法"); var uploadDir = Path.Combine(_tempRoot, id.ToString("N")); var chunkDir = Path.Combine(uploadDir, "chunks"); Directory.CreateDirectory(chunkDir); var tmpPath = Path.Combine(chunkDir, $"{chunkIndex}.tmp"); var partPath = Path.Combine(chunkDir, $"{chunkIndex}.part"); await using (var fs = new FileStream(tmpPath, FileMode.Create, FileAccess.Write, FileShare.None, 81920)) { await file.CopyToAsync(fs); } // .NET Core 3.0+ 支持覆盖式Move，老版本需要先Delete再Move File.Move(tmpPath, partPath); var metaPath = Path.Combine(uploadDir, "meta.json"); if (!File.Exists(metaPath)) { var meta = new UploadMeta { FileName = SanitizeFileName(fileName), TotalChunks = totalChunks, FileSize = 0, UploadId = id.ToString("N") }; await File.WriteAllTextAsync(metaPath, JsonSerializer.Serialize(meta)); } return Ok(new { success = true, chunkIndex }); }

这里有一个开发经验：FileStream的bufferSize参数我用的是81920字节，这是.NET官方CopyToAsync的默认Buffer大小，也是Windows文件缓存比较舒服的块大小。你不需要自己设计成1MB的buffer，除非测出了明显的性能瓶颈，不要瞎调。

另外整个接口里我没有手动做file.Length和chunkIndex的映射关系校验，比如第5片是否真的该是10MB，这个放在合并阶段统一校验更合理，因为前端可能传的是最后一片，本身不满10MB是合法情况。

4.3 目录与文件名的安全设计：只用GUID和数字索引

这是我特别想强调的安全点。接收用户上传文件时，最忌讳的就是把用户传的fileName直接拼到路径里。攻击者可以构造一个../../../Windows/System32/xxx的文件名，配合接口直接往服务器任意位置写文件，这就是经典的路径穿越漏洞。

我的做法是：临时目录永远只使用uploadId作为目录名，uploadId经过Guid.TryParse校验，保证是合法的GUID格式；分片文件永远只使用数字索引作为文件名，数字经过范围校验。原始文件名只存入meta.json的FileName字段，不参与路径拼接。

private static string SanitizeFileName(string fileName) { var name = Path.GetFileName(fileName); if (string.IsNullOrWhiteSpace(name)) return "upload.bin"; foreach (var c in Path.GetInvalidFileNameChars()) { name = name.Replace(c, '_'); } return name.Length > 200 ? name[^200..] : name; }

为什么还要限制文件名长度？因为Windows路径单段最长255个字符，超出会直接IO异常；限制到200字符是留出目录前缀和后续业务后缀的空间。这类细节不踩一次坑很难注意到。

5. 断点续传的实现：状态查询接口与前端恢复流程

5.1 服务端状态怎么查：扫描chunks目录，不依赖数据库

断点续传的第一个关键问题是：怎么知道某个文件哪些分片已经传过了？我不引入数据库，直接扫描chunks目录，列出所有.part文件，解析出数字索引就是已上传分片列表。

[HttpGet("status")] public IActionResult Status([FromQuery] string uploadId) { if (!Guid.TryParse(uploadId, out var id)) return BadRequest("参数非法"); var uploadDir = Path.Combine(_tempRoot, id.ToString("N")); var chunkDir = Path.Combine(uploadDir, "chunks"); if (!Directory.Exists(chunkDir)) return Ok(new { uploadId = uploadId, uploadedChunks = Array.Empty<int>(), finished = false }); var uploadedChunks = Directory .GetFiles(chunkDir, "*.part") .Select(f => int.Parse(Path.GetFileNameWithoutExtension(f))) .OrderBy(x => x) .ToArray(); return Ok(new { uploadId = uploadId, uploadedChunks = uploadedChunks, finished = File.Exists(Path.Combine(uploadDir, "merged", "done.flag")) }); }

扫描目录这种方式在分片数不超过几百个时非常简单可靠。如果文件量级到了几万片，扫描会变慢，那时就要考虑用数据库或者内存字典记录分片状态。但对大部分内部系统来说，目录扫描已经够用，还在文件系统这一层天然实现了状态持久化，就算进程重启，状态也不会丢。

5.2 前端恢复：跳过已传分片，继续后面的片

前端拿到已传列表后，只需在遍历分片时跳过这些索引即可。

async function resumeUpload(file, uploadId) { const status = await fetch(`/api/upload/status?uploadId=${uploadId}`).then(r => r.json()); const uploadedSet = new Set(status.uploadedChunks); if (status.finished) { // 这个文件已经合并过了，直接提示完成 return; } const totalChunks = Math.ceil(file.size / CHUNK_SIZE); for (let i = 0; i < totalChunks; i++) { if (uploadedSet.has(i)) continue; const start = i * CHUNK_SIZE; const end = Math.min(start + CHUNK_SIZE, file.size); const chunk = file.slice(start, end); await uploadChunk(uploadId, chunk, i, totalChunks, file.name); } await fetch(`/api/upload/merge?uploadId=${uploadId}`, { method: 'POST' }); }

核心逻辑已经全部在这里了。断点续传不是什么神奇的黑科技，就是“记住已传的块，跳过它们继续传”。这地方有一个很常见的失败模式：前端在续传时又重新生成uploadId，导致服务端认为这是一个新文件，所有分片从头传。所以uploadId必须要持久化到localStorage，并且key要能对应到具体文件。

5.3 刷新页面/换文件后的uploadId找回策略

localStorage的key我用了文件名、文件大小、lastModified三个字段拼接。这个方案对普通场景足够，但有一种情况会踩坑：用户把文件改名了，但内容完全没变。这时候三个字段中的文件名变了，localStorage匹配不上，会生成新的uploadId，导致旧分片全部作废，重新传一遍。

解决方案是用分片哈希做指纹，比如取文件的首片和末片的SHA256，拼成指纹再存localStorage。这样只要内容不变，不管文件名怎么改都能找回uploadId。第一版要加这个也可以，前端用Web Crypto的crypto.subtle.digest能算，但会多读两次文件。我个人的取舍是：先做简单版，等真有用户反馈“我改名后居然重新传了”再来加也不迟，避免过度设计。

6. 合并分片与完整性校验：从一堆.part到正式文件

6.1 合并接口的实现要点

所有分片传完后，前端请求merge接口。服务端要做的事只有三件：按索引顺序读取所有.part文件、写入输出文件、删除临时目录。顺序绝对不能乱，因为分片是并发上传的，到达服务端的顺序完全随机，只有写入文件时按0、1、2...的顺序合并，才能还原出正确文件。

[HttpPost("merge")] public async Task<IActionResult> Merge([FromQuery] string uploadId) { if (!Guid.TryParse(uploadId, out var id)) return BadRequest("参数非法"); var uploadDir = Path.Combine(_tempRoot, id.ToString("N")); var chunkDir = Path.Combine(uploadDir, "chunks"); var metaPath = Path.Combine(uploadDir, "meta.json"); if (!File.Exists(metaPath)) return NotFound("找不到上传记录"); if (!Directory.Exists(chunkDir)) return BadRequest("没有分片数据"); var meta = JsonSerializer.Deserialize<UploadMeta>(await File.ReadAllTextAsync(metaPath)); long totalLength = 0; for (int i = 0; i < meta.TotalChunks; i++) { var partPath = Path.Combine(chunkDir, $"{i}.part"); if (!File.Exists(partPath)) return BadRequest($"缺少分片 {i}"); totalLength += new FileInfo(partPath).Length; } if (meta.FileSize > 0 && totalLength != meta.FileSize) return BadRequest("分片大小总和与文件大小不一致"); var outputDir = Path.Combine(uploadDir, "merged"); Directory.CreateDirectory(outputDir); var outputPath = Path.Combine(outputDir, meta.FileName); await using (var outFs = new FileStream(outputPath, FileMode.Create, FileAccess.Write, FileShare.None, 81920)) { for (int i = 0; i < meta.TotalChunks; i++) { var partPath = Path.Combine(chunkDir, $"{i}.part"); await using var inFs = new FileStream(partPath, FileMode.Open, FileAccess.Read, FileShare.Read, 81920); await inFs.CopyToAsync(outFs); } } // 清空分片和元数据，只保留合并产物 Directory.Delete(chunkDir, true); File.Delete(metaPath); // 打一个完成标记，供status接口判断 await File.WriteAllTextAsync(Path.Combine(uploadDir, "merged", "done.flag"), DateTime.UtcNow.ToString("O")); return Ok(new { path = $"/files/{id:N}/{meta.FileName}" }); }

这里有个API设计的细节：我在meta.json中存了FileSize，合并前会校验所有.part文件大小总和是否等于原始文件大小。FileSize是前端在第一次上传分片时通过form字段带过来的，写进meta.json里。如果大小对不上，说明有分片传错或者服务端文件损坏，这时候直接返回错误，不要继续合并。

6.2 第一个版本做大小校验就够了，哈希是加分项

很多教程会要求每个分片做MD5或SHA256校验，但我的观点是：第一版不需要全量哈希，大小校验加HTTP的Content-Length校验已经能拦截绝大多数问题。原因有两个：第一，传输层的TCP校验本来就能保证字节级正确，网络不稳定的环境下错误只可能来自缓存或代理的篡改，这种场景在内部系统中概率极低；第二，对1GB文件算一次MD5大概要1到3秒，虽然能接受，但增加了复杂度。

如果你处理的场景对完整性要求极高，比如医疗影像、司法证据，那就必须在合并后对整个文件算一次SHA256，写进数据库或单独返回给前端。分片级别的哈希只在你需要支持秒传功能时才值得做，它本质上是用“已传过相同内容”的哈希索引来跳过上传，属于另一个层面的问题了。

7. 实测中的坑与优化建议：从“能跑”到“好用”

7.1 三个我实际踩过的坑

第一个坑是File.Move覆盖问题。早期我在.NET Core 2.1上写合并逻辑，分片重传时File.Move(tmpPath, partPath)直接抛IOException，因为目标文件已存在。后来改成先File.Delete(partPath)再File.Move，虽然能用，但并发重试时会出现瞬间没有.part文件的情况，状态查询会认为该片未上传。升级到.NET Core 3.0+后用了带覆盖参数的File.Move(tmpPath, partPath, true)，这个问题才彻底解决。

第二个坑是IFormFile的内存缓冲行为。ASP.NET Core的IFormFile在接收到小文件时会把内容放内存，大文件会落到服务器临时目录。内部系统用一律是GB级文件，分片10MB可能正好落在“内存缓冲还是落盘缓冲”的边界上，测试时没注意，上传并发一高，服务器内存直接飙到几个GB。我最后给Kestrel配置了FormOptions.MultipartBodyLengthLimit，并确认TempFileProvider的临时目录有足够的磁盘空间。

第三个坑是临时目录垃圾堆积。测试阶段经常出现用户传了50%就放弃的情况，这些没完成的uploadId目录会一直留在磁盘上，一个1GB文件的分片加元数据差不多也是1GB，十几个放弃的上传就能把磁盘搞满。我写了一个简单的清理任务，逻辑是扫描uploadTemp下所有目录，如果最后写入时间超过24小时，直接删掉整个目录。这个任务用IHostedService实现，每天早上4点跑一次，够用。

7.2 上线前值得做的几项优化

整套方案跑通之后，我建议再做三个优化，顺序由易到难：

第一，把uploadId的查询状态缓存到内存。用ConcurrentDictionary记录每个uploadId的已传分片数，避免每个状态查询都去扫磁盘。注意merge成功后要从字典里删掉，不然内存会持续增长。

第二，前端加一个总控界面，显示每个分片的实时状态，比如待上传、上传中、已完成、失败待重试。这个界面在排查问题时的价值远超你花进去的开发时间。我见过太多关于“传了一半卡住”的工单，没有状态列表就只能靠猜。

第三，把分片上传改造成可打断、可恢复的底座。比如用户点了暂停，前端记录当前已传列表，暂停后续传时直接走resume逻辑。因为你的链路已经实现续传了，加暂停功能只是把resume逻辑暴露给一个按钮而已，改动量很小。

最后说一个部署层面的注意点。如果服务器前面有Nginx，除了client_max_body_size，proxy_read_timeout和proxy_send_timeout也要适当调大。虽然分片之后单个请求时间变短了，但在弱网环境下传一个10MB分片仍然可能超过默认的60秒，超时照样断连。我一般设成300秒，并且在后端接口里记录每次请求的耗时，超过60秒的请求要重点观察，看是带宽问题还是服务端处理瓶颈。