1. 跨平台大文件上传，从需求到方案选型
做桌面端和Web端跨平台客户端的时候，文件上传这块迟早会碰到一个绕不开的坎：小文件随便传没问题，一旦文件超过几GB，或者用户直接拖进来一个包含上千个文件的文件夹，普通的表单提交方式立刻露馅——要么内存爆掉，要么连接超时，要么传一半断掉。
这篇文章聊的就是C#.NET体系下，如何设计一套能扛住大文件和文件夹上传的跨平台方案。我不讲那种只能在Windows上跑的写法，而是基于.NET 6/8的跨平台能力，从分片上传、断点续传、文件夹递归遍历到多线程并发控制，把完整的设计思路和可落地的代码细节都拆给你看。适合正在做客户端上传模块、或者想把Web上传体验做成桌面级的朋友参考。
先说我踩过的一个典型场景：某跨平台系统需要支持用户上传单个2GB以上的设计稿压缩包，同时还能一次拖入几百个文件的资源文件夹。最开始我用的是最简单的MultipartFormDataContent整包上传，结果测试时内存涨到几个GB，小带宽用户传一半直接超时。后来改成切片上传加服务端合并以后，问题才真正解决。这套方案里很多细节不踩坑是想不到的，下面逐一拆解。
2. 为什么要用分片上传，而不是整包提交
2.1 整包上传的三个硬伤
直接FileStream读进内存或者StreamContent丢给HTTP客户端，表面看代码最少，但实际跑起来有三个问题。
第一是内存不可控。StreamContent会尝试把流读完，如果文件是2GB，内存占用轻松超过1.5GB，32位进程更是直接崩。第二是网络容错差。传统HTTP请求一旦连接中断，整个文件要重传，2GB的文件重传一次的成本太高。第三是进度不可见。大多数上传组件的进度回调只能做到整体百分比，遇到大文件或者网络波动，UI上半天不动，用户体验很糟糕。
2.2 分片方案的核心逻辑
分片上传的思路很简单：把大文件切成固定大小的块，比如每块5MB或者10MB，然后逐块上传，服务端接收完所有分片后按顺序合并。这样做的好处首先是内存占用极低，每块读入缓冲、上传、释放，峰值内存只有几个MB。其次是天然支持断点续传，哪块没传成功就重传哪块，不用整文件重来。再次支持多线程并发，多个分片同时上传能显著提升带宽利用率，尤其在高延迟网络下效果明显。
文件夹上传本质上也是分片思路的延伸，只不过分片的对象从“大文件的块”扩展为“每个独立文件的分块”，再加上一个元数据清单来描述文件夹结构。
下面用一个表格直观对比几种常见方案：
| 方案 | 内存占用 | 断点续传 | 并发能力 | 实现复杂度 |
|---|---|---|---|---|
| 整包Stream提交 | 高 | 无 | 无 | 低 |
| 单文件分片上传 | 低 | 支持 | 支持 | 中 |
| 文件夹递归+分片 | 低 | 支持（按文件粒度） | 高 | 高 |
| 自定义二进制流协议 | 极低 | 支持 | 高 | 极高 |
对于绝大多数业务场景，方案“文件夹递归+分片”是性价比最高的选择。
3. 跨平台目录递归与文件分片核心实现
3.1 用跨平台API实现目录遍历
这一节直接上代码，重点说明实现思路。
public static List<FileEntry> EnumerateFolder(string rootPath) { var entries = new List<FileEntry>(); var stack = new Stack<string>(); stack.Push(rootPath); while (stack.Count > 0) { var dir = stack.Pop(); try { foreach (var subDir in Directory.EnumerateDirectories(dir)) { stack.Push(subDir); } foreach (var file in Directory.EnumerateFiles(dir)) { var info = new FileInfo(file); var relativePath = Path.GetRelativePath(rootPath, file); entries.Add(new FileEntry { RelativePath = relativePath, FullPath = file, Length = info.Length, LastWriteTimeUtc = info.LastWriteTimeUtc }); } } catch (UnauthorizedAccessException) { // 跳过无权限的目录，记录日志后继续 continue; } } return entries; }需要注意的两点：一是用Path.GetRelativePath而不是直接拼接字符串，因为Windows用反斜杠\，Linux和macOS用正斜杠/，直接拼会在跨平台时产生兼容问题。二是不要用递归函数遍历深层次目录，用Stack<T>迭代遍历可以避免深目录导致栈溢出。
3.2 文件分片读取与哈希校验
分片读取要避免一次性读入整个文件，而是用固定大小的缓冲循环读取。
public static async IAsyncEnumerable<byte[]> ReadChunksAsync(string filePath, int chunkSize, [EnumeratorCancellation] CancellationToken ct = default) { using var fs = new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.Read, 64 * 1024, FileOptions.Asynchronous | FileOptions.SequentialScan); long remaining = fs.Length; while (remaining > 0) { ct.ThrowIfCancellationRequested(); int readSize = (int)Math.Min(chunkSize, remaining); byte[] buffer = new byte[readSize]; int readCount = await fs.ReadAsync(buffer.AsMemory(0, readSize), ct); if (readCount == 0) break; yield return buffer; remaining -= readCount; } }FileOptions.SequentialScan是关键细节，它告诉操作系统这是一个顺序读取场景，可以禁用缓存预取的部分优化，对大文件顺序读有实际性能提升。每块读取后建议计算一次MD5或SHA256，作为分片的完整性标识。校验值建议用Convert.ToHexString转成十六进制字符串，比传统BitConverter.ToString().Replace("-", "")更简洁，.NET 5以上都支持。
提示：分片大小建议控制在4MB到16MB之间。小于4MB会导致分片请求次数太多，网络往返开销占比高；大于16MB则失去断点续传的粒度优势。我实测下来10MB是较为均衡的取值。
4. 并发调度与断点续传的设计
4.1 并发控制不能无脑开线程
很多人提到并发上传就直接同时开几十个任务，结果要么服务器拒绝连接，要么本地网络被挤爆。正确的做法是使用SemaphoreSlim控制最大并发数。
using var semaphore = new SemaphoreSlim(4); // 控制最多4个分片并发上传 var tasks = new List<Task>(); foreach (var chunk in chunks) { await semaphore.WaitAsync(ct); tasks.Add(Task.Run(async () => { try { await UploadChunkAsync(chunk, ct); } finally { semaphore.Release(); } })); } await Task.WhenAll(tasks);为什么并发数选4而不是8或者16？实测经验：大多数家庭宽带的并发上传瓶颈不在CPU，而在网络往返时延和路由器NAT表项。并发太高会导致丢包率上升，反而降低整体吞吐。4到6是个人电脑和普通服务器之间比较稳妥的并发窗口。如果跑在万兆内网，可以适当调高到8。
4.2 断点续传需要知道“哪些分片没传”
断点续传的数据结构一般长这样：
public class UploadSession { public string SessionId { get; set; } public string FileName { get; set; } public long FileSize { get; set; } public int ChunkSize { get; set; } public int TotalChunks { get; set; } public HashSet<int> UploadedChunkIndexes { get; set; } = new(); }流程分三步：
- 上传前先调服务端接口，带上文件大小、文件名、分片大小，服务端返回一个
SessionId，如果是断点续传则返回已有的分片索引列表。 - 客户端过滤掉已上传的分片，只传未上传的部分。
- 所有分片传完后，客户端调用
Complete接口，服务端按分片索引顺序合并。
4.3 已完成分片信息要持久化
客户端断点续传不能只依赖内存中的HashSet，进程一旦退出数据就没了。我建议在本地存储一份会话状态文件，格式简单一点，用JSON序列化到临时目录即可。
var statePath = Path.Combine(Path.GetTempPath(), "upload_session", sessionId + ".json");每次成功上传一个分片就更新一次状态文件。注意写入时要先写临时文件再替换，避免写一半进程崩溃导致JSON损坏。
经验：不要把临时目录硬编码为C盘某个路径，跨平台下推荐用
Path.GetTempPath()，Windows、Linux、macOS都会自动映射到合适的目录。
5. 文件夹上传的元数据协议与组装
5.1 文件夹信息用一次请求上报
文件夹跟单文件最大的区别在于内部有层级结构。如果每个文件单独走一次上传，服务端无法还原目录树，所以必须先上报一份清单。
public class FolderUploadManifest { public string ClientId { get; set; } public string RootName { get; set; } public List<FileEntryMetadata> Files { get; set; } } public class FileEntryMetadata { public string RelativePath { get; set; } public long Length { get; set; } public DateTime LastWriteTimeUtc { get; set; } }客户端遍历完文件夹后，先生成manifest，上传给服务端。服务端拿到清单就知道一共有多少个文件、各自相对路径是什么，然后为每个文件创建独立的UploadSession。客户端再按清单顺序，逐个文件执行分片上传。
5.2 上传中的空目录也要保留
大部分文件夹里存在空目录，这个细节容易被忽略。如果清单里只记录文件，服务端重建目录树时空目录会丢失。建议在manifest里增加一个Directories字段，专门记录相对路径的空目录，以及所有目录的创建时间。
public List<string> EmptyDirectories { get; set; }服务端合并文件后，先创建这些空目录，再写入文件，这样还原出来的结构跟源文件夹完全一致。
5.3 文件名冲突和非法字符处理
跨平台上文件名的合法性规则不一样。Windows不允许文件名包含\ / : * ? " < > |，Linux上除了/和空字符之外基本都允许。用户机器上能创建的文件，服务端不一定能落盘。稳妥的做法是在manifest里给每个文件分配一个序号ID，上传时按序号存储，服务端合并时再用序号查清单恢复路径。这样即使用户在Windows上上传一个文件名包含竖线|的文件，服务端也能无损保存。
6. 服务端接收与合并的实现要点
6.1 接收分片的REST接口设计
服务端接口设计可以用ASP.NET Core的普通Controller，上传接口接收SessionId和ChunkIndex两个参数，文件体直接用IFormFile接收。
[HttpPost("upload/chunk")] public async Task<IActionResult> UploadChunk( [FromForm] string sessionId, [FromForm] int chunkIndex, IFormFile chunk) { var session = await _sessionStore.GetAsync(sessionId); if (session == null) return NotFound("会话不存在"); var chunkPath = Path.Combine(_storageDirectory, sessionId, $"{chunkIndex}.part"); Directory.CreateDirectory(Path.GetDirectoryName(chunkPath)); using var stream = System.IO.File.Create(chunkPath); await chunk.CopyToAsync(stream); await _sessionStore.MarkChunkUploadedAsync(sessionId, chunkIndex); return Ok(new { received = true }); }服务端接收分片时不要做额外的解密解压操作，直接落盘为.part文件即可。合并阶段在最后统一做，能降低IO次数。
6.2 合并文件的内存效率
合并时要避免把整个文件读入内存。用FileStream管道搬运：
using var output = new FileStream(finalPath, FileMode.Create, FileAccess.Write); for (int i = 0; i < totalChunks; i++) { var partPath = Path.Combine(sessionDir, $"{i}.part"); using var input = new FileStream(partPath, FileMode.Open, FileAccess.Read); await input.CopyToAsync(output); }这段代码看起来很简单，但有个隐藏细节：分片索引必须严格按顺序合并，如果某个分片缺失或损毁，合并出来的文件就坏了。所以合并前要先校准分片完整性，核对每个分片的大小和哈希，如果对不上，返回客户端提示重传该分片。
6.3 合并后的清理策略
合并完成后不能急着删除所有分片。我习惯先保留分片24小时，方便做校验和回溯，24小时之后用后台任务统一清理。如果文件有合规审计需求，可以保留更久。删除时注意用Directory.Delete(sessionDir, true)，但会话目录的父级不要乱删，以免误伤其他正在进行的会话。
7. 断点续传恢复流程与进度计算
7.1 精确到字节的进度模型
上传进度不能只算文件数，还要算每个文件的真实字节比例。假设一个文件夹有10个文件，总大小500MB，已经传完第一个100MB的文件，进度不是10%，而是20%。实现方式：
public double CalculateProgress(UploadSession session) { long uploadedBytes = session.CompletedFileBytes + session.UploadedChunkIndexes.Count * session.ChunkSize; return (double)uploadedBytes / session.TotalBytes * 100.0; }CompletedFileBytes是已完成的整个文件的总字节数，单独记录，避免把已完成文件拆成分片百分比时产生计算误差。
7.2 恢复流程的完整代码
public async Task<UploadSession> ResumeOrCreateAsync(string filePath) { var fileInfo = new FileInfo(filePath); var session = await _clientSessionStore.FindByFullPathAsync(fileInfo.FullName); if (session != null && session.FileSize == fileInfo.Length) { // 文件大小没变，认为可以续传 return session; } // 否则创建新会话 var newSession = new UploadSession { SessionId = Guid.NewGuid().ToString("N"), FileName = fileInfo.Name, FileSize = fileInfo.Length, ChunkSize = 10 * 1024 * 1024, TotalChunks = (int)Math.Ceiling(fileInfo.Length / (double)(10 * 1024 * 1024)) }; await _clientSessionStore.SaveAsync(newSession); return newSession; }这里有个技巧：通过文件大小判断文件是否被修改过。如果大小为改变，之前的断点信息还有效；如果大小变了，保守起见作废会话重建，避免分片数据和现文件对不上。进一步还可以比较最后写入时间，不过最后写入时间的精度在不同文件系统上有差异，文件大小是最可靠的初步判据。
8. 网络异常处理与重试策略
8.1 超时和瞬间断网怎么处理
分片上传过程中最常见的异常是HttpRequestException和TaskCanceledException。前者是连接被重置，后者通常是超时。两者都需要重试，但重试策略不一样。
private static async Task<HttpResponseMessage> SendWithRetryAsync( Func<Task<HttpResponseMessage>> sendFunc, int maxRetries = 3) { int delay = 500; for (int i = 0; i < maxRetries; i++) { try { return await sendFunc(); } catch (HttpRequestException) when (i < maxRetries - 1) { await Task.Delay(delay); delay *= 2; // 指数退避 } catch (TaskCanceledException) when (i < maxRetries - 1) { await Task.Delay(delay); delay *= 2; } } throw new UploadException("分片上传重试失败"); }指数退避的时间间隔不宜太大，否则影响整体进度。第一遍500ms，第二遍1s，第三遍2s，最多三次就够了。超过三次不要硬传，把这个分片标记为失败，等用户手动点击“重试”或者自动进入失败队列。
8.2 服务端不稳定的特殊处理
如果服务器返回500错误，可能是服务端临时故障，也可能是代码bug。分片上传对该错误的重试价值不高，但我建议还是重试一次，若再失败就给前端明确的错误信息。服务端返回408（请求超时）或429（限流）时，需要按服务端给出的Retry-After头等待后再试。
9. 实战踩坑记录，分片上传的几个隐藏问题
9.1 大文件预分配磁盘空间的问题
上传2GB以上的文件时，如果本机磁盘不够，会在写入分片时爆出IOException。跨平台下可以用FileStream.SetLength预分配文件大小，提前发现磁盘不足。
using var fs = new FileStream(tempPath, FileMode.CreateNew, FileAccess.Write); fs.SetLength(fileSize); // 先占位不过这招慎用，如果中途退出，会留一个巨大的空洞文件占满磁盘。我现在的做法是合并前检查目标分区剩余空间，不够就提前给用户提示。
9.2 分片上传的同步问题
多个分片同时上传时，服务端对同一个会话目录写入不同分片文件，理论上不冲突，但若使用FileStream且打开了相同的缓存键，可能引发锁冲突。解决方法是每个分片文件单独命名，不要在同一个文件上做并发写入。
另外客户端并发上传分片时，进度UI更新也必须做串行化处理。ProgressBar.Value更新频率不要超过每200ms一次，否则UI线程会被大量进度消息淹没，界面直接卡死。
9.3 文件名编码与传输一致性
文件夹上传中的文件名可能包含中文、日文甚至Emoji。HTTP请求头中传输这种字符串时，必须确保客户端和服务端统一使用UTF-8。JSON序列化默认就是UTF-8，但要注意ASP.NET Core中IFormFile.FileName用的是RFC 6266解析，某些特殊字符会被转义。更稳妥的做法是不用FileName属性还原原始路径，而是用manifest中传的RelativePath字段。
9.4 杀毒软件和系统缓存导致的文件占用
Windows下杀毒软件会扫描正在写入的文件，偶尔造成共享冲突；macOS和Linux下通常没有这个问题。如果遇到上传过程中某个文件突然被占用，给文件流加上FileShare.ReadWrite是比较有效的规避方式。
using var fs = new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete);这样即使杀毒软件打开过文件，也不会阻塞我们的读取。
10. 高效上传的额外加速技巧
10.1 压缩算法在分片层级的效果
文件夹中包含大量小文件时，每个小文件单独上传的元数据开销很大。可以在分片层面对多个小文件做先压缩再上传的优化，即把文件夹按目录分组，每组打成tar包（Linux/macOS）或zip包（Windows），上传后服务端再解压。但这样会牺牲断点续传的粒度，一旦网络波动，整包重传的成本很高。
我的取舍是：单个文件小于1MB的小文件，合并成几个10MB的块上传；大于1MB的文件保持独立分片。既不丢失续传能力，又能明显减少请求数。
10.2 并行压缩与上传重叠
如果不做合并压缩，上传本身是CPU密集型很小的任务，瓶颈在网络。所以没必要在客户端额外开线程做压缩。但如果是服务端合并场景，可以先本地生成分片的校验文件，边上传边计算下一个分片的哈希，用流水线方式减少等待时间。
10.3 自适应分片大小
固定分片大小简单可靠，但在弱网环境下5MB的分片可能连续重试。更智能的做法是记录最近N次上传的成功率，如果超时率高，自动把分片大小降到2MB；如果内网传输速度很快，自动升到32MB。实现上并不复杂，就是多维护一个动态参数。
private static int GetAdaptiveChunkSize(int baseSize, double avgSpeedMbps) { if (avgSpeedMbps < 1) return Math.Max(baseSize / 4, 1 * 1024 * 1024); if (avgSpeedMbps > 20) return Math.Min(baseSize * 2, 32 * 1024 * 1024); return baseSize; }11. 文件一致性校验与服务端校验策略
11.1 全量校验 vs 抽样校验
全部文件都做全量哈希校验，在文件数量巨大时会占用大量CPU和IO时间。我建议对重要内容做全量校验，对普通文件做抽样校验。抽样规则：文件大小超过100MB时，取首块、中间块、尾块分别计算哈希；小于100MB时直接全量计算。这样既能发现大多数传输错误，性能影响又小。
11.2 校验时机的选择
不要每传一个分片就要求服务端返回哈希确认，那样会增加一次网络交互。最好是客户端计算好本分片的哈希，一起随表单发送，服务端接收到分片后校验收到的字节数与哈希是否一致，不一致立刻返回500错误，客户端重传该分片。合并完成后再做一次全文件校验，比较总大小和总哈希。如果总哈希不一致，说明合并过程有问题，这时候从分片阶段排查。
12. 总结一下设计和落地时的核心经验
在C#.NET里做跨平台大文件上传，语言本身提供的API已经足够强大，真正的难度在整体设计。分片大小、并发控制、断点续传、目录清单、服务端合并，每一环都要单独设计，但又要互相耦合好。跨平台不等于简单地用Directory.EnumerateFiles换个环境跑，还需要考虑路径分隔符、文件系统行为差异、并发与IO调度等多个层面。
根据我个人的实践经验，落地时最值得注意的一点是：先定义清楚甲方或业务方要的“上传体验”到底是什么。如果只是给内部工具用，单文件分片就够；如果要给客户拖拽整个项目目录，那文件夹元数据协议就必须提前设计好，不能等到开发后期再加，否则服务端接口和客户端逻辑都要推倒重来。
最后分享一个小技巧：所有跟分片状态、会话状态相关的代码，一定要保证线程安全。用ConcurrentDictionary管理会话，对每个UploadSession内部的HashSet加锁，或者直接用lock同步。我早期做过一个版本没加锁，并发上传时偶发索引丢失，导致最终合并出来的文件损坏，查了半天才定位到是HashSet并发写导致的问题。这种坑在调试阶段很难复现，一旦遇到非常折磨人，建议一开始就做好同步设计。
