如何正确使用Content-Disposition实现文件下载？

Question

在实现文件下载功能时，如何正确使用 `Content-Disposition` 响应头来控制浏览器以“下载”而非“预览”方式处理文件？常见的疑问包括：应使用 `inline` 还是 `attachment` 参数？如何指定下载文件的默认文件名？是否需要配合 `Content-Type` 使用？如何处理中文文件名编码问题？掌握这些要点有助于确保不同浏览器和环境下文件下载行为的一致性。

Answer 1

一、理解 Content-Disposition 的作用与基本用法

Content-Disposition 是 HTTP 响应头中的一个字段，用于指示浏览器如何处理响应体中的内容。它主要用于控制文件是应该被“预览”还是“下载”。

常见的取值有两个：

• inline：浏览器尝试在窗口中直接显示内容（如 PDF 文件在浏览器中打开）。
• attachment：浏览器提示用户保存文件，即强制下载。

例如，强制下载文件的响应头如下：

Content-Disposition: attachment

二、指定下载文件的默认文件名

在使用 attachment 时，通常需要指定下载文件的默认文件名，这样用户在保存时无需手动输入文件名。

语法如下：

Content-Disposition: attachment; filename="example.txt"

浏览器会将文件保存为 example.txt。

三、Content-Disposition 与 Content-Type 的关系

虽然 Content-Disposition 控制文件是预览还是下载，但 Content-Type 也会影响浏览器行为。

例如，若 Content-Type 是 text/plain，即使设置了 Content-Disposition: attachment，某些浏览器仍可能尝试显示内容。

因此，建议配合使用合适的 Content-Type，如：

Content-Type: application/octet-stream

这将确保浏览器不会尝试渲染内容，而是直接触发下载。

四、处理中文文件名的编码问题

在指定文件名时，如果文件名包含非 ASCII 字符（如中文），需要进行编码处理以确保兼容性。

标准做法是使用 RFC 5987 中定义的编码格式：

Content-Disposition: attachment; filename="example.txt"; filename*=UTF-8''%E4%B8%AD%E6%96%87.txt

其中：

• filename 是 ASCII 文件名（可选）。
• filename*=UTF-8''编码后的文件名 是 URL 编码后的 Unicode 文件名。

例如，中文文件名“报告.pdf”应编码为：

filename="report.pdf"; filename*=UTF-8''%E6%8A%A5%E5%91%8A.pdf

五、不同浏览器的兼容性与测试建议

尽管现代浏览器普遍支持 RFC 5987 编码，但某些旧版本浏览器（如 IE8 及以下）可能不支持。

为确保兼容性，建议采取以下策略：

1. 始终提供 ASCII 版本的文件名作为备选。
2. 使用 UTF-8 编码的 filename* 字段。
3. 在服务器端动态生成编码后的文件名。

示例代码（Node.js）：

const encodeURIComponentRFC5987 = (filename) => {
  return encodeURIComponent(filename).replace(/\\+/g, '%2B');
};

res.setHeader('Content-Disposition', 
  `attachment; filename="report.pdf"; filename*=UTF-8''${encodeURIComponentRFC5987('报告.pdf')}`);
  

六、流程图：文件下载响应头设置流程

以下是设置文件下载响应头的典型流程：

graph TD
      A[确定文件类型] --> B{是否强制下载?}
      B -->|是| C[设置 Content-Disposition: attachment]
      B -->|否| D[设置 Content-Disposition: inline]
      C --> E[设置 Content-Type: application/octet-stream]
      D --> F[设置合适的 Content-Type]
      E --> G{是否包含非ASCII文件名?}
      G -->|是| H[使用 filename* 编码]
      G -->|否| I[使用 filename]