前端下载文件怎么保留后端返回的文件名

如果前端用 fetch 下载文件，却总是得到一串对象 ID、download 或后端路径名，通常不是 Blob 丢了文件名，而是保存动作没有读取响应头。让后端返回 Content-Disposition: attachment，前端从其中解析 filename* 或 filename，再把结果交给 a.download，就能保留业务文件名。

推荐的链路是：读取响应头得到文件名 → 调用 response.blob() → 创建 Blob URL → 设置下载名并触发点击 → 在下载动作完成后释放 URL。跨域请求还必须显式暴露 Content-Disposition。

先确认文件名到底来自哪里

后端响应至少应该表达下载意图和建议名称：

Content-Type: application/pdf
Content-Disposition: attachment; filename="report.pdf"; filename*=UTF-8''%E6%B5%8B%E8%AF%95报告.pdf

filename* 使用 RFC 5987 的编码形式，适合中文和其他非 ASCII 文件名；如果两个字段都存在，能理解它的客户端通常优先使用 filename*。filename 可以保留一个 ASCII 回退名，例如 report.pdf。不要从 URL 最后一段猜名字，因为那一段可能只是对象存储的随机键。

前端读不到响应头时先查跨域

同源请求可以直接读取 response.headers.get("Content-Disposition")。如果接口和页面跨域，浏览器默认只把 CORS 安全响应头交给脚本，Content-Disposition 不在其中，后端要增加：

Access-Control-Expose-Headers: Content-Disposition

这不是把请求头加到 Access-Control-Allow-Headers，而是让脚本能够看到响应头。带 Cookie 的跨域请求也不要盲目使用 *，应明确列出该字段，并同时配置匹配的凭据策略。

可以先用浏览器开发者工具确认网络响应中确实有这个字段，再在控制台打印：

const response = await fetch('/api/export');
// 先判断 HTTP 状态，避免把错误 JSON 当成文件保存。
if (!response.ok) throw new Error(`下载失败：${response.status}`);
// 同源或已被 CORS 暴露时，这里才能读到后端建议的文件名。
const disposition = response.headers.get('Content-Disposition');
console.log(disposition);

优先解析 filename*，再回退到 filename

文件名解析要处理引号、空格和百分号编码。下面的函数只负责提取名称，不把整个响应头当作文件名；解析失败时返回一个带扩展名的安全默认值。

function getDownloadName(disposition, fallback = 'download.bin') {
  if (!disposition) return fallback;

  // filename* 的值通常是 UTF-8'' 加百分号编码，优先使用它。
  const star = disposition.match(/filename\*\s*=\s*UTF-8''([^;]+)/i);
  if (star) {
    try {
      return decodeURIComponent(star[1].trim().replace(/^"|"$/g, '')) || fallback;
    } catch {
      // 编码损坏时继续尝试 ASCII 回退名。
    }
  }

  // filename 只作为兼容回退，并去掉可能带来的路径片段。
  const plain = disposition.match(/filename\s*=\s*(?:"([^"]+)"|([^;]+))/i);
  const name = (plain?.[1] || plain?.[2] || '').trim();
  return name.split(/[\\/]/).pop() || fallback;
}

这里的默认名不是为了掩盖错误：如果业务要求必须有名称，应在返回默认值时记录日志或提示用户，而不是把未知响应静默保存成 PDF、Excel 等具体类型。

Blob URL 用完要释放

拿到文件名后，完整下载动作可以收敛成一个函数：

async function downloadFile(url) {
  const response = await fetch(url, { credentials: 'include' });
  // 网络请求成功不等于业务成功，先拦截 4xx/5xx 响应。
  if (!response.ok) throw new Error(`HTTP ${response.status}`);

  const name = getDownloadName(response.headers.get('Content-Disposition'));
  const blob = await response.blob();
  // 临时 URL 只服务于这个锚点，不把 Blob 内容复制进页面字符串。
  const objectUrl = URL.createObjectURL(blob);
  const link = document.createElement('a');
  link.href = objectUrl;
  link.download = name;
  link.click();
  // 点击已触发保存后释放引用，避免重复下载积累 Blob URL。
  setTimeout(() => URL.revokeObjectURL(objectUrl), 0);
}

URL.createObjectURL() 会为 Blob 建立临时地址，URL.revokeObjectURL() 用来释放它。不要在调用 click() 前立即释放，否则部分浏览器还没来得及读取资源；放到下一轮任务中更稳妥。若项目需要等待用户确认后再下载，可以把 objectUrl 的生命周期绑定到弹窗关闭事件，但必须保留清理分支。

按四层证据反向确认

遇到“文件名还是不对”，按下面顺序定位，通常几分钟就能分清是服务端、CORS 还是前端解析问题：

最后再检查接口是否返回了登录页、JSON 错误或重定向后的 HTML。只要状态码、响应头可见性、Blob 类型和临时 URL 都符合预期，浏览器保存对话框中的名称就会来自 link.download，而不是对象存储 URL。

几个容易混淆的边界

• 直接点击同源的文件链接时，浏览器也可能根据 Content-Disposition 处理名称；只有需要先鉴权、改名或处理 Blob 时，才适合用 fetch 方案。
• Content-Disposition 是响应头，不是前端自定义请求头；把它写进 fetch 的 headers 不会改变服务器返回名。
• download 更适合作为客户端建议名，服务端仍应校验资源权限、内容类型和实际文件来源。

发布前的下载检查清单

接口返回 Content-Disposition，跨域时暴露它；前端先检查 response.ok，再解析 filename* 和 filename；用 response.blob() 创建 Blob URL，设置 download 后触发点击，最后调用 URL.revokeObjectURL()。这条链路同时解决文件名、中文编码、跨域可见性和临时资源清理四个问题。

相关问题

为什么直接给 a 标签设置 download 仍然是服务器文件名？ 跨域资源、响应头策略或浏览器安全限制可能让该属性不能完全覆盖服务端行为；需要先确认资源是否同源以及响应是否被当作附件处理。

filename* 一定能显示中文吗？ 它提供了更明确的编码方式，但仍建议同时保留 ASCII 的 filename 回退名，并在浏览器实际环境中测试。

Blob URL 不释放会怎样？ 页面反复下载时，临时对象可能持续占用内存；在下载动作发起后释放通常是更稳妥的默认做法。