跨域资源无法直接下载？JavaScript配合CORS或后端转发的解决方案

一、现象与根源：为什么 <a download> 会对跨域资源失效

HTML5 为 <a> 标签引入了 download 属性，允许开发者在用户点击链接时直接将目标资源保存为本地文件，并可自定义下载文件名。但在实际业务中，当目标文件的地址位于外部域名、不同二级域名、不同端口或跨协议（HTTP 与 HTTPS）时，这一属性通常会失去效果。

根据 W3C HTML 规范定义，download 属性仅在链接属于同源 URL（Same-Origin）或使用了 blob:、data: 协议时生效。当浏览器检测到 href 指向的资源与当前页面不同源时，出于用户安全与防止跨站追踪、越权下载等沙箱隔离原则，浏览器会直接忽略 download 属性，将该点击行为降级为常规的超链接跳转。

一旦被降级为常规导航，浏览器的处理行为完全取决于目标资源的 MIME 类型及自身的预览能力：

• 具备原生渲染能力的资源（如 JPG/PNG/WebP 图片、PDF 文档、MP4 视频、TXT 文本）：浏览器直接在当前页面或新窗口打开预览。
• 无法直接渲染的二进制资源（如 ZIP、EXE、APK）：即便被降级为常规导航，浏览器仍会触发默认下载，但无法通过 download 属性强行指定保存的文件名。

图 1：浏览器对 <a download> 的同源检查与行为分流机制

二、方案一：前端 Fetch + Blob 方案（需服务端支持 CORS）

当资源托管在具备配置权限的第三方存储服务（如阿里云 OSS、腾讯云 COS、AWS S3 或已开放 CORS 的 API 接口）时，可以利用前端将外部资源转为同源的 blob: 协议链接，从而恢复 download 属性的下载能力。

1. 运作原理

该方案的核心思想是利用异步通信（Fetch 或 XMLHttpRequest）绕过 <a> 标签的直接跨域跳转：

1. 使用 fetch(url) 将跨域资源以二进制流形式读入内存。
2. 将读取到的数据封装为 Blob（Binary Large Object）对象。
3. 调用 URL.createObjectURL(blob) 生成一个以 blob: 开头的临时 URL。该 URL 的源（Origin）与当前页面完全一致，属于同源范围。
4. 动态创建不可见的 <a> 标签，将 href 设置为该 Blob URL，并挂载 download 属性指定文件名。
5. 触发点击事件实现直接下载，下载完成后调用 URL.revokeObjectURL() 释放浏览器内存。

图 2：基于 Fetch 与 Blob 的跨域资源下载各环节拆解

2. 前端代码实现示例

以下是经过生产环境封装的通用下载函数，包含网络异常捕获与资源即时回收机制：

/**
 * 通过 Fetch + Blob 方案实现跨域文件下载
 * @param {string} fileUrl - 目标跨域文件绝对地址
 * @param {string} customFileName - 期望保存的文件名（如 report.pdf）
 */
async function downloadByBlob(fileUrl, customFileName) {
  try {
    // 1. 发起跨域 GET 请求
    const response = await fetch(fileUrl, {
      method: 'GET',
      mode: 'cors'
    });

    if (!response.ok) {
      throw new Error(`网络响应错误，状态码: ${response.status}`);
    }

    // 2. 将数据流读取为 Blob 对象
    const blobData = await response.blob();

    // 3. 生成与当前页面同源的 blob: 协议对象 URL
    const objectUrl = window.URL.createObjectURL(blobData);

    // 4. 动态创建隐藏的 a 标签并挂载属性
    const tempLink = document.createElement('a');
    tempLink.style.display = 'none';
    tempLink.href = objectUrl;
    tempLink.setAttribute('download', customFileName || 'downloaded_file');

    document.body.appendChild(tempLink);
    tempLink.click();

    // 5. 移除 DOM 节点并释放内存地址
    document.body.removeChild(tempLink);
    // 延迟 1 秒释放，确保移动端或部分浏览器下载进程已成功接管该引用
    setTimeout(() => {
      window.URL.revokeObjectURL(objectUrl);
    }, 1000);
  } catch (error) {
    console.error('下载任务执行失败:', error);
    alert('文件下载失败，请检查网络或资源跨域策略配置。');
  }
}

三、方案二：后端代理转发与流式下载（彻底解决跨域与内存瓶颈）

当资源托管在不可控的第三方域名（无法为其添加 CORS 头），或者需要下载体积数以百兆计的大型文件时，前端方案将无法继续工作。此时最稳妥、最标准的企业级解法是后端流式代理转发。

1. 运作原理

在同源后端服务上增加一个下载转发接口。前端不再直接请求外部第三方地址，而是请求同源后端接口。

