简介这份资源面向.NET Core后端开发者与WebAPI初学者聚焦文件上传与下载服务的完整实现帮助解决multipart/form-data解析、流式响应、权限校验与路径安全等常见痛点。压缩包共50个文件约206KB以25个C#源码文件为核心配合9个JSON配置、5个csproj项目文件、4个JavaScript脚本及Dockerfile、sln、readme等涵盖控制器、中间件、配置模型与前端演示模块结构清晰便于按模块研读。内容围绕IFormFile接收、Content-Disposition与Content-Type响应头设置、异步流处理、分块传输、JWT鉴权、文件名清理与类型限制等要点展开并附有上传、缩略图、负载均衡等中间件示例可帮助读者快速搭建可运行的文件服务骨架理解生产环境下的性能优化与错误日志思路。目前已有1921人学习下载适合需要落地文件服务或查漏补缺的中级开发者参考。1. 从一次上传 500 说起这套 .NET Core WebApi 文件服务到底解决什么生产环境里最容易被低估的接口往往就是文件上传和下载。我见过一个内部系统前端传个 2MB 的 Excel 直接返回 500日志里只有一句Request body too large排查半天才发现是 Kestrel 的默认请求体上限卡住了。类似的血泪经验还有下载大文件时服务端把整个文件读进内存几个人同时拉就 OOM上传目录被脚本文件钻了空子服务器上多出一个莫名其妙的 webshell。这些坑不是框架的锅是文件服务这条链路本身环节多——请求体大小、流式读写、存储路径、后缀校验、并发下载每一环都能翻车。这套 .NET Core WebApi 文件上传下载服务就是把这些环节收拢到一个可复现的工程里基于 ASP.NET Core 的 WebApi 模板提供文件上传、文件下载、列表查询等基础接口配套 Swagger 调试页面能直接在浏览器里试传试下。它适合两类人一类是刚接触 .NET Core、想找一个能跑起来的文件接口样板的后端新手另一类是手里有现成业务、需要把文件上传下载这块单独抽出来做稳的从业者。下面我按「这套服务怎么搭起来 → 上传下载怎么写才不翻车 → 坑在哪 → 怎么验证」的顺序拆一遍参数和代码都能直接抄。2. 把工程跑起来.NET Core WebApi 文件服务的搭建与 Swagger 配置2.1 环境与项目骨架先确认本机环境。这套服务对运行时版本不挑.NET 6/7/8 都能跑我一般用 LTS 版本图个稳。命令行敲dotnet --list-sdks能看到已装的 SDK没有就去装一个。新建工程用内置模板最省事# 创建 WebApi 工程-n 指定项目名 dotnet new webapi -n FileService.Api cd FileService.Api # 加 Swagger 支持.NET 6 模板默认已带 Swashbuckle老模板需手动加 dotnet add package Swashbuckle.AspNetCore # 跑起来看看 dotnet rundotnet new webapi生成的是最小 API 或 Controller 两种风格.NET 6 之后默认走最小 API但文件服务这种多接口场景我更推荐 Controller 风格路由清晰、好维护。如果你拿到的是最小 API 模板手动加一个Controllers目录和FileController即可Program.cs里补上builder.Services.AddControllers()和app.MapControllers()。这里有个新手常踩的点模板生成的Program.cs里app.UseHttpsRedirection()默认开着本地用 HTTP 调试时会被强制跳转Swagger 页面可能打不开。本地开发阶段我会先注释掉这行上线再打开。2.2 Swagger 配置与统一前缀Swagger 是这套服务的调试入口配好了能省掉一半用 Postman 的时间。基础配置在Program.csvar builder WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(c { c.SwaggerDoc(v1, new OpenApiInfo { Title FileService.Api, Version v1, Description 文件上传下载服务接口 }); }); var app builder.Build(); if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(c { // 统一前缀场景下Swagger 的 JSON 地址要跟着改 c.SwaggerEndpoint(/fileapi/swagger/v1/swagger.json, FileService v1); c.RoutePrefix fileapi/swagger; }); } app.UseRouting(); app.MapControllers(); app.Run();这段代码里两个参数值得说清楚。SwaggerEndpoint的第一个参数是 Swagger JSON 的实际路径RoutePrefix是 UI 页面的访问前缀。很多人发布到 IIS 或 Nginx 子路径后遇到not found /swagger/v1/swagger.json就是因为只改了RoutePrefix没改SwaggerEndpoint两者必须对齐。统一前缀的另一种做法是在UsePathBase里设但那样 Swagger 的 JSON 路径也要同步容易漏我一般直接在 Swagger 配置里写死前缀直观。如果整个 API 都要挂统一前缀比如/fileapiController 上可以用[Route(fileapi/[controller])]或者全局约定app.UsePathBase(/fileapi); // 放在 UseRouting 之前注意UsePathBase和 Swagger 的RoutePrefix别重复叠加否则会变成/fileapi/fileapi/swagger这种玄学路径排查起来很费时间。2.3 上传接口从 IFormFile 到流式落盘上传接口的核心是IFormFile。最简版本长这样[ApiController] [Route(api/[controller])] public class FileController : ControllerBase { private readonly string _uploadRoot; public FileController(IConfiguration config) { // 上传根目录从配置读别硬编码 _uploadRoot config[FileStorage:UploadRoot] ?? uploads; } [HttpPost(upload)] [RequestSizeLimit(100 * 1024 * 1024)] // 单请求上限 100MB public async TaskIActionResult Upload(IFormFile file) { if (file null || file.Length 0) return BadRequest(文件为空); // 生成不冲突的存储名保留原后缀 var ext Path.GetExtension(file.FileName); var storedName ${Guid.NewGuid():N}{ext}; var dir Path.Combine(_uploadRoot, DateTime.Now.ToString(yyyyMM)); Directory.CreateDirectory(dir); var fullPath Path.Combine(dir, storedName); // 流式写入避免大文件占内存 await using var stream new FileStream(fullPath, FileMode.Create); await file.CopyToAsync(stream); return Ok(new { storedName, originalName file.FileName, size file.Length }); } }几个参数必须讲透。RequestSizeLimit控制单个请求体上限单位字节不设的话 Kestrel 默认约 30MB超了直接 413。如果整个应用都要放宽可以在Program.cs里配builder.WebHost.ConfigureKestrel(o o.Limits.MaxRequestBodySize 100 * 1024 * 1024)但接口级覆盖更精细。CopyToAsync是流式拷贝文件多大都只占固定缓冲区这是避免 OOM 的关键——我见过有人用file.OpenReadStream()读进byte[]再写几十 MB 的文件并发几个就顶不住。存储名用 GUID 而不是原始文件名是为了防路径穿越和重名覆盖。原始文件名只存数据库或返回给前端绝不直接拼进磁盘路径。目录按yyyyMM分片是为了单目录文件数过多时文件系统性能下降这个习惯在文件量上十万后能救命。2.4 下载接口FileStreamResult 与断点续传下载接口最忌讳把文件整个读进内存。正确姿势是返回FileStreamResult[HttpGet(download/{storedName})] public IActionResult Download(string storedName) { // 防路径穿越只允许文件名不允许带路径分隔符 if (storedName.Contains(..) || storedName.Contains(/) || storedName.Contains(\\)) return BadRequest(非法文件名); var path Directory.GetFiles(_uploadRoot, storedName, SearchOption.AllDirectories) .FirstOrDefault(); if (path null) return NotFound(); var stream new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read); // enableRangeProcessing 打开后支持断点续传 return File(stream, application/octet-stream, storedName, enableRangeProcessing: true); }enableRangeProcessing: true是断点续传的开关客户端带Range头时服务端会返回 206 部分内容。大文件下载、视频拖动进度条都靠它。FileShare.Read允许多个下载请求同时读同一个文件不加的话并发下载会报文件被占用。application/octet-stream是通用二进制类型如果明确知道是图片或 PDF换成对应 MIME 类型浏览器会直接预览而不是下载。路径穿越校验那几行别省。storedName来自 URL攻击者传../../web.config就能读到配置文件这是文件下载接口最经典的漏洞。用Directory.GetFiles按文件名搜索而不是直接Path.Combine也能挡掉一部分拼接攻击。3. 上传下载的边界处理大小限制、并发与存储策略3.1 请求体大小与超时的三层配置文件上传失败十有八九是大小限制没配对。这套服务里限制分三层任何一层没放开都会拦你层级配置位置默认值作用KestrelMaxRequestBodySize约 30MB服务器接收请求体上限MVC/接口[RequestSizeLimit]继承上层单个 Action 上限表单MultipartBodyLengthLimit约 128MBmultipart 表单整体上限三层里最容易被忽略的是表单层。用multipart/form-data上传时即使 Kestrel 和接口都放开了表单解析器还有自己的上限。配置方式builder.Services.ConfigureFormOptions(o { o.MultipartBodyLengthLimit 200 * 1024 * 1024; // 200MB o.ValueLengthLimit int.MaxValue; o.MultipartHeadersLengthLimit int.MaxValue; });超时也要留意。大文件上传耗时长Kestrel 的KeepAliveTimeout和请求超时可能在中途掐断连接。上传接口建议单独放宽或者干脆走分片上传绕开单请求时长问题。3.2 并发下载与文件锁多个客户端同时下载同一个文件时如果打开流时用了FileShare.None第二个请求会抛IOException: 文件正被另一进程使用。正确做法是FileShare.Read允许多读。反过来如果上传时正在写某个文件下载请求恰好命中可能读到半个文件。这套服务用 GUID 命名 先写临时文件再改名的方式规避var tempPath fullPath .tmp; await using (var stream new FileStream(tempPath, FileMode.Create)) { await file.CopyToAsync(stream); } // 写完再原子改名下载端永远看不到半成品 System.IO.File.Move(tempPath, fullPath);File.Move在同一文件系统内是原子操作改名瞬间完成下载端要么看到完整文件要么看不到不会读到中间状态。这个技巧在文件服务里很实用成本几乎为零。3.3 存储策略本地目录还是对象存储这套服务默认落本地磁盘适合单机部署或文件量不大的场景。但本地存储有几个天花板多实例部署时文件不共享、磁盘满了要手动扩、备份麻烦。文件量上去后常见做法是接对象存储MinIO、S3 兼容服务等把CopyToAsync的目标从FileStream换成对象存储 SDK 的上传方法下载接口改成返回重定向或代理流。选型判断很简单单机、内网、文件量十万以内本地目录够用要多实例、要外网访问、要弹性扩容早上对象存储。别等到磁盘告警才想起来迁移那时候历史文件的迁移脚本够写一天。这套服务的接口层做了抽象的话换存储只改实现类Controller 不用动所以搭的时候把存储逻辑抽到单独的IFileStorage接口里是个值得养成的习惯。4. 文件服务的避坑清单五条血泪排查记录4.1 上传成功但文件 0 字节现象接口返回 200磁盘上文件存在但大小为 0。原因通常是读取IFormFile的流之前请求体已经被读过一次或者CopyToAsync的目标流没 flush 就释放。解决确认没有在别处提前读Request.Body用await using确保流正确释放如果用了自定义中间件读 body要开EnableBuffering并重置Position。4.2 发布后 Swagger 页面 404现象本地好好的发布到 IIS 或子路径后访问/swagger提示not found /swagger/v1/swagger.json。原因RoutePrefix和SwaggerEndpoint路径不一致或者反向代理改了路径但应用不知道。解决两者写成同一个前缀反向代理场景在Program.cs里加app.UseForwardedHeaders()并配置ForwardedHeadersOptions让应用感知真实路径。4.3 后缀校验被绕过现象只允许图片但攻击者传shell.php.jpg或改Content-Type就混进来了。原因只校验了扩展名或只信了客户端传来的 MIME。解决扩展名白名单 服务端读文件头魔数双重校验存储时强制用白名单后缀重命名原始名只做展示上传目录禁止执行权限Web 服务器配置里对该目录关掉脚本解析。4.4 大文件下载内存暴涨现象下载接口并发几个大文件后进程内存飙升甚至 OOM。原因用了File.ReadAllBytes或把流读进MemoryStream再返回。解决一律用FileStreamResult或PhysicalFileResult让框架流式发送确认没有在返回前对文件做全量处理。4.5 中文文件名乱码现象下载时文件名变成乱码或%E4%B8%AD。原因HTTP 头里文件名编码方式不对。解决用ContentDispositionHeaderValue设置FileNameStar框架会自动做 RFC 5987 编码var cd new ContentDispositionHeaderValue(attachment) { FileNameStar 中文文件名.pdf }; Response.Headers.ContentDisposition cd.ToString();5. 验证与进阶用 curl 和 Swagger 把接口压一遍接口写完不算完得验证。我习惯先用 curl 把上传下载跑通再上 Swagger 点一遍最后用并发工具压一下。上传验证# -F 走 multipart 后跟本地文件路径 curl -X POST http://localhost:5000/api/file/upload \ -F file./test.pdf \ -H Content-Type: multipart/form-data返回里拿到storedName后验证下载# -o 保存到本地-I 只看响应头确认 Content-Length 和 Range 支持 curl -o downloaded.pdf http://localhost:5000/api/file/download/xxxx.pdf curl -I http://localhost:5000/api/file/download/xxxx.pdf看响应头里有没有Accept-Ranges: bytes有就说明断点续传开了。再测一下 Range 请求# 只取前 100 字节正常应返回 206 curl -r 0-99 http://localhost:5000/api/file/download/xxxx.pdf -o part.bin并发下载用ab或wrk压一下观察内存曲线是否平稳。如果内存随并发线性上涨说明流式没生效回去检查下载接口。Swagger 那边重点确认三件事上传接口的file参数是不是IFormFile类型Swagger 会渲染成文件选择框、下载接口返回类型是不是文件流、统一前缀下 JSON 地址能不能打开。这三样对了前端联调基本不会卡在接口定义上。最后说个我自己的习惯。每次搭文件服务我会在appsettings.json里把上传根目录、大小上限、允许后缀都做成配置项而不是散在代码里。上线前对着配置表逐项确认一遍比事后翻日志找 413 快得多。文件服务这东西平时不出事一出事就是磁盘满、内存爆、被传马把边界参数显式化是唯一能提前拦住它们的办法。从那以后我每次新起文件接口都强制先跑一遍 curl 上传下载加 Range 测试再交给前端。希望帮到你。本文还有配套的精品资源点击获取