简介一套基于 .NET Core WebApi 的文件上传与下载服务实现示例面向后端开发者和需要快速搭建文件接口的团队。项目围绕文件接口的真实需求完整演示了使用 multipart/form-data 表单上传、IFormFile 接收文件并持久化存储以及通过 HTTP GET 请求配合 Content-Disposition 与 Content-Type 响应头触发浏览器下载的流程并重点覆盖权限验证、路径遍历防护、文件名清洗、扩展名白名单等安全策略以及异步控制器、分块传输、缓存和异常日志等性能优化与稳定性措施。压缩包内含 50 个文件以 C# 源码25 个 cs为主另有 9 份 JSON 配置、5 个 csproj 工程文件、前端 JS/HTML 演示、Dockerfile 与 readme 说明整体约 206KB目录分层组织服务端、客户端和前端演示模块便于从入口、控制器到配置项逐步排查。目前已有 1921 人学习浏览可直接对照实现文件上传下载与安全控制适合作为项目落地时的参考模板也可结合云存储或分片上传做二次扩展。1. .net core WebApi 文件上传和文件下载一个看似简单、上生产却总翻车的组合文件上传下载在 .net core WebApi 里一直是「看着简单、做着事多」的模块。很多团队把 CRUD 接口写得飞快一到附件上传、资源下载就开始踩坑上传 50MB 文件直接 413、下载中文文件名乱码、存进去的路径能被人猜到然后被拖走、发布一次站点把用户传的文件全冲掉。用 IFormFile 接收一个文件并落盘十行代码就能跑通但把它做成一个能上生产、敢对外分发的文件服务要处理的是 multipart 解析、请求体限制、路径安全、Range 断点续传、发布目录与存储目录分离这一整条链路。这篇文章从上传接口的最小实现讲起一路讲到下载接口的响应头设计、安全边界和部署配置面向的是那些要给内部系统或对外站点搭一个可靠文件服务的后端工程师。全文以代码和配置为主每段代码后面都会说清楚为什么这么写、参数怎么调、失败时怎么看。2. 先立住上传接口multipart/form-data 与 IFormFile 的最小闭环2.1 上传为什么选 multipart/form-data从 boundary 到缓冲区浏览器和客户端工具上传文件表单的 enctype 基本只有 multipart/form-data 一个选项。它把请求体按 boundary 分隔成多个 part每个 part 自带 Content-Disposition 和 Content-Type文件和普通表单字段可以混在同一个请求里。相比把文件转成 base64 塞进 JSONmultipart 的核心优势是流式服务端不需要等到整个请求体都进内存才开始处理可以边接收边写入磁盘。base64 方案的痛点很直接体积膨胀约 33%而且 JSON 反序列化时整个文件内容会先躺在内存里100MB 的文件至少吃掉 130MB 的托管堆。这个方案在 .NET Core WebApi 里基本只适合几 KB 的小图、小配置超过 10MB 就建议别碰。ASP.NET Core 对 multipart 的解析封装在 IFormFile 里。当 action 参数是 IFormFile 或 IFormFileCollection 时框架会通过 MultipartReader 延迟解析请求体文件数据先写入缓冲区小文件留在内存超过阈值默认约 4MB的部分落到本地临时文件等请求结束再清理。这个机制决定了我们写代码时不太需要担心大文件直接打爆内存但要注意及时复制和释放否则临时文件可能残留。选型上普通业务场景用 IFormFile 就够了如果是要做超大文件上传比如几百 MB 甚至 GB 级、或者想自己控制落盘节奏做秒传和断点续传那就需要绕开 IFormFile直接读 Request.Body 配合 MultipartReader 自己解析。后面第 6 章会讲这个方向先看最小的可用方案。2.2 最小上传接口IFormFile 落盘与参数说明先写一个能直接跑起来的上传 action核心是接收文件、校验、GUID 重命名、流式落盘。[ApiController] [Route(api/files)] public class FileController : ControllerBase { private readonly IWebHostEnvironment _env; private readonly ILoggerFileController _logger; public FileController(IWebHostEnvironment env, ILoggerFileController logger) { _env env; _logger logger; } // POST api/files/upload [HttpPost(upload)] [RequestSizeLimit(100 * 1024 * 1024)] public async TaskIActionResult Upload([FromForm] IFormFile file) { if (file null || file.Length 0) return BadRequest(file 不能为空); // 服务端重新生成文件名原始文件名只保留用于展示 var ext Path.GetExtension(file.FileName).ToLowerInvariant(); var storeName ${Guid.NewGuid():N}{ext}; var storeDir Path.Combine(_env.ContentRootPath, uploads); if (!Directory.Exists(storeDir)) Directory.CreateDirectory(storeDir); var fullPath Path.Combine(storeDir, storeName); await using (var stream new FileStream(fullPath, FileMode.Create)) { await file.CopyToAsync(stream); } _logger.LogInformation(uploaded {FileName} - {StoreName}, {Size} bytes, file.FileName, storeName, file.Length); return Ok(new { id storeName, fileName file.FileName, size file.Length }); } }这段代码有几个参数和设计点值得说清楚。[RequestSizeLimit(100 * 1024 * 1024)]是给当前 action 单独放开请求体上限单位是字节这里放到了 100MB不加这个特性时Kestrel 默认的请求体上限约 30MB超过就 413这是上传接口最常见的第一次翻车点。Path.GetExtension(file.FileName).ToLowerInvariant()只取原文件名的扩展名用于拼到新文件名后面。存储名用 Guid 生成这样做一是避免原始文件名里带中文、emoji、特殊字符导致落盘和下载时编码出问题二是避免文件名变成服务端路径的一部分后面第 4 章会讲路径穿越的安全风险。file.CopyToAsync(stream)是流式复制IFormFile 内部的数据源可能是内存也可能是临时文件这里不需要关心复制完 await using 会自动释放 FileStream。注意接口返回的是id storeName不要把服务器绝对路径返回给前端。前端后续下载时拿这个 id 来请求服务端通过 id 去映射真实文件。2.3 Swagger 里调试上传并解决统一前缀问题用 Swashbuckle 做接口文档时IFormFile 类型的参数会自动渲染成一个文件选择控件不需要额外配置点开就能直接选文件调试上传这是 Swagger UI 对 multipart 的默认支持。真正容易出问题的是项目加了统一前缀之后的 Swagger 404。如果项目里用app.UsePathBase(/api)或者把路由统一加了前缀Swagger 的请求地址不会自动跟着变。常见做法是在 Program.cs 里把 SwaggerEndpoint 的地址补上前缀同时要保证 SwaggerEndpoint 的地址和中间件监听的路径模板一致// Program.cs app.UsePathBase(/api); app.UseSwagger(c { c.RouteTemplate api-docs/{documentName}/swagger.json; }); app.UseSwaggerUI(c { c.SwaggerEndpoint(/api/api-docs/v1/swagger.json, FileService v1); });逻辑说明UsePathBase会让应用感知到/api这个路径前缀所有路由都自动带上UseSwagger的 RouteTemplate 决定 swagger.json 放在哪里UseSwaggerUI里的 SwaggerEndpoint 是浏览器去拉取 JSON 的完整地址必须把路径前缀拼上否则页面出来但接口列表一直是空的控制台能看到请求 404。调试上传时还要记住Swagger 只是一个客户端界面它发出的请求同样受 Kestrel 请求体大小、IIS maxAllowedContentLength 这些服务端限制约束不是 Swagger 里能传大文件就代表线上没问题。3. 下载接口做到能上生产从 FileStreamResult 到 Range 请求3.1 静态文件中间件与控制器下载私有文件必须走控制器下载文件和上传不同实现路径有两条明显分岔。.UseStaticFiles()中间件可以直接把服务器上的某个物理目录映射成 URL 访问还自带 Range 断点续传支持静态资源如图片、ISO、JSON、DLL 文件放进去就能下载。但它的问题是没有鉴权能力只要知道 URL 就能拿凡是放在 WebRootPath 下的文件都有被扫描拖走的可能。适合放那些本来就可以公开给所有人的资源。控制器下载则适合私有文件。接口里先做权限校验、再定位文件、最后用FileStreamResult/File()返回可以接日志、记下载次数、做限流。缺点是 Range 支持需要自己处理或额外配置。两张方案不是互斥的公开资源用静态文件中间件私有附件走控制器。场景推荐方式原因公开的静态资源分发ISO、图片、前端包UseStaticFiles EnableRange性能和 Range 支持是内置的需要登录/鉴权的附件下载控制器 FileStreamResult可以在返回前做权限校验下载行为要记录日志/审计控制器方便在 action 里写日志URL 不能暴露真实文件路径控制器返回内容用 id 映射路径不暴露3.2 控制器下载FileStreamResult、响应头与 iOS 预览问题写一个下载接口前先想清楚文件名编码和 Content-Disposition 这两件事。浏览器判断一个响应是「直接展示」还是「下载保存」看的就是 Content-Disposition 的值inline是内联展示attachment是强制下载。很多同事反馈 H5 在 iOS 上下载文件变成了预览十有八九是接口返回时漏了 attachment或者文件名没做 RFC 5987 编码。[HttpGet(download/{id})] public async TaskIActionResult DownloadFile(string id) { // 只允许单层文件名格式避免路径穿越 if (Path.GetFileName(id) ! id) return BadRequest(invalid id); var storeDir Path.Combine(_env.ContentRootPath, uploads); var filePath Path.Combine(storeDir, id); if (!System.IO.File.Exists(filePath)) return NotFound(); // 实际项目里建议用数据库记录原始文件名这里用 id 占位 var originalName id; var stream System.IO.File.OpenRead(filePath); return File(stream, application/octet-stream, originalName); }逻辑说明这里用System.IO.File.OpenRead返回一个 FileStream 给 File 方法ASP.NET Core 会把它包装成 FileStreamResult 流式输出而不是先把整个文件读进 MemoryStream。这几点很关键大文件下载时如果用了MemoryStream承接100GB 的文件直接把进程内存打爆所以下载的大文件必须走流式。File(stream, contentType, downloadName)的三参重载会自动生成 Content-Disposition 响应头值为attachment; filename...; filename*UTF-8...。其中 filename* 是 RFC 5987 编码专门处理中文文件名。iOS 的 WKWebView 在部分系统版本上对 download 属性不敏感但 WebApi 这侧能做的就是保证 attachment filename* 同时出现前端再配合a download触发预览概率会大幅下降。如果是 Vue 项目里用 axios 拿 blob 再手动触发下载遇到绝对路径 txt 文件被预览多半是请求方式是 GET 直链而非 blob。后端统一提供下载接口后前端只需要window.open(/api/files/download/ id)或创建 a 标签即可。3.3 Range 支持大文件下载与断点续传下载工具、浏览器断点续传、视频播放器在请求文件时通常会在请求头带上Range: bytes0-1023如果服务端返回 200 加完整内容下载工具就只能从头开始返回 206 加Content-Range头才能支持断点续传和视频拖动。UseStaticFiles默认就支持 Range。控制器返回的 FileResult 在 ASP.NET Core 里没有内置的 Range 透传需要自己解析。下面是一个处理单段 Range 的最小实现适用于私有文件下载场景[HttpGet(download-range/{id})] public IActionResult DownloadWithRange(string id) { if (Path.GetFileName(id) ! id) return BadRequest(invalid id); var filePath Path.Combine(_env.ContentRootPath, uploads, id); if (!System.IO.File.Exists(filePath)) return NotFound(); var total new FileInfo(filePath).Length; var range Request.Headers[Range].ToString(); long start 0; var end total - 1; if (!string.IsNullOrEmpty(range) range.StartsWith(bytes)) { var part range[bytes.Length..].Split(-); start long.Parse(part[0]); if (part.Length 1 !string.IsNullOrEmpty(part[1])) end long.Parse(part[1]); end Math.Min(end, total - 1); if (start end || start total) return StatusCode(StatusCodes.Status416RangeNotSatisfiable); } var length end - start 1; var buffer new byte[length]; using (var fs System.IO.File.OpenRead(filePath)) { fs.Seek(start, SeekOrigin.Begin); fs.Read(buffer, 0, buffer.Length); } Response.Headers[Accept-Ranges] bytes; Response.Headers[Content-Range] $bytes {start}-{end}/{total}; return File(buffer, application/octet-stream); }参数说明Range头的格式是bytesstart-end我们只处理单段 Range当客户端没带 Range 时start 默认为 0、end 为文件末尾返回完整内容。416RangeNotSatisfiable是客户端请求的起点超出文件大小时的标准状态码。这个实现用byte[]承载文件片段适合中小文件如果是超大文件不要用这种方式直接用FileStream配合Response.Body分段写入更稳。多段 Range比如视频拖动生成多个片段请求会返回multipart/byteranges实现复杂度高很多生产环境如果走私有下载又要对视频做拖动常见做法是鉴权通过后重定向到带签名 URL 的静态文件路径让UseStaticFiles接管 Range或者直接用成熟的静态文件方案。第 5 章会讲部署时怎么配这一层。4. 上传下载的避坑清单上传漏洞、后缀白名单与路径穿越4.1 后缀过滤的漏洞正则黑名单为什么挡不住上传漏洞现象后端在接收文件时写了一大堆正则做扩展名黑名单exe|php|asp|aspx|jsp全挡了自认为安全。但攻击者把文件名改成info.php.rar或info.phtml在 Apache2 这类对多后缀解析宽容的 Web 服务器上文件可能被当成脚本执行这就是典型的文件上传攻击绕过场景。这类问题在安全靶场里被反复演练核心都是「后端正则和后缀黑名单」与「容器解析规则」之间的错位。原因黑名单永远追不上容器特性。不同 Web 服务器对文件名解析的顺序不同Apache 默认只识别最后一个后缀多后缀时看配置Windows 下还有分号截断成info.asp;.jpg的利用方式大小写、百分号编码又能绕过不严谨的匹配。只要校验逻辑是「允许列表之外都拒绝」的反面总有绕过的空间。解决把方案改成白名单 重命名 隔离三层。白名单只放业务真实需要的扩展名图片、PDF、zip、doc 之类的明确清单。上传的文件一律用 GUID 重命名只保留白名单映射出来的扩展名原始文件名存入数据库落盘文件绝不会叫info.php这类名字。存储目录不要放在站点根目录下或至少让该目录没有脚本执行权限。提示如果业务必须允许任意类型文件上传比如网盘类产品存储目录绝对不能在 Web 根目录里下载只能走控制器且 Content-Type 由服务端映射不让浏览器猜测和渲染。4.2 文件名与路径的坑路径穿越和 Unicode 陷阱现象用户上传一个名为../../../../tmp/passwd的文件或者文件名里带 emoji 和中文结果落盘失败、路径错乱甚至覆盖了服务器上其他目录的文件。原因代码里直接把file.FileName拼进Path.Combine用户输入变成了文件系统路径的一部分。Windows 下文件名末尾的点、空格也会导致创建文件失败。解决上传和下载两端都用同一套防御逻辑。Path.GetFileName(file.FileName)可以先把用户输入里的路径前缀剥掉只保留最终段但更推荐干脆不信原始文件名一律用 GUID 重命名原始文件名单独存数据库字段。下载时同样只接受数据库生成的 id通过 id 查表得到物理路径而不是把用户输入直接拼进路径。Path.GetFileName(id) ! id这个判断就是为了防止下载时传a/../../b这种路径片段。4.3 413 Request Entity Too LargeKestrel、IIS 与 multipart 三层限制现象上传一个 50MB 的文件接口返回 413浏览器控制台看到Request Entity Too Large应用日志里 Kestrel 报MaxRequestBodySize exceeded。原因Kestrel 默认请求体上限约 30MBIIS 的maxAllowedContentLength默认值也一样是 30MB 这个数量级multipart 还有独立的MultipartBodyLengthLimit。三层限制只调其中一层问题照旧。解决把三层一起放开。Kestrel 在 Program.cs 里配置FormOptions 控制 multipart 大小IIS 靠 web.configbuilder.Services.ConfigureFormOptions(o { o.MultipartBodyLengthLimit 200 * 1024 * 1024; o.ValueLengthLimit 200 * 1024 * 1024; }); builder.WebHost.ConfigureKestrel(o { o.Limits.MaxRequestBodySize 200 * 1024 * 1024; });system.webServer security requestFiltering requestLimits maxAllowedContentLength209715200 / /requestFiltering /security /system.webServer参数说明MultipartBodyLengthLimit是 multipart 表单整体的大小上限ValueLengthLimit是单个字段值的上限上传文件时这两个都要比文件大小大。MaxRequestBodySize是整个请求体的总上限。IIS 的maxAllowedContentLength单位是字节209715200 正好是 200MB。如果前面还有 Nginxclient_max_body_size 200m也要配上代理层默认 1MB是大文件上传重灾区。4.4 临时文件与缓冲目录上传接口的内存黑匣子现象接口能跑但并发一高服务器内存飙升或者在系统临时目录里看到大量aspnet-*开头的残留文件几个 GB 没人清理。原因IFormFile 底层把超过阈值的 multipart 内容缓冲到临时文件正常流程下请求结束会清理但如果你自己读Request.Body又没读完或者 action 里提前 return 导致 body 未被全部消费ASP.NET Core 管线的清理逻辑就不会触发临时文件就残留了。内存飙升通常是因为在 action 里手动file.OpenReadStream()后没有释放或者把 IFormFile 直接塞进内存集合等后续再处理。解决上传接口只做一件事——把文件从 IFormFile 复制到目标存储。拿到文件后立刻CopyToAsync用完即释放。不要把IFormFile存在缓存或数据库字段里延迟处理。要在接口返回前确保请求体被完整消费RequestSizeLimit合适的值能避免恶意超长请求拖死管线。排查残留文件时先看系统临时目录确认哪些进程占着文件再回看接口代码有没有提前 return 或分支里漏了读取 body。5. 发布与部署把文件服务跑在真实环境里5.1 发布 webapi 项目存储目录与站点分离发布 webapi 项目后IWebHostEnvironment.ContentRootPath指向发布目录。如果上传文件直接写到这个目录下下一次重新发布时可能被覆盖或删除这是一个很隐蔽的数据丢失隐患。发布 webapi 项目时最常见的文件服务事故就是「发了个版用户传的文件全没了」。常见做法是在 appsettings.json 里配置一个存储根路径让上传下载都走这个配置{ Storage: { RootPath: D:\\FileStorage } }var storageRoot builder.Configuration[Storage:RootPath] ?? Path.Combine(builder.Environment.ContentRootPath, uploads); builder.Services.AddSingleton(new FileStorageOptions(storageRoot));说明生产环境把存储根路径指到数据盘比如 Linux 下的/data/files或 Windows 下的D:\FileStorage与站点代码完全分离。启动时检查目录是否存在不存在就Directory.CreateDirectory避免第一个上传请求因为目录缺失报错。Linux 部署时还要注意运行账号对存储目录有读写权限systemd 服务里的User写的是谁目录属主就要对应。5.2 反向代理与请求链路Nginx/IIS 下的 413 和超时文件服务前面挂 Nginx 时上传链路多了一处 413 高发点Nginx 默认client_max_body_size只有 1MB任何超过 1MB 的请求都会直接在 Nginx 层被挡掉请求根本到不了 WebApi。这是「Swagger 里能传、线上传不了」最典型的场景。server { listen 80; server_name files.example.com; client_max_body_size 200m; client_body_timeout 60s; location / { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 300s; } }参数说明client_max_body_size按业务需要调必须大于等于后端 Kestrel 的限制client_body_timeout是两次 body 读取之间的超时上传慢文件时太短会中断proxy_read_timeout是等待后端响应的超时大文件上传后处理时间较长默认 60 秒在某些慢盘场景不够用。IIS 做反代时对应的点是 URL Rewrite 模块和 requestLimits排查思路一样先在 WebApi 这层用 curl 直接打本地端口确认接口本身正常再逐层检查代理配置。5.3 下载验证与日志curl 实测和 Range 验证文件服务发布后不要直接拿浏览器测下载用 curl 看响应头和实际内容更直观。下载失败时先用 scp 从服务器拉一个本地文件确认网络层通再怀疑应用层很多「客户端下载失败」最后查出来是防火墙端口或代理层问题跟接口代码无关。# 验证下载接口的响应头Content-Disposition、Content-Length curl -I http://localhost:5000/api/files/download/abc123 # 验证 Range 支持请求前 100 字节期望返回 206 和 Content-Range curl -i -H Range: bytes0-99 \ http://localhost:5000/api/files/download-range/abc123# 验证下载内容完整性客户端下载后和服务器源文件比较哈希 sha256sum /data/files/abc123 curl -s http://localhost:5000/api/files/download/abc123 | sha256sum参数说明curl -I发 HEAD 请求只取响应头快速确认 Content-Length 和 Content-DispositionRange: bytes0-99请求前 100 字节响应头里有206 Partial Content和Content-Range: bytes 0-99/文件总字节才说明 Range 没失效。哈希比对是文件服务上线前必做的验证源文件与下载后的内容一致再往上层接业务。日志方面上传和下载接口都要记录完整元数据文件名、大小、来源 IP、耗时、结果状态。这样线上有人传了奇怪的文件、下载被拒、路径不存在都能在日志里定位不需要再问客户端「你刚传的什么文件」。6. 进阶大文件分片上传与秒传验证文件服务跑到 500MB 以上单请求上传开始变得脆弱网络抖动就失败、没有进度条、代理层超时、服务端临时文件占用大。这时候行业里普遍的做法是分片上传前端把文件按固定大小切片常见 5MB-10MB每个切片单独发起一个上传请求后端收到全部切片后合并。实现时切片请求要带上传会话 ID 和序号后端用临时目录存放切片全部就绪后再按序号排序合并成最终文件合并完成后做一次哈希校验再落盘。秒传是对分片上传的补充前端先算整个文件的 SHA-256后端查存储表发现同样哈希的文件已存在直接返回已有的文件 id不再真正上传数据。这个方案对重复上传、多人传同一份文件极其有效能省大量带宽和磁盘。实现秒传时要注意哈希算法的一致性前后端必须用同一种算法哈希值存储时统一小写十六进制。验证这套方案我的习惯是准备一个 200MB 左右的随机文件先算好哈希走完整上传流程再走下载接口拉回来两边哈希一致才算通过。分片合并接口特别容易出现「上传全部成功但下载文件损坏」的问题原因往往是某个切片重复或顺序错乱所以合并代码里必须按序号排序并在合并完成后重算一次完整文件的哈希。做文件服务这几年我的第一条经验是把存储目录放到站点外第二条就是决定文件在服务器上只认 GUID 名字、原始文件名只存在于数据库。这两条守住了后面加权限、加审计、加 CDN 都是顺手的事。希望这篇笔记能帮你在 .net core WebApi 文件上传和文件下载这条路上少走几个弯。本文还有配套的精品资源点击获取