Content-Disposition

用法

在标准的 HTTP 响应中，Content-Disposition 头控制浏览器如何向用户呈现内容。将值设为 inline 会告诉浏览器直接渲染内容。将值设为 attachment 则会触发下载对话框。

该头在 multipart/form-data 响应和表单提交中也起作用。multipart 主体的每一部分都包含各自的 Content-Disposition 字段，用于标识表单字段名以及上传文件的可选文件名。各部分的边界在 Content-Type 头中定义。

inline

inline 指令指示浏览器在页面内直接显示内容。当没有 Content-Disposition 时，这是大多数响应的默认行为。

attachment

attachment 指令触发下载提示。浏览器会弹出”另存为”对话框，而不是在视口中渲染内容。

filename

filename 参数为下载的文件建议一个默认文件名。其值用双引号括起，并遵循 ASCII 编码规则。

Content-Disposition: attachment; filename="report.pdf"

filename*

filename* 参数扩展了 filename，支持 ASCII 之外的字符编码。当 filename 和 filename* 同时存在时，filename* 优先。这对于包含非 ASCII 字符的文件名很有用。

Content-Disposition: attachment; filename="document.pdf"; filename*=UTF-8''d%C3%B6cument.pdf

form-data

form-data 指令出现在 multipart 主体各部分中，标识内容属于一次表单提交。

name

name 参数在 multipart 主体各部分中是必需的，用于标识该部分对应的表单字段。

示例

一个响应 CSV 文件下载的服务器设置 attachment 并提供建议的文件名。浏览器会打开一个预填”export.csv”的保存对话框。

Content-Disposition: attachment; filename="export.csv"

一个在浏览器中直接显示 PDF 的服务器使用 inline。浏览器会在其内置查看器中渲染该 PDF，而不是下载文件。

Content-Disposition: inline

在一次 multipart 表单提交中，每一部分都携带各自的 Content-Disposition 字段。name 参数将该部分映射到相应的表单字段，filename 指明上传文件的原始名称。

Content-Disposition: form-data; name="avatar"; filename="photo.jpg"

故障排查

Content-Disposition 的下载和显示问题通常源于指令值不正确或文件名编码错误。

文件以错误的文件名下载。浏览器使用 filename 参数作为默认保存名。缺失或格式错误的 filename 值会导致浏览器回退到 URL 路径或一个通用名称。请确保该值用双引号括起：filename=“report.pdf”。用 curl -I https://example.re/file 验证该头，并检查响应中的 filename 参数。

文件名中的非 ASCII 字符损坏或显示为乱码。filename 参数仅支持 ASCII 字符。对于带有重音字母、CJK 字符或其他非 ASCII 文本的名称，使用编码语法添加 filename* 参数：filename*=UTF-8”d%C3%B6cument.pdf。同时包含 filename（ASCII 回退）和 filename*（编码版本），以在各浏览器间获得最大兼容性。

浏览器忽略 attachment 而内联显示内容。某些浏览器会针对其原生可渲染的内容类型（例如 PDF 和图片）覆盖 attachment。Content-Type 头会影响这一行为。在 attachment 之外设置 Content-Type: application/octet-stream 可对任意文件类型强制下载。浏览器扩展和内置查看器（PDF.js）也可能覆盖该指令。

期望下载时却触发了内联显示。缺失 Content-Disposition 头时，大多数内容类型默认为 inline。服务器必须显式发送 attachment 才能触发下载。在 nginx 中，向相关的 location 块添加 add_header Content-Disposition “attachment”;。在 Apache 中，在或指令内使用 Header set Content-Disposition “attachment”。

filename 与 filename* 的优先级。当两个参数都存在时，filename* 在所有现代浏览器中优先。不支持 filename* 的旧客户端会回退到 filename。请始终同时包含两个参数。filename* 的值必须对特殊字符使用百分号编码：filename*=UTF-8”na%C3%AFve.txt。

框架特定的下载响应辅助方法。大多数 Web 框架都提供设置下载头的内置方法。Django 使用带 as_attachment 参数的 FileResponse。Express 使用 res.download()。Flask 使用带 as_attachment=True 的 send_file()。Rails 使用带 disposition 选项的 send_data 或 send_file。这些方法会处理文件名编码和头格式化，减少手动出错的可能。