.NET Core WebApi 文件服务实战：上传下载陷阱与配置避坑指南

简介一份面向 .NET Core WebAPI 开发者的完整文件上传/下载服务实现方案覆盖文件上传与下载两个核心场景适合需要在 WebAPI 中集成文件处理能力的初中级开发者。资源围绕 multipart/form-data 上传、IFormFile 接收与保存以及下载时的 Content-Disposition、Content-Type、流式输出等关键点展开并兼顾异步处理、权限校验、文件类型限制、路径安全和异常日志等实践能帮读者少走弯路。压缩包共 50 个文件大小约 206KB以 25 个 C# 源码文件为主体配合 9 个 JSON 配置、5 个 csproj 工程文件及前端演示、Dockerfile、说明文档等目录结构清晰适合按示例工程直接对照学习。资源内含多个可运行的服务端示例、中间件和前端演示页便于观察上传下载接口的完整调用链并可直接复用配置类、中间件与部署方案。已有 1921 人学习下载适合希望快速掌握 WebAPI 文件服务搭建思路并在实际项目中扩展或改造的开发者。1. .NET Core WebApi 文件服务上传下载的每个看似正常的返回背后都有参数陷阱接手过权限管理后台的人都会有同感文件上传下载看着只是接一个IFormFile、返回一个FileResult可真要把“.netcore Webapi 文件服务”推到生产环境麻烦一个接一个。默认 30MB 的请求体限制、中文文件名在响应头里变乱码、下载大文件时内存直接飙升这些问题都不是报错抛异常而是“能跑但不对”排查起来比崩溃还费劲。这篇笔记把一套能直接落地的文件服务拆开讲先看 multipart 请求是怎么被框架缓冲的再写流式上传和带 Range 的下载接口接着配好 Kestrel 与 IIS 双重限制、文件头签名校验、路径穿越防护最后把我踩过的五个雷区和应对习惯一并写出来。无论你是刚接触 WebApi 的后端新手还是被线上问题折磨过的老手顺着往下做能少走几天弯路。2. 设计上传接口从 IFormFile 到流式读取先搞清楚缓冲在哪2.1 为什么直接接收 IFormFile 不够multipart/form-data 的组装与缓冲文件上传走的是multipart/form-data协议浏览器或客户端会把表单字段和文件内容用 boundary 分隔符拼成一个请求体。Asp.NET Core 的模型绑定器收到请求后会解析这个 body再把每个文件包装成IFormFile接口塞给你的 Action 参数。听起来很省事但省事的代价是框架在你无感知的情况下做了两次缓冲先读进内存超过阈值后转存到本地临时文件最后才把临时文件路径或内存流交给你。这个阈值受FormOptions.MultipartBodyLengthLimit影响在不同版本里默认值并不一样常见的是 128MB 左右。“文件不大跑起来没问题”通常就指这种情况一旦出现几百 MB 的设计文件、视频素材默认行为会把内存和临时目录同时压垮接口表现就是上传到一半卡住然后莫名返回 500。另一个容易忽略的点是IFormFile的流是不可重读的。你的代码里如果既要保存文件又要计算 SHA256 校验值必须一口气读完再处理别想着先OpenReadStream()读一次再CopyToAsync()读第二次。我见过有人在保存完文件后企图再读一次做 MD5结果拿到的流位置已经在末尾读出来是空数组。所以设计上传接口的第一步不是写代码而是决定你允许的最大文件多大、内存是否扛得住、临时目录磁盘是否够宽裕。这三个问题想清楚再选下面的方案。2.2 动手写上传接口单文件与多文件的 Action 写法与参数说明先看最简单的一组实现。多文件上传用ListIFormFile接收前端只需要在 FormData 里用同一个字段名重复 append 多个文件即可模型绑定会把它们组装成一个列表。下面这个接口把文件直接存到配置好的目录里[HttpPost(upload)] [RequestSizeLimit(200 * 1024 * 1024)] public async TaskIActionResult Upload(ListIFormFile files, CancellationToken ct) { if (files null || files.Count 0) { return BadRequest(new { message 没有接收到文件 }); } var saved new Liststring(); foreach (var file in files) { // 保存时统一使用 GUID 文件名原始文件名写进数据库或单独记录 var ext Path.GetExtension(file.FileName); var newName ${Guid.NewGuid():N}{ext}; var fullPath Path.Combine(_uploadRoot, newName); await using (var stream File.Create(fullPath)) { // 必须用异步拷贝同步 CopyTo 在超大门禁时容易阻塞线程池 await file.CopyToAsync(stream, ct); } saved.Add(newName); } return Ok(new { count saved.Count, files saved }); }逻辑说明RequestSizeLimit特性是 ASP.NET Core 层面对请求体的硬限制单位是字节200 * 1024 * 1024即 200MB。CancellationToken建议从 Action 参数里拿客户端断开连接时框架会触发取消CopyToAsync会抛出OperationCanceledException避免服务端继续傻等已经没人要的请求。文件名用 GUID 重命名是为了避开中文编码和路径穿越风险原始文件名通过另一个字段随表单一起提交或者在上传成功后再调用一次接口做关联。_uploadRoot在构造函数注入IHostEnvironment后拼出绝对路径一定不要直接拿相对路径写文件后面第 4 章会展开。参数说明ListIFormFile里的每个元素对应一个文件块如果你想知道每个文件各自的大小和类型循环里访问file.Length、file.ContentType即可。[RequestSizeLimit]与全局配置是叠加关系最终生效的值是两者中更严格的一方。这里刻意不写[DisableRequestSizeLimit]因为生产环境里基本用不到“不限大小”这种危险设置。2.3 分块读取与缓冲区设置摆脱默认模型的缓冲问题如果你要处理的文件平均大小超过 500MB或者你的部署环境内存只有 1GB那IFormFile模型绑定带来的缓冲就不能忍了。常见做法是绕过模型绑定直接用MultipartReader从Request.Body流式读取每读到一个 section 就处理一个文件全程不落内存。实现起来并不复杂[HttpPost(stream-upload)] public async TaskIActionResult StreamUpload(CancellationToken ct) { var boundary MediaTypeHeaderValue.Parse(Request.ContentType).Boundary; if (boundary null || string.IsNullOrEmpty(boundary.Value)) { return BadRequest(new { message Content-Type 缺少 boundary }); } var reader new MultipartReader(boundary.Value, Request.Body); MultipartSection? section; var savedCount 0; while ((section await reader.ReadNextSectionAsync(ct)) ! null) { if (!section.AsFileDownloadInfo().FileName.HasValue) { // 跳过普通表单字段 continue; } var fileName section.AsFileDownloadInfo().FileName.Value; // 注意这里依旧要重命名原因同上 var fullPath Path.Combine(_uploadRoot, ${Guid.NewGuid():N}_{Path.GetFileName(fileName)}); await using var output File.Create(fullPath); await section.Body.CopyToAsync(output, ct); savedCount; } return Ok(new { count savedCount }); }逻辑说明MultipartReader是Microsoft.AspNetCore.WebUtilities命名空间下的类型它做的事是按 boundary 切分Request.Body每个 section 都是一个独立的流。AsFileDownloadInfo()扩展方法用于尝试把 section 识别为文件如果返回的空值说明这截内容是普通表单字段。这里没有额外设置缓冲区大小CopyToAsync内部有默认的 81920 字节缓冲区对你来说并不需要去调它除非你做性能压测时发现磁盘 IO 成为瓶颈那时才考虑引入自定义缓冲流。比起IFormFile流式读取最大的优点是无论文件多大服务端内存占用都稳定在几 MB 内临时目录也不会被撑爆。缺点是失去了模型绑定给你的字段自动 mapping所有表单字段都要从 section 里手动解析。所以我的习惯是内部系统、文件可控的情况下用IFormFile快速交付面向公网或接收大文件时一律走MultipartReader流式方案。很多人只把代码停在“能跑通”等你真的部署到内存只有 512MB 的云主机上传 1GB 文件时就会发现到底是哪个方案靠谱。3. 下载接口文件流 vs 物理路径Range 与文件名编码都要带3.1 两种返回方式PhysicalFile vs FileStream 的取舍下载接口比上传简单得多但依然有选型问题直接返回物理路径对应的文件还是手动打开 FileStream 再返回大多数静态文件场景下用PhysicalFile是最省事的写法[HttpGet(download/{id})] public IActionResult Download(int id) { var fileRecord _fileRepo.GetById(id); if (fileRecord null || !System.IO.File.Exists(fileRecord.StoragePath)) { return NotFound(new { message 文件不存在或已被清理 }); } // enableRangeProcessing: true 才会支持断点续传和视频拖动 return PhysicalFile( fileRecord.StoragePath, application/octet-stream, fileRecord.OriginalName, enableRangeProcessing: true); }逻辑说明PhysicalFile会直接通过PhysicalFileResult把磁盘文件作为响应输出框架内部使用FileStream分块读取不需要你手动管理流对象的释放。fileRecord.StoragePath是文件落盘后的完整物理路径fileRecord.OriginalName就是我们要让浏览器保存的文件名。这里把enableRangeProcessing显式设为true它会让响应自动带上Accept-Ranges: bytes头并且处理客户端发来的Range请求。那什么时候需要手动FileStream两种情况一是文件并不存在于磁盘比如文件内容是从数据库 BLOB 字段读出来的或者经过实时压缩、加密后的字节数组二是你想自己控制读取缓冲区大小或者要在读取前后加埋点日志。FileStreamResult的写法同样简单var stream new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 81920); return new FileStreamResult(stream, application/octet-stream) { FileDownloadName fileRecord.OriginalName, EnableRangeProcessing true };这里缓冲区 81920 字节是 .NET 默认的 80KB普通场景不用改。但注意一点FileShare.ReadWrite意味着允许其他人同时读写这个文件这在你需要边下载边替换文件时有用。我之前处理过一个报表系统定时任务会在下载过程中重写文件如果只开FileShare.Read下载一半就会抛“文件正由另一进程使用”。这个参数往往是被忽略的坑。3.2 断点续传与 Range什么时候该支持什么时候不该支持Range 请求就是 HTTP 协议里客户端带上Range: bytes0-1023这样的头服务端只返回指定字节段。对视频播放、PDF 在线阅读这类场景是刚需没有它视频拖进度条就会重新下载整个文件。PhysicalFile和FileStreamResult只要开启enableRangeProcessing框架会自动解析 Range 头、返回206 Partial Content并带上正确的Content-Range响应的剩余字节。但这也意味着每次下载请求会多一层判断并且 Range 处理在某些反向代理上可能失效。如果你的文件都是几十 KB 的小图片或是一次性下载后立刻删除的临时文件建议直接把enableRangeProcessing设为false减少不必要的头信息处理。另一个不要盲目支持 Range 的场景是文件在下载过程中会被覆盖或删除因为 Range 请求可能会并发多个有的请求拿到的文件长度和文件实际长度不一致造成下载文件损坏。处理方式是在下载接口开头打快照记录文件长度并确保下载期间文件不被清理线程回收。给一个手动判断是否支持 Range 的习惯文件大于 10MB 且扩展名为.mp4、.pdf、.zip时开启否则关闭。这个阈值不是绝对标准只是我在实际项目中用的经验值。更极客的做法是从数据库里存储的ContentType判断视频类默认开启文档类看用户需求。无论怎么选不要把选择权交给调用方服务端固定行为比动态 header 更可预测。3.3 文件名乱码与 URL 编码Content-Disposition 的坑浏览器保存文件的名称来自响应头Content-Disposition里的filename但 HTTP 头只能传输 ASCII 字符。你直接把“合同文件.pdf”放进filename合同文件.pdf浏览器要么下载成乱码要么被安全策略直接拦截。正确做法是同时提供两个字段ASCII 兜底文件名和 RFC 5987 编码的真实文件名。ASP.NET Core 里当你传fileRecord.OriginalName给PhysicalFile时框架会生成Content-Disposition但不同版本的编码处理并不一致最稳妥的是自己动手改响应头var asciiFallback RemoveNonAscii(fileRecord.OriginalName); var encodedName Uri.EscapeDataString(fileRecord.OriginalName); Response.Headers.Add( Content-Disposition, $attachment; filename\{asciiFallback}\; filename*UTF-8{encodedName});逻辑说明filename后面的部分给老客户端和某些下载工具用必须保证纯 ASCIIfilename*是 RFC 5987 的扩展写法支持 UTF-8 百分号编码现代浏览器优先认后者。RemoveNonAscii这里简单处理即可把非 ASCII 字符替换成下划线或去掉目的只是让兜底名看起来不那么难看。Uri.EscapeDataString会把中文百分号编码但要注意它不会自动加上单引号前的UTF-8前缀必须按规范拼写完整。另外还有一个容易被忽略的点如果你的文件名本身带了双引号或反斜杠上述写法还是会坏最好把文件名里的和\提前替换掉。我见过很多生产系统下载中文文件时显示____.pdf就是因为没有加filename*。排查方法很简单用浏览器开发者工具看响应头如果只有filename且值变成了乱码那就证明编码方向错了。这里要顺手提一句URL 里的/download/文件名这路径本身也要 URL 编码通常前端会用encodeURIComponent处理好服务端[FromRoute]拿到的是解码后的值。如果前端忘了编码路由匹配会失败返回 404。4. 配置与安全上传大小限制、类型校验、路径穿越一次说清4.1 Kestrel 与 IIS 的双重限制少配一个都等于白配文件服务上线后第一个“正常但诡异”的问题是本机跑得好好的部署到 IIS 或反向代理后面就 413 或 404这不是代码逻辑错而是请求在最外层就被拦截了。ASP.NET Core 有多个层级都会做请求体大小限制我把它分成三层看层级默认行为配置位置Kestrel默认约 30MB 的请求体限制builder.WebHost.ConfigureKestrel/ appsettingsASP.NET Core 模型绑定multipart 表单字段大小限制FormOptionsIIS / 反向代理maxAllowedContentLength默认约 30MBweb.config / nginx 配置如果你只在自己的 Controller 上加了[RequestSizeLimit]Kestrel 层没过关请求会被以 413 拒绝如果你只调了 Kestrel但部署在 IIS 下IIS 自己的模块会先拦一道。最保险的做法是在Program.cs里同时配置builder.Services.ConfigureFormOptions(options { options.MultipartBodyLengthLimit 200_000_000; options.ValueLengthLimit 200_000_000; }); builder.WebHost.ConfigureKestrel(options { options.Limits.MaxRequestBodySize 200_000_000; });逻辑说明FormOptions里的MultipartBodyLengthLimit控制整个 multipart body 的最大长度包括文件内容加表单字段ValueLengthLimit控制单个字段值长度。Limits.MaxRequestBodySize是 Kestrel 的全局请求体上限。如果你用了 IIS 部署还要在web.config里加system.webServer security requestFiltering requestLimits maxAllowedContentLength200000000 / /requestFiltering /security /system.webServer这里maxAllowedContentLength单位是字节但它是从 IIS 层面接收整个请求体的上限如果小于 Kestrel 的设置最终就被 IIS 卡死。我一般会把三层统一配到同一数值比如 200MB并备注到部署文档里。验证是否生效的方法是用 curl 上传一个超过限制的测试文件看返回的是 413 还是 200能快速定位是哪层在拦截。还有一个容易记混的概念[RequestSizeLimit]和[DisableRequestSizeLimit]是 per-action 的FormOptions是全局的MaxRequestBodySize是服务器层的。它们之间不是覆盖关系而是多个安全网叠加任何一个拒绝都会失败。某次联调时前端开发坚持说服务端限制了 30MB我查了半天发现appsettings.json里根本没有 Kestrel 配置IIS 也改了但忘了重启应用池整个下午都耗在缓存上。改配置后强制重启一下不做缓存推断。4.2 文件类型校验别只信 Content-Type用文件头签名判断大多数上传接口都要限制文件类型最常见的错误写法是判断file.ContentType比如要求只能是图片就检查ContentType image/jpeg。问题是Content-Type是客户端给的完全可以用任意工具伪造。一个自称image/png的请求体里放个 exe照样能骗过这种校验。正确做法是读取文件开头的几个字节和已知格式的魔数比对。private static readonly Dictionarystring, byte[] FileSignatures new() { { jpg, new byte[] { 0xFF, 0xD8, 0xFF } }, { png, new byte[] { 0x89, 0x50, 0x4E, 0x47 } }, { pdf, new byte[] { 0x25, 0x50, 0x44, 0x46 } }, { zip, new byte[] { 0x50, 0x4B, 0x03, 0x04 } } }; private static bool IsAllowedFile(Stream stream) { var header new byte[8]; var readCount stream.Read(header, 0, header.Length); foreach (var pair in FileSignatures) { var sig pair.Value; if (readCount sig.Length header.Take(sig.Length).SequenceEqual(sig)) { return true; } } return false; }逻辑说明stream.Read会把前 8 个字节读入header然后逐个魔数比较。这里的jpg是三字节 FF D8 FFpng开头是 89 50 4E 47pdf是 25 50 44 46zip是 50 4B 03 04。注意Stream类型在你的IFormFile.OpenReadStream()和section.Body上都一样。调用结束后流的位置已经在第 8 个字节再次拷贝文件时要把位置重置到开头stream.Position 0或者把校验方法改成传入文件路径打开独立只读流来做头校验。参数说明魔数表可以按业务扩展但不要只比对扩展名。有位同事做过一个“允许上传任意附件”的接口觉得不需要校验结果被人传了一个带恶意宏的 Office 文档好在当时只在内网。从那以后我的习惯是能用扩展名白名单就用白名单不能确定的类型统一存成.bin或重命名绝不信任客户端声明。另外一个细节是图片上传场景很多人只校验Content-Length不校验像素尺寸一张损坏的图片可能只有几 KB却报了 200要看具体的业务是否允许这种“空壳文件”。4.3 路径穿越与文件名清理Combine 之后必须 GetFullPath 再验证路径穿越是老生常谈但文件服务里依旧频繁出现。你从IFormFile.FileName拿到的只是一个文件名吗不一定。某些客户端会传../../etc/passwd这样的“文件名”如果你直接用Path.Combine(_uploadRoot, fileName)组合出的路径就可能跳出上传目录。更隐蔽的是 Windows 下文件名里带盘符分隔符C:\xxx或者带通配符和..的组合。一个可靠的防护流程是三步走第一步只用Path.GetFileName截取路径中的最后一段把..和分隔符全部剔除第二步组合绝对路径第三步对组合结果再调一次GetFullPath然后验证前缀是否在根目录内。var safeName Path.GetFileName(fileName); if (string.IsNullOrEmpty(safeName) || safeName ! fileName) { // 只要原始文件名里包含路径信息直接拒绝不要尝试修补 return BadRequest(new { message 文件名不合法 }); } var fullPath Path.GetFullPath(Path.Combine(_uploadRoot, safeName)); var rootPrefix Path.GetFullPath(_uploadRoot); if (!fullPath.StartsWith(rootPrefix, StringComparison.OrdinalIgnoreCase)) { return BadRequest(new { message 检测到目录穿越 }); }逻辑说明Path.GetFileName会把../../a.txt变成a.txt我们要验证它和原始输入是否一样不一样就直接拒绝省得后续同步更名带来歧义。StartsWith比较的是完整路径前缀如果根目录是D:\uploads任何组合结果只要不在这个前缀下都会被拦。大小写用OrdinalIgnoreCase避免 Windows 和 Linux 在C:\场景下的大小写差异影响判断。还有一个容易忽略的点用户上传的文件名如果带了:,*,?,,,,|这些 Windows 非法字符Path.Combine不会报错但File.Create在 Windows 上会抛异常。Linux 上这些字符大多合法但为了避免跨平台部署我在保存前统一做一次非法字符替换foreach (var c in Path.GetInvalidFileNameChars()) { safeName safeName.Replace(c, _); }但因为我们前面已经用了 GUID 重命名原始文件名只存数据库所以非法字符的坑在生产环境里我很少遇到。如果你决定保留原始文件名落盘这一段就是必写的。5. 避坑文件服务五个隐藏雷区现象原因解决一次讲透5.1 大文件上传一半返回 500.30 或连接被重置现象在 IIS 下部署上传 100MB 以上的文件进度条走到一半直接报 500应用池被回收换成 Kestrel 独立部署则提示连接重置。原因ASP.NET Core 处理 multipart 时要写临时文件默认路径在系统临时目录应用池账号对这个目录没有写权限或者临时目录所在的磁盘空间不足。解决先确认临时目录位置System.IO.Path.GetTempPath()在 Linux 上是/tmpWindows 上是C:\Users\xxx\AppData\Local\Temp。给应用池账号加写权限或通过环境变量ASPNETCORE_TEMP指向一个有足够空间的专用目录。更彻底的办法是放弃IFormFile采用第 2 章里的MultipartReader方案自己控制落盘位置。我遇到过的最迷惑版本是小文件一切正常一旦超过某个阈值就 500因为框架在小文件时直接走内存缓冲不需要碰临时目录大文件才会触发临时文件逻辑。这种“只有大文件才出问题”本身就指向了临时目录权限。5.2 上传后保存的文件名变成乱码或 “_”现象从IFormFile.FileName拿到的中文文件名保存后变成问号或乱码下载时也是乱码。原因HTTP 请求头里的文件名默认按 Latin-1 解码前端 FormData 没有显式标注文件名编码服务端Request.Headers里拿到的原始字节已经被错误解码。解决不要依赖客户端的原始文件名上传保存时立刻用Guid.NewGuid()重命名原始文件名通过一个单独的表单字段传输这个字段在 multipart 里是 UTF-8 编码的文本模型绑定可以正确解析。下载时按第 3.3 节的方式用filename*输出。如果你的客户端是浏览器form enctypemultipart/form-data本身就带 UTF-8问题大多出现在自研客户端里遇到这种客户端让它们在文件名字段上主动做 URL 编码服务端解码后再保存。5.3 用 HttpClient 下载大文件时客户端超时现象接口本身用PhysicalFile返回 200浏览器下载没事但某内部服务用HttpClient.GetAsync下载时过了 100 秒就抛TaskCanceledException。原因HttpClient.Timeout默认是 100 秒这个超时是整个响应完成的超时不是首字节超时。200MB 文件在慢速内网里传输超过 100 秒很正常。解决客户端把Timeout调大或者用 .NET 5 里推荐的HttpClient配合SocketsHttpHandler的PooledConnectionLifetime做精细化控制。更好的是流式消费响应using var response await client.GetAsync(url, HttpCompletionOption.ResponseHeadersRead); if (!response.IsSuccessStatusCode) return; await using var source await response.Content.ReadAsStreamAsync(); await using var target File.Create(newFilePath); await source.CopyToAsync(target);逻辑说明HttpCompletionOption.ResponseHeadersRead告诉HttpClient拿到响应头就返回不要等整个 body 缓冲完。ReadAsStreamAsync拿到的是底层网络流CopyToAsync边收边写内存占用和客户端超时风险都大幅下降。注意如果你把Timeout设成无限大那就等于放弃了保护一旦服务端挂起客户端会永远卡着所以超时要结合你的业务文件大小设一个合理值比如 10 分钟。5.4 批量小文件上传反而变慢甚至内存飙升现象一次上传几十个 100KB 的小文件接口耗时比传一个 10MB 大文件还久任务管理器里看到 w3wp.exe 内存涨到几个 GB。原因ListIFormFile模式会把所有文件都先缓冲每个文件都创建一个流对象和临时文件模型绑定的解析开销按文件数量线性增长更糟的是如果你还用了同步CopyTo每个小文件的一次落盘都要等待磁盘同步。解决优先优化客户端让客户端一次性压缩成 zip 上传服务端解压后逐条处理或者改用MultipartReader流式读取每读到一个 section 立刻写入磁盘不堆积在内存。另外要注意FormOptions里MultipartBoundaryLengthLimit的默认值只是防攻击用的不会自动提升性能不要盲目调大。5.5 下载文件名里带逗号或分号保存后名字被截断现象文件名是项目预算,2024.xlsx浏览器下载后变成项目预算扩展名都丢了用命令行工具下载也是截断到逗号为止。原因老式 HTTP 头解析器把filenamea,b.xlsx里的逗号当成自定义参数分隔符引号没有兜住浏览器内部的实际分割逻辑。解决走filename*RFC 5987 编码逗号会被百分号编码成%2C不再作为分隔符存在同时 ASCII 兜底文件名用空格替换逗号和分号var safeAscii Regex.Replace(fileRecord.OriginalName, [^\x00-\x7F], _); safeAscii safeAscii.Replace(,, _).Replace(;, _);我在一个采购系统里为这事折腾了半天对方用 Safari 下载含逗号的文件名始终只能保存到逗号之前。最后把filename*输出后发现Safari 其实优先按filename*解析问题迎刃而解。如果你赶时间记住只要文件名可能包含非 ASCII 或逗号分号一律输出filename*并保证 ASCII 兜底不会破坏头结构。6. 进阶把文件服务做成通用模块中间件记录上传日志与大小6.1 用中间件拦截请求体大小与耗时文件服务上线后你可能需要统计今天上传了多少流量、哪些接口拖垮了服务器。最轻量的做法不是改每个 Action 加日志而是写一个中间件只要请求的 Content-Type 是multipart/form-data就读取ContentLength和耗时记录到日志里。app.Use(async (context, next) { if (context.Request.ContentType?.StartsWith(multipart/form-data) true) { var length context.Request.ContentLength ?? 0; var sw Stopwatch.StartNew(); await next(); sw.Stop(); logger.LogInformation( Upload path {Path}, size {Size} bytes, cost {Cost} ms, context.Request.Path, length, sw.ElapsedMilliseconds); } else { await next(); } });逻辑说明中间件要做的事很简单但注意ContentLength可能在分块传输时不准确要更精确的数值可以配合request.Body的包装流统计实际读到的字节数但包装流会影响性能非必要别做。await next()后面代码能拿到响应状态码可以顺手记录是成功还是 413。这个中间件要注册在UseRouting之后、控制器执行之前顺序影响不大。参数说明Stopwatch要用System.Diagnostics日志等级建议Information但如果你的文件服务是高频接口建议用采样日志比如每 100 个请求记一条否则日志量会吓到运维。记录到数据库时只记录路径、大小、耗时、结果码就够了不要把文件内容写进日志。6.2 一个保存多年养成的小习惯按用户和日期分目录上传文件如果全堆在一个目录里几个月后目录里几万个文件列出目录都要卡几秒。我的习惯是落盘路径按用户ID/日期/文件分三层日期用yyyyMMdd每天一个目录。这样做的好处有三个备份可以按天做增量排查问题能快速定位某用户当天的文件清理过期文件只需要删目录。代码最初听起来多一层目录开销但实际路径拼接并不复杂var subDir Path.Combine(_uploadRoot, userId.ToString(D8), DateTime.Now.ToString(yyyyMMdd)); Directory.CreateDirectory(subDir); var fullPath Path.Combine(subDir, ${Guid.NewGuid():N}{ext});逻辑说明Directory.CreateDirectory在目录已存在时不会报错放心调用。userId.ToString(D8)是为了让用户目录在文件列表里按位数对齐8 位足够大多数系统使用。保存成功后数据库里存的相对路径是userId/yyyyMMdd/文件名下载时再拼根目录转绝对路径。要注意用户 ID 在路径里会被GetFullPath校验如果用户 ID 可能包含..或路径分隔符记得先做和文件名一样的清理。如果系统有匿名上传就统一放到anonymous/yyyyMMdd下。从那以后我每次写完一套文件服务都强制走一遍检查清单上传大小限制三层是否都改了文件名是否 GUID 化下载头是否正确输出filename*落盘路径是否做了GetFullPath前缀校验最后一个动作是拿一个带中文名和逗号的测试文件跑一遍端到端流程。这套流程帮我避掉的坑比印象里的还要多希望也能帮到你。本文还有配套的精品资源点击获取