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+）。
