简介：面向.NET Core开发人员，这是一份完整的文件上传下载服务示例资源，帮助解决WebAPI项目中如何接收multipart/form-data文件、保存到存储并安全提供下载的常见需求。压缩包共50个文件，大小仅206KB，其中包含25个C#源码文件、9个JSON配置文件、5个项目文件以及前端Demo、Dockerfile、readme等，代码结构与项目配置一目了然，便于直接对照学习和复用。示例覆盖了控制器方法设计、IFormFile上传处理、Content-Disposition与Content-Type响应头设置、流式输出下载、异步与错误处理，以及路径安全和权限验证等要点；同时提供前端调用页与中间件实现，可快速搭建起本地演示环境。目前已有1921人学习下载，适合刚接触.NET Core文件传输、正在设计Web API文件接口的初中级开发者参考实践。通过研读这份资源，可以掌握从上传入口到下载响应的完整链路，并在实际项目中灵活扩展为云存储或分块传输方案。 做文件上传下载服务这个需求，我在项目里前前后后写过好几版。从最初用WebForm里的FileUpload控件一把梭，到后来用.NET Core WebApi独立拆出一套上传下载服务，中间踩过的坑确实不少。尤其是前后端分离的架构下，前端用Vue调用接口上传，传完了还要带着文件名和URL去下载，这里面的细节比想象中多得多。这篇文章把这次做的“.NET Core WebApi文件上传服务+文件下载接口”完整拆解一遍，从设计思路、核心代码、部署注意事项到前端联调问题，全部讲透。
1. 接口设计思路拆解
1.1 这个服务到底要解决什么问题
先理清楚需求场景。企业内部的文档管理系统，操作人员通过Vue页面选择本地文件，点击上传后文件要落到服务器磁盘上，后续其他同事需要根据文件名或文件路径在网页上下载这个文件。表面上看就是两个接口，“上传”和“下载”，实际落地时会牵出一堆问题：大文件怎么传不超时、中文文件名怎么保证不乱码、前端下载时怎么用blob拿到真实文件名、非法文件怎么拦截、文件要不要分目录存放、磁盘路径要不要暴露给前端。
这些需求背后，选型方案其实不止一种。开发这套服务的时候，我把存储方案对比了一遍：
| 存储方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 本地物理磁盘存储 | 实现简单、IO速度快、无额外成本 | 扩展性差、需要自己做备份 | 中小项目、内网系统 |
| 云对象存储（OSS等） | 扩容方便、自带CDN加速、安全稳定 | 引入外部依赖、产生费用 | 公网访问量大、文件多的系统 |
| 数据库二进制存储 | 事务一致性好、方便备份 | 数据库压力大、文件大时性能差 | 少量小文件、强一致场景 |
我这次选的是本地物理磁盘存储。原因很直接：系统是部署在公司内网服务器上，用户量不大，文件量级在几千到几万个之间，本地存储完全够用，而且不需要额外的云资源投入。如果你做公网系统，文件量大，我更建议直接上对象存储，代码逻辑其实差不多，只是把FileStream替换成SDK调用。
1.2 接口粒度的划分方式
文件服务建议拆成三个核心接口：上传单个文件、按文件名下载文件、查询文件信息。批量上传可以作为后续优化，但单文件接口是所有逻辑的基础。
上传接口接收multipart/form-data格式的请求，参数名统一约定为file。下载接口我设计成用相对路径作为参数（例如202503/a8f3...jpg），这里不用文件ID而用相对路径，好处是下载链接可以直接拼出来，配合nginx部署时指向静态目录即可直接回源，灵活性更高。文件查询接口返回文件的URL、原始文件名、大小、上传时间等信息，方便前端生成文件列表。
关于文件名，我坚持“存储名与原始名分离”的策略。服务器上存储时用Guid字符串 + 扩展名，比如a8f3f2e1...jpg，原始文件名存到MySQL表里或者一个映射Json文件里。下载时再根据存储名反查原始名，通过Content-Disposition响应头把原始文件名带给前端。这样能彻底避免中文文件名乱码、特殊字符导致路径异常、以及同名文件互相覆盖的问题。
2. 项目初始化和环境准备
2.1 创建WebApi项目
我用的是Visual Studio 2022 + .NET 8，创建ASP.NET Core Web API项目即可。如果你用的是.NET 6或.NET 7，代码几乎没有差别。
创建项目后，按下面的目录结构整理文件：
FileService/ ├── Controllers/ │ └── FileController.cs ├── uploads/ // 文件存储根目录，运行时自动创建 ├── Program.cs └── appsettings.jsonProgram.cs里需要额外配置两样东西：静态文件中间件和跨域策略。
var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddCors(options => { options.AddPolicy("AllowFrontend", policy => { policy.WithOrigins("http://localhost:5173") // Vue开发服务器地址 .AllowAnyHeader() .AllowAnyMethod(); }); }); var app = builder.Build(); app.UseCors("AllowFrontend"); app.UseStaticFiles(); // 允许直接访问wwwroot下的静态文件 app.MapControllers(); app.Run();跨域这块是前后端分离最常见的坑。Vue开发服务器默认跑在5173端口，WebApi跑在5000端口，两者端口不同一定会有跨域问题。记得把线上前端的域名也加到WithOrigins里，比如http://yourdomain.com。如果你后端将来要部署到nginx后面，由nginx统一转发，那么CORS可以配置成AllowAnyOrigin()简化处理，但生产环境建议还是明确指定域名。
2.2 appsettings.json中的关键配置
文件上传最容易被忽略的就是大小限制。ASP.NET Core默认请求体大小上限是30MB左右，超过这个值接口直接报413或者请求被取消。需要在上传接口上加[RequestSizeLimit]特性，或者在配置文件里明确设置。
{ "FileStorage": { "RootPath": "uploads", "MaxSizeMB": 1024, "AllowedExtensions": [ ".jpg", ".jpeg", ".png", ".gif", ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".zip", ".rar", ".txt" ] }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*" }MaxSizeMB这里我设置成1024MB，也就是1GB，是考虑到企业内部偶尔会传大压缩包和设计稿。如果你做的是公网网盘类应用，建议限制在10MB~50MB，防止上传流量耗尽服务器带宽。后面会讲在代码里如何读取这些配置并进行校验。
3. 文件上传接口实现
3.1 接收文件并做安全校验
上传接口的核心逻辑分四步：参数校验、目录准备、文件落盘、返回结果。直接看代码。
using Microsoft.AspNetCore.Mvc; using System.Text; using System.Text.RegularExpressions; namespace FileService.Controllers; [ApiController] [Route("api/[controller]")] public class FileController : ControllerBase { private readonly IWebHostEnvironment _env; private readonly IConfiguration _config; public FileController(IWebHostEnvironment env, IConfiguration config) { _env = env; _config = config; } /// <summary> /// 上传单个文件 /// </summary> [HttpPost("Upload")] [RequestSizeLimit(1024 * 1024 * 1024)] // 1GB上限，单位是字节 public async Task<IActionResult> Upload(IFormFile file) { // 1. 基本校验 if (file == null || file.Length == 0) return BadRequest(new { code = 1, msg = "文件不能为空" }); var maxMB = _config.GetValue<int>("FileStorage:MaxSizeMB"); var maxBytes = maxMB * 1024 * 1024L; if (file.Length > maxBytes) return BadRequest(new { code = 1, msg = $"文件大小不能超过{maxMB}MB" }); // 2. 扩展名校验 var ext = Path.GetExtension(file.FileName).ToLowerInvariant(); var allowedExtensions = _config.GetSection("FileStorage:AllowedExtensions").Get<string[]>() ?? Array.Empty<string>(); if (!allowedExtensions.Contains(ext)) return BadRequest(new { code = 1, msg = "不支持的文件类型" }); // 3. 获取文件名并清洗（保留原始名，但过滤掉路径字符） var originalName = Path.GetFileName(file.FileName); originalName = Regex.Replace(originalName, "[\\\\/:*?\"<>|]", "_"); // 4. 按月份分目录 var rootPath = Path.Combine(_env.ContentRootPath, _config["FileStorage:RootPath"] ?? "uploads"); var monthDir = DateTime.Now.ToString("yyyyMM"); var saveDir = Path.Combine(rootPath, monthDir); if (!Directory.Exists(saveDir)) Directory.CreateDirectory(saveDir); // 5. 生成存储名并落盘 var storeName = Guid.NewGuid().ToString("N") + ext; var fullPath = Path.Combine(saveDir, storeName); await using (var stream = new FileStream(fullPath, FileMode.Create)) { await file.CopyToAsync(stream); } // 6. 返回相对路径，前端用来拼下载地址 var relativePath = $"{monthDir}/{storeName}"; return Ok(new { code = 0, msg = "上传成功", data = new { url = $"/api/File/Download?fileName={relativePath}", originalName = originalName, size = file.Length, ext = ext } }); } }分目录的这个设计，我强烈推荐。yyyyMM月目录的好处是，每月一个文件夹，后续做定期清理非常方便，比如写个定时任务删除三个月前的目录即可。如果所有文件平铺在uploads根目录下，几万个小文件会让文件系统检索性能明显下降，而且在Windows上用资源管理器打开都会卡顿。
3.2 安全校验和文件上传漏洞的防范
这部分的三个校验点一个都不能少。第一，大小限制防止磁盘被恶意请求塞满。第二，扩展名白名单防止可执行文件被上传。
关于文件上传漏洞，本质上就是用户上传了可执行的脚本文件，并通过请求直接访问到这些文件，从而在服务器执行恶意代码。WebApi项目本身只要能正确配置静态文件中间件，uploads目录不放进wwwroot，就不会被当成可执行文件直接访问。但为了保险，我做了三处防护：
- 扩展名白名单校验，从配置中心读取，方便运维随时调整。
- 存储文件名使用Guid，不暴露用户原始文件名的可猜测规律。
- 上传目录与站点静态目录完全隔离，避免任何通过URL直接访问uploads目录的可能性。
这里有个细节要特别提醒：不要用Path.GetExtension去判断文件的真实类型。扩展名是可以伪造的，一个.docx文件完全可能是exe程序改名的。要严格校验，可以读取文件头字节（Magic Number）进行MIME类型检测。比如JPEG文件的头两个字节是FF D8，PNG是89 50 4E 47。对于一般企业内网场景，扩展名白名单已足够，但如果是公网项目且对安全有要求，建议加上文件头校验，代码也不复杂，网上有很多现成方案。
4. 文件下载接口实现
4.1 下载接口的两种实现方式
下载接口有两种写法，一种是用FileStream手动处理，一种是直接用PhysicalFileResult。我最终采用的是第二种，更简洁，而且能自动处理HTTP Range头，意味着支持断点续传。
/// <summary> /// 下载文件（支持断点续传） /// </summary> [HttpGet("Download")] public IActionResult Download(string fileName) { // 1. 路径合法性校验 if (string.IsNullOrWhiteSpace(fileName)) return BadRequest(new { code = 1, msg = "文件名不能为空" }); var rootPath = Path.Combine(_env.ContentRootPath, _config["FileStorage:RootPath"] ?? "uploads"); var fullPath = Path.GetFullPath(Path.Combine(rootPath, fileName)); // 防止路径穿越攻击：确认解析后的路径仍然在upload目录内 var uploadRootFull = Path.GetFullPath(rootPath); if (!fullPath.StartsWith(uploadRootFull, StringComparison.OrdinalIgnoreCase)) return BadRequest(new { code = 1, msg = "非法文件路径" }); if (!System.IO.File.Exists(fullPath)) return NotFound(new { code = 404, msg = "文件不存在" }); // 2. 从存储路径反推原始文件名（实际应用中从数据库或映射文件查询） var originalName = GetOriginalName(fileName); var contentType = GetContentType(originalName); // 3. 返回文件流，enableRangeProcessing: true 开启断点续传支持 return PhysicalFile(fullPath, contentType, originalName, enableRangeProcessing: true); }GetOriginalName方法在实际项目中是从数据库查询的。我原来的表结构里有三个字段：存储路径、原始文件名、上传时间。如果没接数据库，可简化为直接返回fileName的最后一个路径段。这里展示的是一个简化版本：
private string GetOriginalName(string storagePath) { // 实际项目中从数据库查，这里简单演示 var fileName = Path.GetFileName(storagePath); // 假设数据库里存了原始名，这里先把存储名的Guid部分去掉再补上扩展名 // 完整版本应是从数据库读取：SELECT OriginalName FROM FileInfo WHERE StorePath = @path return fileName; }4.2 MIME类型和中文文件名编码
GetContentType是下载接口中必须处理好的点。如果Content-Type不对，浏览器可能把文件直接当HTML解析展示，而不是触发下载。常见文件的MIME映射如下：
| 扩展名 | MIME类型 |
|---|---|
| .jpg / .jpeg | image/jpeg |
| .png | image/png |
| .gif | image/gif |
| application/pdf | |
| .doc | application/msword |
| .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| .xls | application/vnd.ms-excel |
| .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| .zip | application/zip |
| .txt | text/plain; charset=utf-8 |
ASP.NET Core的FileExtensionContentTypeProvider类可以直接从扩展名推断MIME，不用手动维护一份大字典：
private string GetContentType(string fileName) { var provider = new Microsoft.AspNetCore.StaticFiles.FileExtensionContentTypeProvider(); if (provider.TryGetContentType(fileName, out var contentType)) return contentType; return "application/octet-stream"; }关于中文文件名，这里必须要多说两句。如果你直接return File(stream, contentType, originalName)，生成的Content-Disposition头里的文件名默认用filename="..."格式，中文会被浏览器URL编码成%E4%B8%AD%E6%96%87.pdf，Chrome里一般没问题，但老版本浏览器或者某些下载组件拿到的是乱码文件名。
更稳妥的方案是用RFC 5987定义的filename*=UTF-8''格式，我在项目里让PhysicalFile自动处理了，它内部就是用的这种现代编码。实测在Chrome、Edge、Firefox下中文文件名显示完全正常。如果你遇到有的浏览器下载文件名乱码，可以检查一下是否是中间层（比如nginx反向代理）重写了Content-Disposition头。
5. 前端Vue联调与Blob下载
5.1 前端上传的代码示例
前端我用的是Vue3 + axios。上传部分比较简单，直接FormData打包文件post过去即可。注意不再手动设置Content-Type，axios会依据FormData自动生成带boundary的multipart/form-data头，手动设置了反而容易出问题。
// 上传文件 async function uploadFile(file) { const formData = new FormData(); formData.append('file', file); try { const res = await axios.post('/api/File/Upload', formData, { timeout: 300000 // 大文件上传超时时间要调大 }); if (res.data.code === 0) { console.log('上传成功', res.data.data); return res.data.data; } // 处理错误 } catch (err) { console.error('上传失败', err); } }timeout这个参数值得留意。axios默认超时时间是0（即不超时），但如果我设置了一个固定值比如10秒，上传500MB的大文件时连接还没传完就被掐断了。一定要根据你设置的最大文件大小，合理调整前端超时时间。另外nginx代理上传时也可能有client_max_body_size限制，默认1MB，必须同步修改nginx配置。
5.2 下载时用Blob保存文件并保持文件名不变
下载部分稍微绕一点。如果直接用window.location.href = '/api/File/Download?fileName=xxx'，在同一个域名下确实能触发下载，但有两个问题：一是无法捕获错误（比如文件不存在时返回的JSON会被当文件下载），二是无法动态修改文件名。所以更推荐用responseType: 'blob'配合URL.createObjectURL来做。
async function downloadFile(fileUrl, displayName) { try { const res = await axios.get(fileUrl, { responseType: 'blob' // 关键：把响应体转成Blob }); // 方案一：从响应头Content-Disposition中解析真实文件名 let fileName = displayName; const disposition = res.headers['content-disposition']; if (disposition && disposition.includes("filename*=UTF-8''")) { try { fileName = decodeURIComponent(disposition.split("UTF-8''")[1]); } catch (e) { // 解析失败就用调用方传入的displayName兜底 } } // 创建临时URL并触发下载 const blob = new Blob([res.data]); const blobUrl = window.URL.createObjectURL(blob); const link = document.createElement('a'); link.href = blobUrl; link.download = fileName; document.body.appendChild(link); link.click(); document.body.removeChild(link); window.URL.revokeObjectURL(blobUrl); // 释放内存 } catch (err) { console.error('下载失败', err); } }保持文件名不变的关键就在link.download = fileName这行代码。<a>标签的download属性会覆盖URL末尾的路径名，所以只要fileName解析正确，下载到本地就是原始文件名。还需要特别说明的是，Blob([res.data])外面包了一层新的Blob，因为axios返回的res.data本身就是Blob，如果不转直接赋给link.href也可以，但有些浏览器会把0字节文件或损坏文件写出来，用新Blob重新包一层实测更稳定。
5.3 跨域下载时Content-Disposition的坑
如果你前后端不在同一个域名下，axios请求下载接口时，浏览器出于安全策略，默认不允许前端读取Content-Disposition响应头。这时候我上面写的解析那段代码就走不通了，res.headers['content-disposition']会得到undefined。
解决办法是在后端CORS中间件里显式暴露这个响应头：
policy.WithOrigins("http://localhost:5173") .AllowAnyHeader() .AllowAnyMethod() .WithExposedHeaders("Content-Disposition");WithExposedHeaders会把指定的响应头暴露给前端JS代码，这样axios才能拿到。这个坑我排查了很久才定位到，当时前端一直报文件名undefined，后端用Postman测试却一切正常，其实就是CORS的ExposeHeaders没配。
6. 常见问题与排查实录
6.1 问题速查表
这几类问题基本覆盖了文件上传下载服务从开发到上线的绝大多数故障：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 上传返回413 Payload Too Large | 请求体大小超过默认30MB限制 | 上传接口加[RequestSizeLimit]特性 |
| 前端上传到一半就中断 | nginxclient_max_body_size未调大 | nginx配置里设为client_max_body_size 1024m |
| 下载的文件名全是乱码 | Content-Disposition头编码格式旧 | 用RFC 5987filename*=UTF-8''格式 |
| 前端拿不到Content-Disposition头 | CORS未配置ExposeHeaders | 后端加WithExposedHeaders("Content-Disposition") |
| 下载的文件大小为0字节 | Blob包装错误 | 用new Blob([res.data])包一层 |
| 上传成功后无法通过URL访问图片 | 上传目录没有映射为静态资源 | 部署时配置nginx或IIS虚拟目录指向uploads |
| Windows服务器中文文件名下载报404 | 存储名用了中文导致编码问题 | 强制存储名用Guid，原始名存数据库 |
6.2 部署时容易忽视的细节
如果你的WebApi部署在IIS下，有几点要额外小心。第一，uploads目录要设置IIS应用程序池用户的读写权限，否则上传时Directory.CreateDirectory会报没有权限的异常。第二，如果部署在Linux + nginx环境下，uploads目录挂在var目录或home目录下，要保证dotnet进程有该目录的写权限。实际项目里很多人会因为登录用户没有写权限导致上传接口报500，排查半天发现是权限问题。
还要提醒一个运维层面的坑：我遇到过服务器重启后上传的文件“丢”了的情况。仔细排查才发现，文件并没有真正丢失，而是部署时使用了dotnet publish，发布目录被回收或替换后，uploads目录还在旧目录里。正确的做法是，把uploads目录放在应用外部，比如/var/data/files或者D:\FileStorage，通过配置文件指定RootPath为绝对路径，不要放在项目根目录下面。这样版本升级时，文件不会跟着发布目录一起被覆盖。
6.3 大文件上传优化
如果单个文件超过500MB，一次性流写入磁盘也可能让接口卡很久。这时候有几个优化方向值得考虑：
- 使用分片上传，前端把文件切成5MB一个的分片，后端接收后按顺序合并。
- 加一个上传进度接口，前端定期轮询或使用SignalR推送进度。
- 使用
FileStream写入时，设置FileOptions.Asynchronous，异步IO在高并发下更流畅。
分片上传实现起来代码量不小，这次没展开讲，但它是一个在网盘类系统中非常核心的功能。如果你们企业实际应用有大于1GB的文件传输需求，建议单独做一套分片方案，基础的上传下载接口只解决常规文件就够了。
7. 我的一点经验体会
整套服务从开发到上线，前后花了一天时间，但真正让我觉得有价值的不是那几百行代码，而是调试过程中对HTTP协议和浏览器行为偏好的理解。文件上传下载表面上是文件流处理，本质上是HTTP语义的正确传达——Content-Type要准、Content-Disposition要规范、CORS暴露要全、超时和大小限制要综合考虑前端体验和后端安全。
最后再分享一个小技巧：如果你想在浏览器里快速预览上传的图片而不是强制下载，可以在PhysicalFile前判断一下Content-Type是不是image/*，如果是则去掉filename参数，浏览器就会自动展示图片而不是下载。这个细节在内网和公网系统中都能提升用户体验。
本文还有配套的精品资源，点击获取
