做 Web 上传功能这些年我最怕听到的四个字就是“传不上去”。用户把一个 2GB 的大文件拖进浏览器或者把一整文件夹素材拖进上传区进度条卡在 83%然后网络闪断刷新之后一切从头再来。这种场景遇到得越多越能体会设计一个可靠的 C#.NET 跨平台上传方案有多重要。如果只是传几个小文件form enctypemultipart/form-data加后端IFormFile就够了。但文件体积一旦上到 GB 级或者面对成百上千个文件的目录结构问题就不再是“怎么写代码”而是整个传输模型根本不匹配。这篇文章把我自己落地过的大文件分片上传、断点续传、文件夹还原、跨平台部署细节完整捋一遍代码和配置都能直接抄希望能帮到正在和上传功能较劲的人。1. 常规上传为什么扛不住大文件先看清敌人是谁要设计一个能扛住大文件的方案首先得明白常规方案到底死在哪儿。很多人一上来就找“分片插件”“断点续传组件”但如果不理解背后的瓶颈配置和代码很容易调错方向。1.1 三个逃不掉的硬限制第一个是请求体限制。ASP.NET Core 自带的 Kestrel 服务器默认允许的最大请求体只有约 30MB超过之后直接抛BadHttpRequestException。即便你调大了 Kestrel 的限制部署到 IIS 后面还有maxAllowedContentLength放到 nginx 后面还有client_max_body_size。每一层都可能成为拦截大文件的黑洞而且是配置不对就立刻 413/400 的那种排查时非常迷惑。第二个是内存峰值。常规做法是把整个请求体读进内存或者通过IFormFile一次性拷贝。很多人误以为IFormFile已经是“落盘”了实际上multipart/form-data的解析过程依然要经过内存缓冲大文件到场时内存会瞬间被打满多用户同时上传就是灾难级的体验。第三个是“全有或全无”的重传机制。一次请求只要没在超时窗口内完成或者中途掉线整个文件就废了。TCP 层已经尽力保证不丢包但应用层没有断点能力用户就只能从头再来。下载器早就有断点续传了上传功能却还停留在“一次请求赌到底”的阶段这本身就很不合理。1.2 跨平台到底要跨什么常听说“一次编写到处运行”但 .NET Framework 时代的上传代码基本等于被绑死在 Windows 上HttpModule、HttpContext、Windows 身份验证体系模块和中间件全都依赖 IIS。跨平台方案的核心前提是项目必须基于 .NET Core / .NET 5 这一代运行时而不是老 Framework。只有新一代运行时才能用 Kestrel 独立部署、丢进 Linux 容器、用上跨平台的FileStreamAPI。我见过不少团队还在维护老 Framework 的下载中心每次处理大文件上传都要走 IIS 临时目录部署迁移 Linux 基本等于重写一遍。所以做跨平台上传方案第一步不是代码抽象而是确认运行时选型没有把自己锁死在单一操作系统上。2. 分片上传把大问题拆成小问题的通用套路分片上传的思路和断点下载一脉相承与其让一个巨大的请求生死未卜不如把文件切成一个个独立的小块每块单独上传、单独校验。单块失败就只重传这块不牵连其他。它解决的不只是“体积太大”更是“失败代价太高”的问题。2.1 分片模型三个接口加一个身份标识我推荐的最小可用模型长这样接口作用关键参数POST /api/upload/init创建上传任务返回 fileIdfileName、relativePath、totalSize、totalChunksPOST /api/upload/chunk上传单个分片fileId、chunkIndex、fileGET /api/upload/status查询已上传分片用于续传fileIdPOST /api/upload/merge合并所有分片为完整文件fileId、totalChunks、fileName、relativePath这里fileId是整个流程的纽带由前端生成。它可以是 UUID也可以是文件内容的哈希值。用哈希当 fileId 有个额外好处可以直接实现“秒传”这个后面细说。每个分片用chunkIndex标识顺序合并时严格按索引拼接顺序错一个字节都会导致文件损坏。2.2 分片大小怎么定分片大小没有标准答案。我见过用 1MB、5MB、10MB 的也有人为了对齐对象存储的分块规则用 16MB。经验判断公网上传5MB 到 10MB 比较合适内网带宽充足可以放到 20MB 以上。这里有个权衡逻辑分片太小请求数量暴涨。一个 2GB 文件用 1MB 分片就是 2048 次请求每次请求都有 HTTP 头、鉴权、磁盘写入的开销失败概率随请求数线性上升。分片太大又回到老问题——单块传输时间变长断点续传的粒度变粗。我在实际项目中通常把默认分片设为 5MB同时根据用户当前网络质量动态调整网络波动大的用户分片小一些网络稳定的用户可以适当调大。2.3 并发上传为什么能让大文件更快分片还有一个附加价值可以并发。浏览器的同源请求并发上限大约是 6 个左右JS 自己维护任务队列把待传分片丢给 3 到 5 个并发 worker 去跑吞吐量比单请求上传高出一截。但并发数不是越大越好服务端磁盘是机械盘时分片随机写入并发太高会拖垮 IO即便用 SSD超过 8 个并发分片也可能造成文件句柄和网络队列的浪费。这里顺便提醒一句并发分片在服务端是乱序到达的合并时绝不能依赖上传完成顺序必须是 merge 阶段统一按chunkIndex顺序读取合并。谁后到、谁先到在合并环节无关紧要。3. 断点续传、秒传和并发控制体验差距从这三个细节拉开分片只是骨架真正拉开体验差距的是续传、秒传和并发控制。这三个功能不做分片上传充其量只是“大文件能传了”但离“传得爽”还差很远。3.1 秒传用哈希换时间秒传的核心是内容寻址。前端选完文件后计算文件整体的 MD5 或 SHA-1注意是整个文件哈希不是每个分片拿哈希去 init 接口查一下如果服务端已经存在相同哈希的文件直接返回“已存在”前端连传都不用传。这个功能对素材库、安装包分发这类场景特别实用用户重复上传的概率很高。大文件算整文件哈希有个现实问题慢。2GB 文件在浏览器里算完整 MD5最快也要十几秒。我实际项目中常用的折中方案是抽样哈希取文件前几 MB 和末尾几 MB 拼接后算哈希命中率足够耗时能控制在秒级。秒传属于优化项如果业务上不需要去重直接用 UUID 当 fileId 更省事。3.2 续传上传前先问服务端缺哪些块续传的实现依赖 status 接口。前端拿到 fileId 后先调用 status 查询服务端已经收到了哪些chunkIndex然后只补传缺失的块。例如 2GB 文件被切成 400 个 5MB 分片传了 327 个后断网重连后只需要传剩下的 73 个而不是从头再来。这里有一个重要的幂等性细节服务端收到分片后不仅要写文件还要校验分片大小是否符合预期否则一个中断的半块会导致合并出的文件损坏。我通常会在分片元数据里记录每个分片的期望大小status 查询时把“已存在但大小不对”的块标记为无效让前端重新传它。这比单纯检查“文件是否存在”可靠得多。3.3 并发数和服务端承压的平衡并发控制在前面提过这里补充一个容易踩的坑不要在服务端通过锁去限制并发而要在前端用任务队列限制。服务端做全局并发限流逻辑复杂还容易误伤正常用户前端把limit设为 3理论上每用户只维持 3 个长连接服务端压力就基本可控。如果登录系统本身有多级代理实际连接数会被放大limit 还需要再往下调。async function runWithConcurrency(tasks, limit) { const queue [...tasks]; const workers Array.from({ length: limit }, async () { while (queue.length) { const task queue.shift(); await task(); } }); await Promise.all(workers); }注意这段代码里每个 worker 是死循环消费队列limit是多少就有多少个真正的并发请求。它不保证某个分片一定先完成但保证队列里的任务一个都不会漏。4. 文件夹上传真正麻烦的是目录结构本身文件夹上传和大文件上传是两个维度的难题。单文件再大也只是“一条直线”的传输文件夹包含成百上千个文件还需要保留完整的目录层级。用户从资源管理器拖一个素材目录进来后端如果给拍扁成平铺的文件列表对用户来说功能就是不完整的。4.1 webkitdirectory 与 relativePath 的组合实践前端拿到文件夹最直接的方式是input typefile webkitdirectory multiple /。选择目录后input.files会返回目录下所有文件的扁平列表但每个 file 对象带一个webkitRelativePath属性格式类似设计方案/图纸/建筑平面图.dwg。这个属性就是还原目录结构的关键。input.addEventListener(change, () { const files Array.from(input.files); for (const file of files) { const relativePath file.webkitRelativePath || file.name; enqueueFileUpload(file, relativePath); } });文件夹里可能有几百个文件不能一股脑全部同时上传。我的做法是把所有文件先放进一个队列每个文件作为一个上传任务队列用limit 3或limit 5的并发 worker 消费。这样既保留了目录结构又不会把浏览器和服务端的连接数打爆。4.2 服务端路径还原与防目录穿越前端把webkitRelativePath原样传上来后端要做两件事一是把路径里的分隔符统一处理二是把危险片段清理干净。..和绝对路径是重灾区恶意用户完全可以通过构造 relativePath 把文件写到服务器任意目录。我建议在服务端做一个独立的路径消毒函数拒绝任何包含..、盘符、根路径的输入。public static string Normalize(string relativePath) { var normalized relativePath.Replace(\\, /); var parts normalized.Split(/, StringSplitOptions.RemoveEmptyEntries); var safe new Liststring(); foreach (var part in parts) { if (part is . or ..) continue; if (Path.GetInvalidFileNameChars().Any(c part.Contains(c))) continue; safe.Add(part); } return string.Join(Path.DirectorySeparatorChar, safe); }注意最后一步合并回目录字符串时要用Path.DirectorySeparatorChar而不是硬编码反斜杠。Windows 上它是\Linux 上是/让运行时去决定你就能避免写出“Windows 上能用、部署到 Linux 就报错”的代码。4.3 浏览器兼容与降级webkitdirectory带了私有前缀说明它不是标准 API。目前 Chrome、Edge、Firefox 都支持Safari 的支持历史则比较曲折部分旧版本拿不到完整的relativePath。我的兼容策略是检测input.files[0]?.webkitRelativePath是否存在不存在就走降级——让用户手动多选文件夹里的文件或者提供 zip 上传的方案由服务端解包展开目录结构。zip 方案对超大目录尤其管用因为浏览器端遍历上千个文件本身就有性能开销压缩传输反而更稳。5. C#.NET 后端落地接口、合并和存储的关键代码前面把模型讲清楚了下面把 C#.NET 后端真正落地的代码亮出来。我假设你的项目是基于 .NET 8 的 ASP.NET Core Web API这是目前最稳妥的 LTS 版本跨平台支持也最完整。5.1 上传与合并接口的最小实现上传分片接口的核心动作只有一个把IFormFile落盘到临时目录并按 fileId 分区存放避免几百个分片文件堆在同一个目录里。[HttpPost(upload/chunk)] [RequestSizeLimit(15 * 1024 * 1024)] public async TaskIActionResult UploadChunk([FromForm] ChunkUploadRequest request) { if (request.File is null || request.File.Length 0) return BadRequest(分片内容为空); var chunkDir Path.Combine(_options.TempRoot, request.FileId); Directory.CreateDirectory(chunkDir); var chunkPath Path.Combine(chunkDir, ${request.ChunkIndex}.part); await using (var stream new FileStream(chunkPath, FileMode.Create, FileAccess.Write, FileShare.None)) { await request.File.CopyToAsync(stream); } _metadata.Record(request.FileId, request.ChunkIndex, request.File.Length); return Ok(new { ChunkIndex request.ChunkIndex }); }这里有两个容易忽略的点。第一RequestSizeLimit要留余量单分片 5MB 时给到 15MB防止IFormFile在处理过程中混入其他表单字段导致整体体积超标。第二分片落盘用FileMode.Create同一个分片重复上传会直接覆盖天然幂等配合前面的续传逻辑前端重复传某个分片也不会产生脏数据。合并接口按索引顺序读取临时目录下所有.part文件边读边写目标文件合并完成后删除临时目录[HttpPost(upload/merge)] public async TaskIActionResult Merge([FromBody] MergeRequest request) { var tempDir Path.Combine(_options.TempRoot, request.FileId); if (!Directory.Exists(tempDir)) return NotFound(上传任务不存在); if (!_metadata.Validate(request.FileId, request.TotalChunks)) return BadRequest(分片不完整请先补齐); var safeRelativePath PathSanitizer.Normalize(request.RelativePath); var targetDir Path.Combine(_options.StoreRoot, safeRelativePath); Directory.CreateDirectory(targetDir); var targetPath Path.Combine(targetDir, FileNameSanitizer.Sanitize(request.FileName)); await using (var output new FileStream(targetPath, FileMode.Create, FileAccess.Write, FileShare.None, 1_048_576)) { for (var i 0; i request.TotalChunks; i) { var chunkPath Path.Combine(tempDir, ${i}.part); await using var input new FileStream(chunkPath, FileMode.Open, FileAccess.Read, FileShare.Read, 1_048_576, FileOptions.SequentialScan); await input.CopyToAsync(output); } } Directory.Delete(tempDir, true); return Ok(new { Path Path.Combine(safeRelativePath, request.FileName) }); }合并用的是 1MB 缓冲的流式拷贝不会一次性读入内存。对不太夸张的大文件比如 2GB 以下同步合并十几秒能搞定行为最简单也最好排查。真正超过 10GB 的巨型文件我建议把合并放进后台任务执行前端通过 status 轮询合并状态而不是让 HTTP 请求长时间挂着否则任何一层代理的超时都会让你前功尽弃。5.2 存储抽象给未来换对象存储留条路跨平台方案不只是“跨操作系统”还要预防“未来换存储”的迁移成本。我习惯在控制层和存储层之间加一个薄薄的抽象接口public interface IFileStore { Task SaveAsync(string relativePath, Stream content, CancellationToken ct); Taskbool ExistsAsync(string relativePath, CancellationToken ct); }本地磁盘实现走FileStream未来接对象存储就再写一个实现把处理好的相对路径作为 object key 直接用。这样业务代码不用改动换存储只是换注册类型的事情。对跨平台来说真正要小心的不是“将来换云”而是“今天这套本地磁盘代码在 Windows 和 Linux 上行为不一致”——路径分隔符、文件名大小写、文件锁语义处处有差别务必把路径操作收敛到一处统一处理。5.3 配置坑Kestrel 与 FormOptions 必须一起调ASP.NET Core 里有两层限制同时管着请求体Kestrel 的MaxRequestBodySize和FormOptions.MultipartBodyLengthLimit。只调一个另一个照样拦你。我见过几次“代码没问题但分片一到 30MB 就报 400”的排查最后根因都是 FormOptions 没放开。builder.WebHost.ConfigureKestrel(options { options.Limits.MaxRequestBodySize 15 * 1024 * 1024; }); builder.Services.ConfigureFormOptions(options { options.MultipartBodyLengthLimit 15 * 1024 * 1024; options.ValueLengthLimit 1024 * 1024; options.ValueCountLimit 20; });分片方案天生对配置友好因为单请求体很小这两层限制只需要按“分片大小 余量”来设置。它不会让你一次性放开几百 MB安全性和可用性都能兼顾。6. 跨平台部署清单换台机器就崩的细节代码写好了部署才是检验跨平台的试金石。下面几条是我在 Windows 服务器和 Linux 容器环境里都踩过、修过的具体问题。6.1 路径分隔符与大小写敏感Windows 文件系统大小写不敏感README.md和readme.md是同一个文件Linux 严格区分。如果目录还原逻辑依赖某个固定大小写比如前端路径是Assets/New上传到 Linux 之后拿assets/new去读就会扑空。所以路径存储一律保持原样比较时不要做大小写归一化除非你真的需要设计去重。分隔符的问题更隐蔽。Path.Combine(a, b/c)在 Windows 上会得到a\b/c这种混合分隔符在 Windows 上没问题在 Linux 上也会被容忍因为 Linux 只认/\会被当成普通字符。问题通常出现在要拿路径和用户输入比较或写入数据库再读取还原时分隔符不统一会导致查重失败。保险做法是入口统一 Normalize 成/落盘前统一转成平台的DirectorySeparatorChar全程一个规则不乱混。6.2 反代、容器与临时目录即使分片方案把单请求体控制得很小部署时仍要检查前置代理的请求体限制。nginx 默认client_max_body_size是 1MB如果整文件直传而没调它小文件没事大文件直接 413。分片模式下单请求 5MB 也已经超过 nginx 默认值所以无论走不走分片把client_max_body_size设到 50m 以上都是稳妥操作。容器环境还要注意临时目录容量。分片上传的临时目录如果映射到容器可写层一旦容器重建所有未完成的上传任务会全部丢失。更实际的问题是/tmp如果挂的是内存盘几十个并发大文件就能把内存打爆。我建议持久化卷单独挂一个upload-temp目录并且把容量监控纳入日常巡检。6.3 分片临时文件的生命周期管理分片临时文件会持续堆积必须有一个后台清理任务兜底。按 fileId 组织子目录的好处在这里体现出来清理时只需扫描临时根目录删除超过 24 小时未更新的子目录。public class ChunkCleanupService : BackgroundService { protected override async Task ExecuteAsync(CancellationToken stoppingToken) { while (!stoppingToken.IsCancellationRequested) { await Task.Delay(TimeSpan.FromHours(1), stoppingToken); var dirs Directory.EnumerateDirectories(_tempRoot); foreach (var dir in dirs) { if (DateTime.UtcNow - Directory.GetLastWriteTimeUtc(dir) TimeSpan.FromHours(24)) { Directory.Delete(dir, true); } } } } }另外提醒一句大量小分片文件会消耗 inode。大文件分片后临时目录里满是小文件Linux 上 inode 耗尽会导致“磁盘明明还有空间但任何文件都写不进去”。定期看一眼 inode 使用率比线上故障后再处理要轻松得多。7. 收尾聊几句实测中的体会这套方案我前前后后改过三轮有几个细节如果不提前处理早晚会在生产环境变成事故这里说点比较实际的心得。合并接口之前一定要检查目标分区的剩余磁盘空间。分片上传过程中的空间占用只有单分片大小看起来人畜无害但 merge 一到2GB 文件瞬间占掉 2GB 真实空间磁盘不够直接写崩可能把上传任务和服务器一起带崩。我现在会在 merge 开始前用DriveInfo.AvailableFreeSpace预检一次空间不足就提前返回错误给前端。浏览器端算大文件整体哈希虽然可以抽样但如果业务确实需要精确秒传最好让用户后台上传时预先算好哈希并缓存别指望每次上传都现场算一遍。浏览器算 2GB 文件的完整 MD5 既卡页面又耗 CPU体验非常差。前端上传大文件时永远用File.slice拿分片别用FileReader.readAsDataURL或readAsArrayBuffer。前者是零拷贝的分片引用后者会把整块内容读进内存传 5MB 分片内存占用可能涨到几十 MB几十个并发分片过来浏览器直接白屏。文件夹的空目录问题目前无解浏览器端没有标准 API 能枚举空目录。如果业务强依赖空目录也要保留只能走 zip 上传让服务端解包展开这是我前面说的降级方案也是目前唯一可靠的兜底。最后一个建议上传功能尽量单独评估别和其他业务接口混在同一个越权模型里。上传接口天然要接收二进制内容、要写磁盘、要允许大请求体这三件事组合在一起就是攻击面。我在生产环境始终给上传接口单独配鉴权和限流不用匿名访问也不让普通用户直接打到这个接口上。大文件与文件夹上传的跨平台设计说到底就是一个控制风险边界的过程分片控制传输风险临时目录控制存储风险路径规范控制跨平台风险权限控制安全风险。把这几条边界划清楚剩下的就是在真实流量里不断打磨细节了。
