去年给公司内部做资料库系统的时候用户经常要传几百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默认请求体上限大约是30MBIIS的maxAllowedContentLength默认也是30MB左右。你传一个超过30MB的请求Kestrel直接返回413IIS干脆连请求都不给进。本机调试时为什么没发现因为本机通常没有IIS限制这一层而Kestrel限制可以通过RequestSizeLimit特性临时放开传着传着就把这个限制忽略了。第三个坑是失败重传的代价。直传方案下1GB文件传到95%断开用户就得从0%重传。如果用户网络本来就不稳定或者中途切了Wi-Fi、锁了屏一次都传不完。我曾经测过一个场景手机热点传给服务器1GB文件连续尝试5次没有一次能完整传完。这已经不是技术问题了是用户体验直接崩盘。1.2 分片能解决什么不能解决什么分片的核心思路很简单把1GB文件切成100个10MB的小块每次只传一小块单块请求时间短超时风险小失败后只需要重传那一小块不用从头再来。它能解决超时问题能解决请求体限制问题也能把失败重试的代价从“1GB”降级到“10MB”。但它不能解决带宽不够的问题也不能解决服务器磁盘满了的问题。换句话说分片是为了让上传过程更健壮而不是让网络更快。这个预期要先摆正不然你后面优化方向会跑偏。2. 整体方案定案分片大小、文件标识与续传状态设计2.1 分片大小为什么选10MB分片大小直接影响请求数量和续传粒度。片太小比如1MB1GB就是1000个请求HTTP握手和表单解析的开销会吃掉大量时间片太大比如100MB一个片传起来还是要几十秒超时风险又回来了。我最终选了10MB。理由有三个一是10MB远小于Kestrel和IIS的默认30MB限制就算不调大服务器限制也能先跑通二是1GB文件切100片请求数量可控三是断点续传的粒度是10MB用户重连后最多重传10MB体感可以接受。如果你要传的文件普遍是10GB以上可以把分片调到20MB甚至50MB但不能超过网关的请求体限制这是一个联动关系。2.2 三个接口与状态约定我设计的接口只有三个没有引入数据库也没有引入消息队列整个方案把依赖降到了最低接口方法作用/api/upload/chunkPOST上传单个分片表单包含uploadId、chunkIndex、totalChunks、fileName和文件流/api/upload/statusGET查询某个uploadId已上传了哪些分片返回上传列表/api/upload/mergePOST上传完所有分片后触发后端合并并校验完整性这里的核心变量是uploadId。前端在上传开始时生成一个GUID作为这个文件在服务端的唯一标识。所有分片、状态查询、合并请求都围绕这个uploadId展开。服务端临时目录结构是uploadTemp/ {uploadId}/ chunks/ 0.part 1.part 2.part ... meta.jsonmeta.json记录文件原始名称、总分片数、文件大小。分片文件统一用数字索引作为文件名后面会讲为什么必须这么做——这直接关系到路径穿越的安全性。2.3 一个关键认知网页端的切片逻辑是JavaScriptC#在服务端再强调一次避免后面代码看不懂浏览器端切片用的是File.slice()这是JavaScript的API。C#全程是在服务端处理分片落盘、状态查询、合并。如果你非要在浏览器端也跑C#那就得用Blazor WebAssembly但Blazor对超大文件的支持很弱而且首次加载就要下载好几MB的运行时。我个人的建议是别纠结这个JS做前端切片、C#做后端处理是这个场景下工程上最成熟的组合。3. 前端切片与上传File API、整体进度与并发控制3.1 File.slice切出一块10MB的Blob用户通过input typefile选中文件后前端拿到的是一个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 TaskIActionResult UploadChunk(...)如果你部署在IIS后面web.config也要同步调整system.webServer security requestFiltering requestLimits maxAllowedContentLength26214400 / /requestFiltering /security /system.webServerNginx反代的话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 TaskIActionResult 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.Emptyint(), 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 TaskIActionResult 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.DeserializeUploadMeta(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_sizeproxy_read_timeout和proxy_send_timeout也要适当调大。虽然分片之后单个请求时间变短了但在弱网环境下传一个10MB分片仍然可能超过默认的60秒超时照样断连。我一般设成300秒并且在后端接口里记录每次请求的耗时超过60秒的请求要重点观察看是带宽问题还是服务端处理瓶颈。
去年给公司内部做资料库系统的时候用户经常要传几百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默认请求体上限大约是30MBIIS的maxAllowedContentLength默认也是30MB左右。你传一个超过30MB的请求Kestrel直接返回413IIS干脆连请求都不给进。本机调试时为什么没发现因为本机通常没有IIS限制这一层而Kestrel限制可以通过RequestSizeLimit特性临时放开传着传着就把这个限制忽略了。第三个坑是失败重传的代价。直传方案下1GB文件传到95%断开用户就得从0%重传。如果用户网络本来就不稳定或者中途切了Wi-Fi、锁了屏一次都传不完。我曾经测过一个场景手机热点传给服务器1GB文件连续尝试5次没有一次能完整传完。这已经不是技术问题了是用户体验直接崩盘。1.2 分片能解决什么不能解决什么分片的核心思路很简单把1GB文件切成100个10MB的小块每次只传一小块单块请求时间短超时风险小失败后只需要重传那一小块不用从头再来。它能解决超时问题能解决请求体限制问题也能把失败重试的代价从“1GB”降级到“10MB”。但它不能解决带宽不够的问题也不能解决服务器磁盘满了的问题。换句话说分片是为了让上传过程更健壮而不是让网络更快。这个预期要先摆正不然你后面优化方向会跑偏。2. 整体方案定案分片大小、文件标识与续传状态设计2.1 分片大小为什么选10MB分片大小直接影响请求数量和续传粒度。片太小比如1MB1GB就是1000个请求HTTP握手和表单解析的开销会吃掉大量时间片太大比如100MB一个片传起来还是要几十秒超时风险又回来了。我最终选了10MB。理由有三个一是10MB远小于Kestrel和IIS的默认30MB限制就算不调大服务器限制也能先跑通二是1GB文件切100片请求数量可控三是断点续传的粒度是10MB用户重连后最多重传10MB体感可以接受。如果你要传的文件普遍是10GB以上可以把分片调到20MB甚至50MB但不能超过网关的请求体限制这是一个联动关系。2.2 三个接口与状态约定我设计的接口只有三个没有引入数据库也没有引入消息队列整个方案把依赖降到了最低接口方法作用/api/upload/chunkPOST上传单个分片表单包含uploadId、chunkIndex、totalChunks、fileName和文件流/api/upload/statusGET查询某个uploadId已上传了哪些分片返回上传列表/api/upload/mergePOST上传完所有分片后触发后端合并并校验完整性这里的核心变量是uploadId。前端在上传开始时生成一个GUID作为这个文件在服务端的唯一标识。所有分片、状态查询、合并请求都围绕这个uploadId展开。服务端临时目录结构是uploadTemp/ {uploadId}/ chunks/ 0.part 1.part 2.part ... meta.jsonmeta.json记录文件原始名称、总分片数、文件大小。分片文件统一用数字索引作为文件名后面会讲为什么必须这么做——这直接关系到路径穿越的安全性。2.3 一个关键认知网页端的切片逻辑是JavaScriptC#在服务端再强调一次避免后面代码看不懂浏览器端切片用的是File.slice()这是JavaScript的API。C#全程是在服务端处理分片落盘、状态查询、合并。如果你非要在浏览器端也跑C#那就得用Blazor WebAssembly但Blazor对超大文件的支持很弱而且首次加载就要下载好几MB的运行时。我个人的建议是别纠结这个JS做前端切片、C#做后端处理是这个场景下工程上最成熟的组合。3. 前端切片与上传File API、整体进度与并发控制3.1 File.slice切出一块10MB的Blob用户通过input typefile选中文件后前端拿到的是一个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 TaskIActionResult UploadChunk(...)如果你部署在IIS后面web.config也要同步调整system.webServer security requestFiltering requestLimits maxAllowedContentLength26214400 / /requestFiltering /security /system.webServerNginx反代的话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 TaskIActionResult 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.Emptyint(), 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 TaskIActionResult 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.DeserializeUploadMeta(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_sizeproxy_read_timeout和proxy_send_timeout也要适当调大。虽然分片之后单个请求时间变短了但在弱网环境下传一个10MB分片仍然可能超过默认的60秒超时照样断连。我一般设成300秒并且在后端接口里记录每次请求的耗时超过60秒的请求要重点观察看是带宽问题还是服务端处理瓶颈。