由于跨域限制仅存在于浏览器沙箱环境，服务器与服务器之间的网络通信不受同源策略约束。后端服务向目标资源地址发起请求，拉取原始文件流，并使用 管道流（Stream Pipe） 边拉取边回传给前端，同时在 HTTP 响应头中注入特定的控制字段：

• Content-Disposition: attachment; filename="filename.ext"：强制告知浏览器必须以附件形式下载，禁止任何内联预览。
• Content-Type: application/octet-stream：指示响应为通用二进制流。

图 3：后端流式转发与响应头注入的架构流程

2. 后端核心实现（以 Node.js 为例）

在 Node.js 中，通过 axios 或原生 https 获取 responseType: 'stream'，然后利用 .pipe(res) 将流直接接入输出通道：

const express = require('express');
const axios = require('axios');
const app = express();

app.get('/api/proxy-download', async (req, res) => {
  const { fileUrl, fileName } = req.query;

  if (!fileUrl) {
    return res.status(400).send('缺少必要参数 fileUrl');
  }

  try {
    // 1. 服务端发起流式请求，避免在内存中缓存完整大文件
    const remoteResponse = await axios({
      method: 'GET',
      url: fileUrl,
      responseType: 'stream'
    });

    // 2. 针对中文及特殊字符文件名进行标准 RFC 5987 编码转换，杜绝乱码
    const safeAsciiName = encodeURIComponent(fileName || 'downloaded_file');
    const contentDisposition = `attachment; filename="${safeAsciiName}"; filename*=UTF-8''${safeAsciiName}`;

    // 3. 设置核心响应头
    res.setHeader('Content-Disposition', contentDisposition);
    res.setHeader('Content-Type', remoteResponse.headers['content-type'] || 'application/octet-stream');

    if (remoteResponse.headers['content-length']) {
      res.setHeader('Content-Length', remoteResponse.headers['content-length']);
    }

    // 4. 将远端数据流直接管道式注入当前客户端响应流
    remoteResponse.data.pipe(res);

    remoteResponse.data.on('error', (err) => {
      console.error('上游数据流读取中断:', err);
      if (!res.headersSent) {
        res.status(502).send('远端文件传输中断');
      }
    });
  } catch (err) {
    console.error('拉取目标文件失败:', err.message);
    res.status(500).send('服务端转发失败');
  }
});

app.listen(3000, () => console.log('下载代理服务已启动在 3000 端口'));

3. 前端对接方式

当后端完成代理接口并注入 Content-Disposition: attachment 后，前端的逻辑大幅简化，甚至可以直接使用原生的 window.location.href 或纯 <a> 标签：

// 前端触发方式一：直接使用 location 导航
function downloadViaProxy(remoteUrl, fileName) {
  const proxyApi = `/api/proxy-download?fileUrl=${encodeURIComponent(remoteUrl)}&fileName=${encodeURIComponent(fileName)}`;
  window.location.href = proxyApi;
}

// 前端触发方式二：利用普通 a 标签（由浏览器依据 attachment 标头接管）
// <a href="/api/proxy-download?fileUrl=...&fileName=...">下载文件</a>

四、两种解决方案的综合对比与选型决策

在实际项目架构中，并非所有场景都必须引入后端转发，也不是所有文件都适合在前端用 Blob 处理。两者在运维成本、服务器负载以及功能边界上存在明确差异：

图 4：两种方案的技术选型决策路径与权衡总结

五、生产实践中的常见问题与避坑指南

1. 中文或特殊字符文件名乱码

在配置 Content-Disposition 响应头时，直接写入 UTF-8 中文可能会导致部分浏览器解析出现乱码甚至截断。标准做法应遵循 RFC 5987 规范，同时提供 ASCII 回退名称与编码后的扩展字段：

Content-Disposition: attachment; filename="document.pdf"; filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%96%87%E6%A1%A3.pdf

2. 对象 URL 释放过早导致下载中断

在使用 window.URL.revokeObjectURL(url) 时，若紧随 link.click() 同步执行销毁操作，在部分低版本浏览器或移动端 WebView 中，由于底层网络/磁盘写入线程尚未完成与该临时地址的握手，可能导致下载直接失败或生成 0 字节文件。建议使用 setTimeout 延时 1 秒至 2 秒再进行资源释放。

3. 携带凭证与 Cookie 的安全传输

如果远端资源所在的服务器需要身份验证（如携带 Cookie），使用 Fetch 发起请求时需显式声明 credentials: 'include'。此时服务端返回的 Access-Control-Allow-Origin 不能为通配符 *，必须精确设置为请求方的来源 Origin，且需额外附带 Access-Control-Allow-Credentials: true。