C#.NET跨平台大文件分片上传与断点续传实战指南

做 Web 上传功能这些年，我最怕听到的四个字就是“传不上去”。用户把一个 2GB 的大文件拖进浏览器，或者把一整文件夹素材拖进上传区，进度条卡在 83%，然后网络闪断，刷新之后一切从头再来。这种场景遇到得越多，越能体会设计一个可靠的 C#.NET 跨平台上传方案有多重要。

如果只是传几个小文件，<form enctype="multipart/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 分片模型：三个接口加一个身份标识

我推荐的最小可用模型长这样：

这里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 type="file" 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 List<string>(); 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 Task<IActionResult> 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 Task<IActionResult> 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); Task<bool> 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.Configure<FormOptions>(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 上传让服务端解包展开，这是我前面说的降级方案，也是目前唯一可靠的兜底。

最后一个建议：上传功能尽量单独评估，别和其他业务接口混在同一个越权模型里。上传接口天然要接收二进制内容、要写磁盘、要允许大请求体，这三件事组合在一起就是攻击面。我在生产环境始终给上传接口单独配鉴权和限流，不用匿名访问，也不让普通用户直接打到这个接口上。

大文件与文件夹上传的跨平台设计，说到底就是一个控制风险边界的过程：分片控制传输风险，临时目录控制存储风险，路径规范控制跨平台风险，权限控制安全风险。把这几条边界划清楚，剩下的就是在真实流量里不断打磨细节了。