Content-Disposition 是什么
Content-Disposition 指示客户端把响应体当作「内联展示」还是「作为附件下载」，附件模式下还可以指定保存的文件名。文件下载接口、报表导出、备份下载都依赖它。文件名含非 ASCII 字符时要用 RFC 5987 的 filename* 参数编码，否则不同浏览器会出现乱码或文件名被丢弃。
基本信息
| 方向 | 响应头（也可用于 multipart 的表单部分） |
|---|---|
| 取值 | inline（默认，直接展示）、attachment（下载为附件） |
| 文件名参数 | filename= 与 filename*=UTF-8''编码值 |
| 规范 | RFC 6266、RFC 5987（参数编码）、RFC 2183 |
| 典型场景 | 文件下载、报表导出、图片另存为 |
| 安全配合 | X-Content-Type-Options: nosniff |
典型使用场景
- 导出报表后让浏览器弹出保存对话框而不是直接打开
- 下载接口指定带业务含义的文件名，便于用户识别
- 中文文件名在主流浏览器上正确显示，需使用 filename* 编码
- 强制下载 HTML/SVG 等易被当作页面渲染的类型，降低 XSS 风险
- multipart 表单上传时标记各部分的名称与文件名
附件下载响应示例
附件下载响应示例
# 同时给出兼容旧浏览器的 filename 与规范的 filename*
Content-Disposition: attachment; filename="report-2026.xlsx"; filename*=UTF-8''%E6%8A%A5%E8%A1%A8-2026.xlsx
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
X-Content-Type-Options: nosniff
# Nginx 中按后缀强制下载（示意）
# location ~* \.(pdf|zip)$ { add_header Content-Disposition 'attachment'; }取值与行为
| 取值 | 浏览器行为 | 适用场景 |
|---|---|---|
| inline | 尽量在页面内展示 | 图片、PDF 预览 |
| attachment | 弹出保存对话框或直接下载 | 报表、备份、可执行包 |
| attachment + filename | 以指定名称保存 | 英文或 ASCII 文件名 |
| attachment + filename* | 按 UTF-8 解码名称保存 | 中文、带空格或特殊字符的文件名 |
| 只给 filename 给中文 | 不同浏览器表现不一致，可能乱码 | 应改为 filename* 或同时给出两者 |
filename 是历史参数，只宜承载 ASCII 字符；含非 ASCII 时用 filename*=UTF-8''后接百分号编码的值。稳妥做法是两个参数都写，老客户端读 filename，新浏览器优先用 filename*。
文件名参数会被浏览器直接用于保存路径：把用户可控的内容不经净化就拼进响应头，带引号或换行的值可以注入额外的响应头；同时下载的 HTML/SVG 若以 inline 展示，可能被当作页面执行脚本，务必 attachment 配合 nosniff。