在Web开发中，服务端经常需要把生成的报表、图片或压缩包推送给浏览器，并希望浏览器以附件形式下载，而不是就地打开。C#作为主流服务端语言，可以通过设置HTTP响应中的Content-Disposition头，精确控制浏览器的这种行为以及客户端看到的默认文件名。理解该响应头的语法和规范，是写出兼容各浏览器的下载功能的前提。
Content-Disposition头的基础概念
Content-Disposition是HTTP协议中的一个响应头，用于指示响应的内容该以何种形式呈现。它最早在邮件系统中使用，后来被引入HTTP下载场景。该头主要包含两个指令：inline和attachment。inline表示内容应该在浏览器中直接显示，例如PDF若浏览器支持则会预览；attachment则表示应该被下载，通常还会伴随文件名建议。
当使用attachment时，可以通过filename参数给出建议的文件名，例如attachment; filename="report.pdf"。但这里的文件名如果是中文或含有特殊字符，不同浏览器解析方式不一致，容易造成乱码。因此后续规范引入了filename*参数，使用RFC 5987编码来承载UTF-8文件名，提升国际化兼容性。C#开发者在输出该头时，必须清楚这两种参数的区别与 fallback 机制。
inline与attachment的差异
选择inline还是attachment，核心看业务诉求。若用户点击链接期望直接看图片或读文本，用inline更友好；若用户点击的是导出按钮，则必须用attachment触发下载。部分浏览器对特定类型（如文本、图片）即便写了attachment也可能直接打开，这时可配合Content-Type与X-Content-Type-Options头来约束。
从代码层面看，两者只是字符串值不同。但attachment若缺失文件名，浏览器会以URL最后一段作为默认名，往往不够直观。所以实际项目中，attachment几乎总是配合filename或filename*一起出现，以确保用户保存时看到期望的名字。
在ASP.NET Core中设置下载头
ASP.NET Core提供了更现代的文件返回方式。最常见的是使用PhysicalFile或File方法，并指定fileDownloadName，框架会自动帮你拼好Content-Disposition。例如返回物理文件并强制下载，只需一行代码即可，不必手动拼接字符串，能减少编码错误。
如果需求更底层，比如要动态写流，也可以直接操作Response.Headers。这时要注意HeaderNames.ContentDisposition是强类型常量，赋值需用StringValues。手动构造时推荐使用ContentDisposition类，它位于Microsoft.Net.Http.Headers命名空间，能自动处理编码细节。
使用FileResult简化写法
下面的示例展示在Controller中直接返回文件并设定下载名：
using Microsoft.AspNetCore.Mvc;
public class FileController : Controller
{
public IActionResult Download()
{
// 物理文件路径，实际部署请使用安全路径
var path = "/var/files/report.pdf";
// 设定下载时建议的文件名
return PhysicalFile(path, "application/pdf", "月度报表.pdf");
}
}
上述代码中，PhysicalFile的第三个参数就是下载文件名。框架内部会判断浏览器并选择filename或filename*格式，避免中文乱码。这种方式最省心，也是官方推荐做法。
手动构造响应头
当需要完全控制或写自定义流时，可参考以下代码：
using Microsoft.AspNetCore.Mvc;
using Microsoft.Net.Http.Headers;
using System.IO;
public class StreamController : Controller
{
public IActionResult DownloadStream()
{
var bytes = System.Text.Encoding.UTF8.GetBytes("测试内容");
Response.Headers[HeaderNames.ContentType] = "application/octet-stream";
var cd = new ContentDispositionHeaderValue("attachment");
cd.FileName = "测试.txt";
// 框架会自动处理编码
Response.Headers[HeaderNames.ContentDisposition] = cd.ToString();
return File(bytes, "application/octet-stream");
}
}
利用ContentDispositionHeaderValue类型，可以避免手工拼接时漏掉引号或编码错误。它重写的ToString方法会输出符合规范的头值，包括必要时使用filename*。
传统ASP.NET Web Forms中的做法
在旧的Web Forms或一般处理程序（ashx）中，开发者通常直接操作HttpResponse。这时要显式调用AddHeader或设置Response.AppendHeader，并自行处理中文文件名。很多老代码用HttpUtility.UrlEncode处理文件名，但这种方式并非所有浏览器都认，更稳妥的是同时写filename和filename*。
另一个常见坑是调用了Response.Write之后再改头会失效，因为响应已 flush。所以设置头必须在写正文之前完成，且最好调用Response.ClearHeaders或确保没提前输出。以下示例展示ashx中的标准写法。
一般处理程序示例
using System.Web;
public class DownloadHandler : IHttpHandler
{
public void ProcessRequest(HttpContext context)
{
var fileName = "数据导出.csv";
context.Response.ContentType = "application/octet-stream";
// 使用 RFC 5987 编码中文名
var encodedName = System.Net.WebUtility.UrlEncode(fileName);
context.Response.AddHeader("Content-Disposition",
"attachment; filename=" + encodedName + "; filename*=UTF-8''" + encodedName);
context.Response.Write("id,namen1,测试");
}
public bool IsReusable { get { return false; } }
}
这段代码同时提供了filename和filename*，老版本IE可能读前者，现代浏览器读后者，兼顾兼容。注意UrlEncode会把中文转成百分号编码，配合UTF-8''前缀即符合标准。
常见错误与排查思路
实践中，开发者常遇到浏览器把文件当页面打开，或保存时文件名是一串乱码。前者大多是因为写了inline或没写attachment，后者则是直接拼接未编码的中文字符串。还有人把Content-Disposition写成Content_Disposition，下划线导致头被忽略。
另一个隐蔽问题是缓存中间件或反向代理把头过滤掉。此时可用浏览器开发者工具查看响应头原始值，确认服务端确实发出。若头存在但仍不下载，检查Content-Type是否被设为浏览器可内联的类型且缺少X-Content-Type-Options: nosniff。
编码与浏览器兼容对照
下表列出不同策略的兼容性表现：
| 写法 | Chrome | Firefox | 旧IE |
|---|---|---|---|
| filename="中文.pdf" | 乱码 | 乱码 | 可能正常 |
| filename*=UTF-8''中文.pdf | 正常 | 正常 | 忽略 |
| 两者同时写 | 正常 | 正常 | 正常 |
从表中可见，双写是最稳妥的方案。C#里借助现有API大多自动双写，手写时则需留心。
总结与实践建议
控制浏览器下载行为本质就是正确发出Content-Disposition头。新项目优先用ASP.NET Core的FileResult体系，让框架处理细节；维护老代码时，用UrlEncode加双参数写法保兼容。始终在发送正文前设头，并在测试阶段用多浏览器验证文件名与下载动作。
掌握这些之后，你就能在C#后端灵活决定文件是预览还是下载，以及用户看到什么名字，而不再受乱码或意外打开的困扰。
C#Content-Disposition文件下载修改时间：2026-08-03 04:36:36