简介：面向.NET Core开发者的一份WebAPI文件服务实战示例，聚焦文件上传与下载的完整实现路径，适合已具备C#与ASP.NET Core基础、希望快速搭建文件服务的中级开发者参考。压缩包共50个文件，约206KB，以25个cs源码文件为核心，辅以9个json配置、5个csproj项目文件及少量js、html前端演示页面，另含Dockerfile与readme说明，整体结构轻量、便于按模块阅读。内容围绕IFormFile接收上传、Content-Disposition与流式响应实现下载，并涉及权限验证、路径安全、文件类型限制、异步与分块传输、缓存策略及日志记录等要点，还包含中间件与缩略图处理等扩展模块。已有1922人学习，可帮助读者理解控制器、服务与配置的组织方式，并对照自身项目做调整与扩展。
1. 从一次“上传成功但下载 404”说起
文件上传下载这件事，看起来是 Web 开发里最没有技术含量的部分：前端选文件、后端存盘、给个地址下载，完事。但真把它放到 .NET Core WebApi 里做成一个能上生产的服务，问题就全冒出来了——大文件上传超时、中文文件名乱码、下载时内存被撑爆、静态目录被意外暴露、并发写同一个文件互相覆盖。我见过不止一个项目，上传接口在本地跑得好好的，一部署到服务器就变成“上传成功但下载 404”，排查半天发现是保存路径用了相对路径，工作目录和预期不一致。
这篇要拆的是一份 .NET Core WebApi 文件上传下载服务的完整实现资源，核心就是围绕IFormFile接收、流式落盘、受控下载这条主线，把接口设计、存储策略、安全边界和性能参数讲透。它适合正在用 ASP.NET Core 做后端、需要给业务系统补一个文件服务模块的开发者，也适合已经写过上传接口但被大文件和并发坑过的熟手。下面按“这套服务怎么搭 → 关键参数怎么设 → 坑在哪 → 怎么验证”的顺序走一遍，能直接照着复现。
2. 接口与存储设计：IFormFile 接收、流式落盘与受控下载
先把整体结构立住。一个合格的文件服务至少要有三个动作：上传、下载、删除（或元数据查询）。很多人一上来就把文件存到wwwroot下，然后开UseStaticFiles，觉得这样下载最省事。这个做法在 Demo 里没问题，但在真实业务里等于把整个存储目录暴露成公开静态资源，任何人猜到文件名就能拿，权限控制形同虚设。所以这套实现的第一条设计原则是：文件不放在静态目录，下载必须走控制器动作，由服务端决定谁能拿。
2.1 上传接口：为什么用 IFormFile 而不是 Base64
ASP.NET Core 接收文件的标准入口是IFormFile，它来自multipart/form-data请求体。有人喜欢让前端把文件转成 Base64 塞进 JSON，理由是“统一走 JSON 好处理”。这个选择在小文件上无所谓，但文件一大就翻车：Base64 会把体积膨胀约 33%，而且整个字符串要先在内存里拼出来，几百 MB 的文件直接把内存打满。IFormFile则是流式的，框架会把超过阈值的内容缓冲到临时文件，不会一次性吃光内存。
上传动作的最小实现长这样：
[ApiController] [Route("api/[controller]")] public class FilesController : ControllerBase { private readonly IFileStorage _storage; public FilesController(IFileStorage storage) => _storage = storage; [HttpPost("upload")] [RequestSizeLimit(200 * 1024 * 1024)] // 单请求上限 200MB [RequestFormLimits(MultipartBodyLengthLimit = 200 * 1024 * 1024)] public async Task<IActionResult> Upload(IFormFile file, CancellationToken ct) { if (file is null || file.Length == 0) return BadRequest("空文件"); // 只信任扩展名白名单，不信任客户端 ContentType var ext = Path.GetExtension(file.FileName).ToLowerInvariant(); if (!_storage.IsAllowedExtension(ext)) return BadRequest($"不支持的扩展名: {ext}"); // 服务端生成存储名，原始文件名只作为元数据保存 var storedName = $"{Guid.NewGuid():N}{ext}"; await _storage.SaveAsync(file.OpenReadStream(), storedName, ct); return Ok(new { id = storedName, originalName = file.FileName, size = file.Length }); } }这段代码有几个刻意的选择。第一，RequestSizeLimit和RequestFormLimits两个特性都要加，前者管整个请求体，后者管 multipart 表单部分，只加一个在大文件场景下仍会被拦。第二，扩展名白名单在服务端做，绝不依赖前端校验，因为前端校验只是体验，绕过它只需要一个 curl。第三，存储名用 GUID 重新生成，原始文件名只存进数据库或元数据——这一步是后面所有安全问题的总闸，下面会反复提到。
file.OpenReadStream()返回的是只读流，配合SaveAsync里的FileStream做CopyToAsync，就是流式落盘，内存占用与文件大小基本无关。这里有个参数值得说：CopyToAsync可以传 bufferSize，默认 81920 字节，一般够用；如果磁盘 IO 是瓶颈，调到 1MB 左右能减少系统调用次数，但别调太大，否则小文件反而浪费。
2.2 存储层：本地磁盘的目录分片与并发写
存储层单独抽一个IFileStorage接口，是为了以后能换对象存储而不动控制器。本地磁盘实现里，最容易被忽略的是单目录文件数。所有文件平铺在一个目录下，文件数上万之后，某些文件系统的目录索引会明显变慢，列目录、删除都卡。常见做法是按日期或哈希前缀分片：
public async Task SaveAsync(Stream source, string storedName, CancellationToken ct) { // 用存储名前两位做一级分片，避免单目录文件过多 var shard = storedName[..2]; var dir = Path.Combine(_rootPath, shard); Directory.CreateDirectory(dir); var fullPath = Path.Combine(dir, storedName); // FileMode.CreateNew：同名文件已存在时抛异常，防止并发覆盖 await using var fs = new FileStream( fullPath, FileMode.CreateNew, FileAccess.Write, FileShare.None, bufferSize: 81920, useAsync: true); await source.CopyToAsync(fs, ct); }FileMode.CreateNew这个参数是并发安全的关键。如果用Create，两个请求拿到同一个存储名时会互相覆盖，虽然 GUID 碰撞概率极低，但“极低”不等于零，而且这个参数成本为零。FileShare.None保证写入期间别人打不开这个文件，读请求要么等要么失败，不会读到写了一半的残缺内容。useAsync: true让FileStream走真正的异步 IO，而不是在线程池里假异步。
分片策略用存储名前两位，是因为 GUID 的十六进制字符分布均匀，256 个分片足够撑到百万级文件。如果业务量更大，改成两级分片（前两位 + 后两位）即可，改动只在Path.Combine那一行。
2.3 下载接口：FileStreamResult 与 Range 支持
下载接口的核心诉求是“大文件不占内存”和“支持断点续传”。前者靠FileStreamResult而不是File(byte[])，后者靠框架对 Range 请求头的原生支持。实现如下：
[HttpGet("download/{id}")] public async Task<IActionResult> Download(string id, CancellationToken ct) { // id 只允许十六进制字符，杜绝路径穿越 if (!Regex.IsMatch(id, "^[a-f0-9]{32}\\.[a-z0-9]{1,8}$")) return BadRequest("非法文件标识"); var meta = await _storage.GetMetaAsync(id, ct); if (meta is null) return NotFound(); var stream = _storage.OpenRead(id); // 返回 FileStream，seekable // enableRangeProcessing: true 让框架处理 Range 头，支持断点续传 return File(stream, "application/octet-stream", meta.OriginalName, enableRangeProcessing: true); }这里有两个细节。第一，id用正则白名单校验，只允许“32 位十六进制 + 扩展名”的格式。这一步不是多余的，因为id最终会拼进文件路径，如果不校验，传个../../appsettings.json就能读到配置文件，这是文件服务最经典的路径穿越漏洞。第二，File(...)的第四个参数enableRangeProcessing: true打开后，客户端带Range: bytes=0-1023就能只拿前 1KB，视频拖动进度条、下载器多线程分段都靠它。默认是关闭的，很多人不知道要显式打开。
FileStreamResult在响应结束时由框架负责释放流，所以不要在控制器里using掉它，否则响应还没写完流就关了，客户端拿到的是截断文件。这个坑后面还会提。
3. 参数与配置：请求体上限、Kestrel 与超时怎么调
接口写对了，部署上去还是可能失败，因为 ASP.NET Core 对请求体大小、超时、并发都有一层默认限制，这些限制分散在 Kestrel、MVC、表单解析三个地方，只改一处往往不够。这一章把需要动的参数集中列出来，并说明每个参数管的是哪一段。
3.1 三层请求体限制的优先级
大文件上传失败，最常见的报错是413 Payload Too Large或Request body too large。这个限制有三层，从外到内依次是 Kestrel 的MaxRequestBodySize、MVC 的RequestSizeLimit、表单的MultipartBodyLengthLimit。任何一层超限都会拦下请求，所以要么统一调大，要么在接口上单独放开。
| 层级 | 配置位置 | 默认值 | 作用范围 |
|---|---|---|---|
| Kestrel | KestrelServerOptions.Limits.MaxRequestBodySize | 30MB | 整个服务器 |
| MVC | [RequestSizeLimit]/[DisableRequestSizeLimit] | 继承 Kestrel | 单个动作 |
| 表单 | [RequestFormLimits]的MultipartBodyLengthLimit | 128MB | multipart 解析 |
全局配置写在Program.cs里：
builder.WebHost.ConfigureKestrel(o => { // 全局上限 200MB，与接口特性保持一致 o.Limits.MaxRequestBodySize = 200 * 1024 * 1024; // 请求头超时，慢速攻击防护 o.Limits.RequestHeadersTimeout = TimeSpan.FromSeconds(30); });注意MaxRequestBodySize设成null表示不限制，这在公网服务上等于给自己挖坑，一个恶意大文件就能把磁盘写满。正确做法是设一个业务能接受的上限，再在个别需要更大文件的接口上用[DisableRequestSizeLimit]单独放开，而不是全局放开。我一般会把全局值设成“普通接口够用”的大小，大文件走独立接口，这样攻击面小很多。
3.2 超时与取消令牌的配合
上传大文件时另一个高频问题是“传到一半连接断了”。除了网络因素，服务端有两个超时在起作用：Kestrel 的KeepAliveTimeout（默认 130 秒）和RequestHeadersTimeout。请求体传输本身没有硬超时，但客户端如果长时间不推进，连接会被回收。更稳妥的做法是把CancellationToken一路传到CopyToAsync，客户端断开时立刻停止写盘，避免留下半截文件：
public async Task<IActionResult> Upload(IFormFile file, CancellationToken ct) { // ct 在客户端断开时触发，CopyToAsync 会抛 OperationCanceledException try { await _storage.SaveAsync(file.OpenReadStream(), storedName, ct); } catch (OperationCanceledException) { // 清理已写入的部分文件，防止孤儿文件堆积 _storage.TryDelete(storedName); return StatusCode(499); // 客户端关闭请求 } return Ok(new { id = storedName }); }CancellationToken由框架自动注入，不需要手动创建。关键是catch里要做清理——如果不清理，每次上传中断都会在磁盘上留一个不完整文件，时间长了存储目录里全是垃圾，而且这些垃圾没有元数据记录，永远查不到来源。这是我在实际项目里踩过的坑，后面避坑章节还会展开。
3.3 反向代理层的独立限制
如果服务前面挂了 Nginx 或同类反向代理，它有自己的client_max_body_size，默认通常 1MB。这时候你会发现接口特性都调大了，请求还是在代理层被 413 拦掉，而且后端日志里什么都看不到——因为请求根本没到应用。排查这类问题的第一反应应该是“看代理层日志，不是看应用日志”。代理层的配置不在代码里，但部署清单里必须写上，否则换台机器就复现一次。
4. 避坑清单：中文名乱码、路径穿越与流释放
这一章集中写四类真实踩过的坑，每条按“现象 → 原因 → 解决”走。这些问题的共同点是：本地开发环境往往不出现，一到生产或者换客户端就冒出来。
4.1 中文文件名下载后变成乱码
现象：上传时文件名是“测试报告.pdf”，下载下来变成%E6%B5%8B%E8%AF%95...或者一串问号。
原因：HTTP 响应头里的Content-Disposition对非 ASCII 字符的处理有历史包袱。如果直接把中文塞进filename=，不同浏览器解码方式不一致。RFC 5987 规定用filename*=UTF-8''加百分号编码，但老客户端不认。
解决：让框架处理，不要自己拼响应头。File(stream, contentType, fileDownloadName)这个重载在 ASP.NET Core 里会自动生成同时包含filename和filename*的响应头，兼容新旧客户端。如果确实要手写，两个都带上：
var encoded = Uri.EscapeDataString(meta.OriginalName); Response.Headers.ContentDisposition = $"attachment; filename=\"{encoded}\"; filename*=UTF-8''{encoded}";另外，原始文件名在入库前要做一次规范化，去掉控制字符和路径分隔符，否则某些客户端会把文件名里的/当成目录。
4.2 路径穿越：一个../读到配置文件
现象：安全扫描报告里出现“任意文件读取”，复现方式是请求download/..%2f..%2fappsettings.json。
原因：下载接口把用户传入的标识直接拼进Path.Combine，而Path.Combine遇到..会向上跳目录，遇到绝对路径会直接丢弃前面的根路径。这是文件服务最危险的漏洞，没有之一。
解决：两道防线。第一道是入口正则白名单，只允许固定格式的标识（见 2.3 节）。第二道是拼完路径后做一次规范化校验：
var fullPath = Path.GetFullPath(Path.Combine(_rootPath, storedName)); // 规范化后必须仍在根目录下，否则拒绝 if (!fullPath.StartsWith(Path.GetFullPath(_rootPath) + Path.DirectorySeparatorChar)) throw new SecurityException("路径越界");GetFullPath会把..解析掉，再比较前缀就能拦住所有越界尝试。注意前缀比较要带上目录分隔符，否则/data/files-evil会被误判为在/data/files之下。
4.3 下载大文件时内存暴涨
现象：几个人同时下载几百 MB 的文件，服务进程内存曲线直线上升，严重时触发 OOM。
原因：用了File(byte[], ...)或者先把流ReadAllBytes再返回。字节数组整个驻留内存，并发数一乘就爆。
解决：一律用FileStreamResult，也就是File(Stream, ...)重载。同时确认存储层返回的是真正的FileStream而不是MemoryStream。还有一个隐蔽点：如果中间套了一层BufferedStream且缓冲区开得很大，也会放大内存，下载路径上不要加额外缓冲。
4.4 流被提前释放导致文件截断
现象：下载下来的文件大小比原文件小，或者 PDF 打不开提示损坏，但服务端日志没有任何异常。
原因：在控制器里写了using var stream = ...，方法返回时using作用域结束，流被释放，而框架还没来得及把流内容写进响应。FileStreamResult是延迟执行的，返回IActionResult只是登记了“要写这个流”，真正写发生在后续管道。
解决：交给框架释放，控制器里不要using返回给File(...)的流。如果存储层内部打开了流，确保所有权转移清晰——要么存储层返回流且调用方负责，要么存储层提供回调式写入。这个坑的排查成本很高，因为现象是“偶发文件损坏”，很容易被误判为网络问题。
提示：这四条里，路径穿越和流释放是必须在上线前用测试用例覆盖的，前者是安全问题，后者是数据完整性问题，都不能靠“看起来正常”来判断。
5. 验证与压测：用 curl 和并发脚本确认边界
功能写完不等于能用，文件服务的很多问题只有在特定请求形态下才暴露。这一章给一套可执行的验证方法，覆盖断点续传、大小限制、并发写入三个关键边界。
5.1 用 curl 验证 Range 与响应头
断点续传是否真的生效，看响应状态码和头就能确认。先发一个带 Range 的请求：
# 请求前 1024 字节，期望返回 206 Partial Content curl -i -H "Range: bytes=0-1023" \ http://localhost:5000/api/files/download/abc123...ef.pdf # 检查 Content-Disposition 是否同时含 filename 和 filename* curl -sI http://localhost:5000/api/files/download/abc123...ef.pdf \ | grep -i content-disposition期望看到HTTP/1.1 206 Partial Content、Content-Range: bytes 0-1023/总大小、Accept-Ranges: bytes。如果返回 200 且带完整文件，说明enableRangeProcessing没生效，回去检查File(...)的参数。Content-Disposition里应该同时出现filename=和filename*=，只有前者说明中文兼容性没做全。
5.2 边界值测试：刚好超限与刚好不超限
大小限制的验证要卡边界，不能只测“小文件能传、超大文件被拒”。构造一个刚好等于上限和上限加 1 字节的文件：
# 生成 200MB 和 200MB+1 字节的测试文件 dd if=/dev/zero of=ok.bin bs=1M count=200 dd if=/dev/zero of=over.bin bs=1M count=200 printf 'x' >> over.bin curl -F "file=@ok.bin" http://localhost:5000/api/files/upload curl -F "file=@over.bin" http://localhost:5000/api/files/upload前者应成功，后者应返回 413。如果两个都成功，说明某一层限制没生效；如果两个都失败，说明限制设小了或者单位算错（1024 * 1024写成1000 * 1000是常见笔误）。这个测试在改过任何一层配置后都要重跑，因为三层限制的优先级容易记混。
5.3 并发写入与孤儿文件检查
并发场景下要验证两件事：同名文件不会互相覆盖，中断上传不会留下垃圾。用一个简单脚本并发上传同一批文件，然后对比存储目录的文件数和接口返回的成功数：
# 并发 20 个上传请求 seq 1 20 | xargs -P 20 -I{} \ curl -s -F "file=@ok.bin" http://localhost:5000/api/files/upload # 统计存储目录实际文件数（按分片目录递归） find /data/files -type f | wc -l如果文件数少于成功数，说明有覆盖发生，回去检查FileMode.CreateNew。孤儿文件的验证更直接：上传一个文件，在传输中途Ctrl+C中断，然后看存储目录里有没有残留。有残留说明CancellationToken的清理逻辑没生效，或者清理时用的存储名和实际写入的不一致。
5.4 一个容易漏掉的验证项：删除后的元数据一致性
删除接口如果只删文件不删元数据，或者反过来，都会造成“列表里有记录但下载 404”或者“文件还在但查不到”。验证方法是删除后分别查元数据接口和直接访问文件路径，两者必须同时失效。这个检查在引入缓存之后尤其重要，因为缓存可能让已删除的文件继续可下载一段时间。
| 验证项 | 请求方式 | 期望结果 | 失败时先看 |
|---|---|---|---|
| 断点续传 | 带 Range 头 GET | 206 + Content-Range | enableRangeProcessing |
| 大小上限 | 上传上限+1 字节 | 413 | 三层限制哪层没改 |
| 中文文件名 | 下载后看响应头 | 含filename* | 是否手拼响应头 |
| 路径穿越 | 传../变体 | 400 | 入口正则 + 前缀校验 |
| 并发覆盖 | 并发同名上传 | 文件数=成功数 | FileMode.CreateNew |
这套验证跑一遍大概十几分钟，但能挡掉上线后 80% 的文件服务工单。我现在的习惯是：任何涉及流和路径的改动，提交前都强制走一遍 5.1 和 5.3，尤其是改过存储层之后——流的所有权和路径的规范化这两件事，靠读代码很难确认对错，只能靠请求打进去看结果。希望这套流程能帮你在自己的项目里少返工几次。
本文还有配套的精品资源，点击获取
