C# Minimal API文件下载 C#如何从最简API返回一个文件流

Minimal API中应使用Results.Stream()而非FileStreamResult返回文件，需指定contentType和Content-Disposition头；文件流应通过委托延迟打开以避免资源泄漏，并校验路径防止目录遍历。

Minimal API里怎么用FileStreamResult返回文件

Minimal API不支持传统mvc的File()辅助方法，但可以直接构造FileStreamResult并手动设置响应头。关键不是“能不能”，而是必须显式声明Content-Type和Content-Disposition，否则浏览器可能当成文本打开或直接报错。

常见错误现象：System.InvalidOperationException: No service for type 'microsoft.AspNetCore.Mvc.Infrastructure.IActionResultExecutor`1[Microsoft.AspNetCore.Mvc.FileStreamResult]' has been registered——这不是因为你没注册服务，而是你用了return new FileStreamResult(...)但没启用MVC服务（Minimal API默认不带）。

• 正确做法：不用FileStreamResult，改用Results.Stream()（.NET 6+ 内置）
• Results.Stream()自动处理流释放、响应头、分块传输（Transfer-Encoding: chunked），且不依赖MVC服务
• 必须指定contentType，比如"application/pdf"或"application/octet-stream"；不确定类型时慎用"application/octet-stream"，它会禁用浏览器内联预览
• 文件名建议通过headers参数传入Content-Disposition，例如：new Dictionary { ["Content-Disposition"] = "attachment; filename="report.pdf"" }

Results.Stream()如何安全读取本地文件

别直接new FileStream(path, FileMode.Open)然后塞进Results.Stream()——如果请求中途断开，流不会被及时释放，可能造成句柄泄漏或文件被锁住。

正确姿势是把文件打开逻辑放进Stream参数的委托里，让框架在需要时才打开、用完即关：

app.MapGet("/download", (string fileName) => {     var filePath = Path.Combine("uploads", fileName);     if (!System.IO.File.Exists(filePath))         return Results.NotFound();      return Results.Stream(() => System.IO.File.OpenRead(filePath),         contentType: "application/pdf",         headers: new Dictionary         {             ["Content-Disposition"] = $"attachment; filename="{fileName}""         }); });

• 用System.IO.File.OpenRead()而非new FileStream()，前者默认FileShare.Read，避免并发下载时文件被锁
• 路径必须做白名单校验，禁止用户传../../web.config这类遍历路径，否则就是任意文件读取漏洞
• 大文件（>100MB）建议加X-Sendfile或nginx代理转发，避免ASP.NET Core进程长期占用内存和I/O

返回MemoryStream适合什么场景

只适用于小文件（比如生成的二维码图片、CSV内存导出、json压缩包），且内容可完全载入内存。一旦文件超5MB，就该切回Results.Stream()配磁盘文件或数据库BLOB流式读取。

• 用new MemoryStream(data)后，Results.Stream()能自动识别长度并设Content-Length，浏览器可显示进度条
• 别忘了stream.Position = 0，否则从末尾开始读，返回空内容
• 如果数据来自Encoding.UTF8.GetBytes()，contentType设为"text/csv; charset=utf-8"，不然excel可能乱码

为什么Results.File()不能用在Minimal API

Results.File()是MVC专用扩展方法，底层依赖IActionResultExecutor服务，而Minimal API默认不注册这一整套MVC执行器。强行调用会抛InvalidOperationException，提示找不到服务。

有人试过手动services.AddControllers()来“补上”MVC服务，但这会让Minimal API失去轻量性，还可能引发路由冲突或中间件顺序问题。真要复用MVC的File()逻辑，不如直接切回Controller模式——Minimal API的设计初衷本就不为这种场景服务。

真正容易被忽略的是：Results.Stream()的委托是懒执行的，但如果你在里面写了同步IO（比如File.ReadAllText()），整个请求线程会被阻塞。务必用File.OpenRead()这类异步友好的方式，或明确标注async + await配合Results.StreamAsync()（.NET 7+）。