前端下载文件全攻略：从a标签到Blob、鉴权与大文件断点续传

我当初面试一家公司的时候，面试官问我：“前端下载一个文件，你会怎么做？”我嘴里说着a标签加download属性，心里其实已经闪过七八个念头——这玩意儿真这么简单？下载这个动作，放在浏览器里，表面的“点击就下”背后藏着太多分支：文件是后端下发的流还是静态资源？要带token吗？文件名是中文会不会乱码？下载到一半断了怎么办？这些问题不搞清楚，实际做项目的时候就等着一个个踩坑吧。

这篇就把前端下载这件事掰开揉碎讲。从浏览器最底层的下载触发机制，到Blob二进制下载、文件名解析、大文件断点和鉴权下载，每个环节我都会给你可以直接抄走的方案和代码。内容面向从初级到中高级的前端开发者，尤其适合准备面试或者正在做文件模块的兄弟们。

1. 浏览器下载的本质：一条链接引发的血案

很多前端干了两年还在用window.location.href = url下载文件，偶尔能用，但断断续续出些怪问题，还找不着原因。要搞清楚前端下载，第一步就是理解浏览器的下载行为是怎么被触发的。

1.1 下载的本质不是“代码在下载”，而是“浏览器在导航”

浏览器天生就有一项能力：识别服务器返回的响应头。只要HTTP响应头里的Content-Disposition带了attachment，浏览器收到内容后就不会去渲染页面，而是把内容当成一个文件丢进下载管理器。这个行为跟你怎么发请求没关系——你直接地址栏输入URL也好，a标签href指向也好，window.open也好，只要响应头是attachment，它就下载。

这就是最最初的下载原理：下载并不是前端“主动拉”一个文件，而是前端引导浏览器去访问一个URL，浏览器根据服务器的响应头决定是渲染还是下载。

所以一个最直接的前端下载方法就是：

html复制<a href="https://example.com/files/report.pdf" download>下载报告</a>

你可能会问，这里我加了download属性，是不是就靠它实现的？其实并不是。download属性只是告诉浏览器“这个链接我希望是下载而不是跳转”，但它有两个前提：第一，必须是同源URL，因为download属性对跨域资源是无效的（Chrome会忽略它，直接打开预览）；第二，服务器响应头也得配合，如果服务器没有返回attachment，即便加了download有的场景也会变成预览。

1.2 三种方式的本质区别

前端触发下载的方式汇总起来其实就三大类，很多文章讲得云里雾里，我这里列个表，一下就清楚了：

这张表是理解前端下载整个体系的骨架。第一二种本质就是让浏览器做一次导航请求，第三种是先用代码拿到文件数据，再在前端拼出一个文件让浏览器下载。别看写法差几个字母，背后完全是两种思路。

1.3 为什么有时候点击下载没反应

这个问题高频出现在工作中。结合上面的原理，基本可以按这几条去排查：

浏览器拦截了window.open——因为window.open如果不在用户点击的同步事件栈里触发，会被弹窗拦截。有人代码里先await了一个接口，再调window.open，就被拦了。解决方法是用a标签临时创建或者先开空窗再赋值location。

服务器返回的是JSON错误信息而不是文件流——比如token过期了，后端返回401加一段JSON。前端还在傻傻接收，接收完发现不是文件，自然下不了。

后端响应头没设置Content-Type导致浏览器直接去渲染文件内容了——比如返回一个JSON格式的数据却标了text/html，浏览器把内容当页面展示。这类问题看Network面板里响应体内容比看任何报错都直观。

2. 二进制流下载：为什么你下载的文件总是一堆乱码

前端的进阶下载方式——先请求拿到数据流，然后在浏览器端“造”一个文件出来，就是常说的Blob下载。

2.1 后端下发文件流的两种形态

后端接口返回的文件数据，因为网关或历史原因，常见有两种形态。

第一种，接口直接返回二进制流。你fetch拿到的是一个Response对象，要调res.blob()拿到Blob实体。

第二种，接口被包了一层JSON结构，文件内容被转成了Base64编码字符串或二进制数组。出现这种情况，多半是后端没用流式输出，而是把文件读进内存再编码塞进JSON里。前端拿到这种数据，需要先转成Uint8Array或直接处理Base64，再new Blob。

如果后端返回的是这种带外层结构的JSON，前端就得二次处理。以常见的Base64字符串为例：

javascript复制// 后端JSON里长这样：{ code: 0, data: "JVBERi0xLjQK..." }
async function downloadJsonBase64File(jsonUrl, filename) {
  const res = await fetch(jsonUrl);
  const json = await res.json();
  if (json.code !== 0) throw new Error('文件获取失败');

  // 将Base64解码为二进制字符串
  const byteCharacters = atob(json.data);
  const byteNumbers = new Array(byteCharacters.length);
  for (let i = 0; i < byteCharacters.length; i++) {
    byteNumbers[i] = byteCharacters.charCodeAt(i);
  }
  const byteArray = new Uint8Array(byteNumbers);
  const blob = new Blob([byteArray], { type: 'application/pdf' });

  triggerDownload(blob, filename);
}

这种处理方式你得跟后端确认清楚编码方式，Base64还是Base64URL，有没有带data:前缀，处理逻辑都不一样。接口文档里多确认一句，能省一晚上的排查时间。

2.2 Blob的type设置和MIME的坑

Blob的MIME类型不是随便填的，填错了最典型的症状是：下载下来的文件后缀名正确，但打开就报格式错误或者乱码。比如一份Excel文件，如果type填了application/pdf，就算你给文件命名成.xlsx，Excel打开时按内容判断格式也会报错。

常见文件对应MIME：

MIME类型最保险的做法是看后端接口的Content-Type响应头，后端返回什么你就用什么。手动映射表总有覆盖不到的文件类型，还容易写错。

2.3 触发浏览器下载的标准动作

拿到Blob之后，需要一个统一的函数把Blob变成“浏览器认得的下载”。市面上常见的downloadjs、file-saver这些库，核心代码其实都一样，底层逻辑就是：

javascript复制function triggerDownload(blob, filename) {
  // 老版本IE走msSaveBlob
  if (window.navigator && window.navigator.msSaveOrOpenBlob) {
    window.navigator.msSaveOrOpenBlob(blob, filename);
    return;
  }

  // 其他浏览器：创建Blob URL挂到a标签上
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename || 'download';
  document.body.appendChild(a); // 必须挂到DOM上才能触发Firefox下载
  a.click();

  // 清理工作
  document.body.removeChild(a);
  URL.revokeObjectURL(url);
}

两个新手容易漏的细节：

a.click()触发后要立刻URL.revokeObjectURL吗？这里有个浏览器内部的时间差问题，Chrome的处理是触发click之后，下载任务已经拿到blob的引用，所以立刻revoke没事。但Firefox在某些版本里如果太快revoke，下载会失败——安全起见，稳妥的做法是把revoke放到setTimeout里延迟几十毫秒，或者干脆放在a.click()之后的下一个宏任务里。

a标签必须加入DOM吗？Chrome里不加也能触发，但Firefox对未挂载到DOM的a标签click事件处理有bug，会导致不下载。所以统一都appendChild一下，再remove掉，一行代码换来全兼容，很划算。

2.4 Blob URL的内存泄漏问题

URL.createObjectURL创建的字符串，即使你删了a标签，也不会自动释放对应的内存。它像一个指向浏览器内存中Blob对象的句柄，不调revokeObjectURL，那个Blob就会一直在内存里躺到页面卸载。

写个演示用的下载逻辑没感觉，但如果在管理后台反复下载文件，一上午能产生几百MB的泄漏。我帮人排查过一个导出功能越用越卡的问题，最后定位就是每点一次下载，生成一个几十MB的Blob URL没回收。加上revoke之后，内存曲线立刻下来了。

所以在真实项目里，我建议把triggerDownload封装之后，还得有一个配套约定：所有下载入口走的都是这个封装函数，才能保证revoke逻辑不遗漏。手写的临时a标签越多，内存泄漏的坑越深。

3. 文件名：后端说什么你听什么吗

下载的文件叫什么名字，这件事看似简单，实则是一个前后端容易互相甩锅的重灾区。

3.1 三种文件名来源的优先级

当文件名有多个来源时，遵循一个原则：优先用后端在Content-Disposition里指定好的文件名，只有当后端没给或给的特殊字符处理不了时，才退到前端自己兜底命名。

后端返回文件名的方式靠响应头：

http复制Content-Disposition: attachment; filename="report.pdf"
Content-Disposition: attachment; filename*=UTF-8''%E5%B9%B4%E6%8A%A5.pdf

关键是：当filename和filename*同时存在时，按照RFC 5987规范，浏览器应该优先取filename*，因为后者才是支持URL编码字符集的标准写法。但部分老版本浏览器并不遵守，所以前端做兜底解析时会面临一个小分叉逻辑。

3.2 为什么fetch拿不到Content-Disposition头

很多前端写了这样的代码：下载前先fetch请求一下接口，想从响应头里取filename，发现res.headers.get('Content-Disposition')始终是null。这跟后端没设置没关系，而是浏览器的跨域安全策略：默认情况下，前端JS只能读取响应头里的CORS safelisted头（比如Content-Type），Content-Disposition不在其中。

要让前端能读到，后端必须显式加一个响应头：

http复制Access-Control-Expose-Headers: Content-Disposition

坑的是，很多后端并不了解这个机制，所以你需要把这段说明同步给后端同事。同时，前端要做的准备是：就算拿不到，也要有自己的兜底文件名处理方案。

3.3 中文文件名乱码的完整解码

即使Content-Disposition能拿到，里面内容也可能是编码过的。遇到过比较完整的情况是后端返回这样的头：

code复制Content-Disposition: attachment; filename="=?UTF-8?B?5bm75Y2X55SfLnBkZg==?="; filename*=UTF-8''%E5%B9%B4%E6%8A%A5.pdf

我们需要处理filename*这段。处理逻辑伪代码：

javascript复制function getFilenameFromDisposition(disposition) {
  if (!disposition) return '';

  // 优先匹配 filename*=UTF-8''xxxx 形式
  const starMatch = disposition.match(/filename\*=(?:UTF-8'')?([^;]+)/i);
  if (starMatch && starMatch[1]) {
    try {
      return decodeURIComponent(starMatch[1].replace(/['"]/g, ''));
    } catch (e) {
      // 解码失败就原样返回，总比空白强
      return starMatch[1];
    }
  }

  // fallback 到普通filename，多半是Latin1编码
  const plainMatch = disposition.match(/filename="?([^";]+)"?/i);
  return plainMatch ? plainMatch[1] : '';
}

这里要慎重处理的是解码失败时的降级路径，千万不要因为解码就console报错中断下载流程——文件名加不出来最多就是名字难看，因为一个小错误把下载链路打断才是真正的线上事故。

4. 大文件下载：进度条和断点续传，不能只靠浏览器默认UI

前面说的下载方式，对于几十MB的文件够用。但如果你下载的是几百MB的数据包、日志文件或者视频，用户体验就是一个很现实的问题。浏览器工具栏左下角那个下载管理器的进度展示，如果产品经理觉得不够友好怎么办？这时候就需要前端自己控进度条。

4.1 用fetch的ReadableStream读取下载进度

fetch响应体是一个ReadableStream，你可以通过它的reader逐块读取数据，自己统计已经读取的字节量。

javascript复制async function downloadWithProgress(url, filename, onProgress) {
  const res = await fetch(url, {
    headers: { 'Authorization': `Bearer ${getToken()}` }
  });

  if (!res.ok) throw new Error(`下载失败：HTTP ${res.status}`);
  const totalBytes = Number(res.headers.get('Content-Length')) || 0;

  const reader = res.body.getReader();
  const chunks = [];
  let receivedBytes = 0;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
    receivedBytes += value.byteLength;

    if (totalBytes && onProgress) {
      onProgress(receivedBytes, totalBytes);
    }
  }

  // 汇总所有片段，得到完整Blob
  const blob = new Blob(chunks);
  triggerDownload(blob, filename);
}

// 使用
downloadWithProgress('/api/export/bigfile', '大文件.zip', (received, total) => {
  const percent = Math.floor(received / total * 100);
  document.getElementById('progressBar').style.width = percent + '%';
  document.getElementById('percent').textContent = percent + '%';
});

这里要注意：如果文件本身是gzip传输的，Content-Length和实际接收到的字节量可能对不上，进度条可能最后突然从98%跳到100%。这种情况建议后端传输时关掉压缩，或者干脆不支持压缩大文件——因为压缩大文件的服务端CPU开销也是问题。

4.2 用Blob合并不是简单的数组concat

上面代码里我把每一段数据都push进了chunks数组，最后用new Blob(chunks)合成。有人觉得应该把它们concat成一个大的Uint8Array，再传进Blob。实测下来，new Blob(arrayOfChunks)的底层性能更好，因为它不需要所有数据同时存在连续内存里。文件越大，Blob数组拼接的优势越明显。所以记住：Blob构造器本身就接收Uint8Array数组，不需要你手动concat。

4.3 断点续传的两种思路

下载大文件还有个灵魂问题：如果下载到一半网络断了，是不是得重新开始？断点续传有两种实现思路。

第一种是服务端支持 Range 请求。前端记住已接收的字节数offset，断线后重新发请求，带上Range: bytes=offset-的请求头，服务器从offset位置继续发数据。这是文件下载的标准续传方案，难点是浏览器端的空间管理——你把已下载的数据存在内存里，页面一刷新就丢了，要做持久化就得配合indexedDB存Blob片段，复杂度一下子升上来。

第二种思路是前端不直接续传，而是给用户“失败重试”的兜底方案。适合几十到100MB这种量级的文件，重试一次成本可接受。代码里加个下载函数自身调用的retry机制就够了。

面试或者做技术选型时，最理性的判断是：文件超过几百MB才值得做真正的可持久化断点续传，否则直接优化重试策略更省事。别一上来就满嘴IndexedDB续传，落地成本要算进去。

5. 鉴权下载：a标签解决不了的事

这是下载需求里最绕不开的一关。很多后台系统的文件不允许匿名下载，必须携带登录凭证，这就把前面最简单的第一类方法（a标签直接下载）给堵死了。

5.1 为什么带token的下载不能用a标签

a标签啊，你没法给它自定义headers。有人会想着那我把token拼在URL后面行不行，比如/api/download?token=xxx。如果是GET接口，确实能行，但这会让token暴露在浏览器历史记录、服务器访问日志、Nginx转发日志里，属于典型的不安全设计。稍微正规一点的后端接口都不会接受这种传参方式。

所以带鉴权的下载，前端方案就一条路走得通：先fetch带headers请求拿到Blob，再在本地触发下载。前面分析过的CORS、filename获取、Type设置，每一条都要踩对，链路才算闭环。

5.2 一个完整的带token下载封装

把整个过程的代码完整组装一次：

javascript复制async function downloadAuthorizedFile(url, filename, token) {
  try {
    const res = await fetch(url, {
      headers: { 'Authorization': `Bearer ${token}` },
      // redirect: 'follow' 是默认行为，个别下载接口会先302到临时文件URL
    });

    if (!res.ok) {
      // 非2xx时后端多半返回JSON错误信息，尝试取出来提示给用户
      const errorText = await res.text().catch(() => '');
      throw new Error(`下载失败(${res.status}) ${errorText || ''}`);
    }

    const blob = await res.blob();
    const finalFileName = filename || guessFilename(res) || `download_${Date.now()}`;

    triggerDownload(blob, finalFileName);
  } catch (err) {
    // 统一错误提示，方便上层catch
    console.error('下载出错：', err);
    throw err;
  }
}

这里面有个很重要的后端协作点：如果接口实际返回的是临时文件URL的重定向，前端也要能处理。fetch默认是跟随重定向的，但如果你手动设置了redirect: 'manual'去做拦截，就要自己处理重定向后的response了。没有特殊需求的话，请保持默认或者显式设置redirect: 'follow'。

5.3 接口带下载又有业务数据返回怎么办

还有一种场景是下载接口本身不是纯文件，它还会附带回执数据，比如“下载成功，记录本次操作日志的id”。这个时候接口返回格式往往是JSON外加一个文件，后端常见做法是返回JSON里带文件的Base64或临时下载URL。这就回到第2.1节里的Base64处理逻辑了。建议项目里统一定一个“下载响应DTO”，不管文件大小，后端都返回统一的JSON格式，前端封装一套DownloadService专门消费这个格式，不同类型文件只用处理解析差异即可。

6. 多文件批量打包下载：一次请不了愿就压缩一次

后台系统经常有“批量下载”的需求，把勾选的多个文件打成一个包。这一步前端能做的是先在本地把所有文件抓下来，在浏览器端压缩成ZIP再下载。好处是不占用服务端资源，坏处是文件总量太大时，浏览器内存扛不住。所以这套方案只适合总大小在几十到一两百MB以内的场景。

6.1 用JSZip在浏览器端打包

JSZip是这个领域的成熟库，它支持把多个Blob加到一个ZIP包里再生成blob：

javascript复制import JSZip from 'jszip';

async function downloadMultipleFiles(fileList) {
  // fileList: [{ url | blob, filename }]
  const zip = new JSZip();

  for (const item of fileList) {
    const blob = typeof item.url === 'string'
      ? await fetch(item.url).then(r => r.blob())
      : item.blob;

    zip.file(item.filename, blob);
  }

  const zipBlob = await zip.generateAsync({
    type: 'blob',
    compression: 'DEFLATE',
    compressionOptions: { level: 6 }
  });

  triggerDownload(zipBlob, '批量下载.zip');
}

压缩级别官方建议6，这是速度和体积的甜点位。设9级压缩率并没好多少，但CPU占用成倍涨，文件大了页面会明显卡顿甚至崩溃。

6.2 大文件批量下载的内存处理

把200MB的文件用浏览器端打包，不是不可能，但是要看好你的目标用户设备和浏览器。Chrome对单个标签页内存有隐形天花板，一旦超过阈值，渲染进程会被直接杀。稳妥的兜底策略是：给下载文件总量设个上限，超过M就提示用户转用服务端打包接口。

这个M可以是100MB，可以根据实际业务平均文件大小调整。做批量下载的产品，大部分单文件不会特别大，关键总量要控制住。

7. 面试官视角：你在聊下载问题时，其实在考什么

既然这个主题高频出现在前端面试题里，我就直接以面试官的视角拆一下这道题背后想考察什么，这也正好帮你检验自己的知识体系有没有盲区。

面试官问“前端怎么实现下载”，不是真想听你默写一个a标签demo。他们在考察：

第一层，基础能力——你会不会最基本的静态文件下载。这一层a标签、download属性、同源限制能答出来，算是及格。

第二层，安全意识和跨域理解——当你听到“需要登录才能下载”，会怎么处理？能不能想到a标签不能带自定义header的硬伤，再过渡到fetch加Blob的方案。这是后端同学最爱配合的考察点。

第三层，工程经验——拿到的文件流可能是JSON包装的，文件名的Content-Disposition可能被跨域策略挡住，下载的过程中内存会不会泄漏，下载一半断网了用户该怎么被安抚。这些没有真实项目经验、只刷过八股文的人是答不出来的。

第四层，方案取舍——到底用浏览器下载还是前端拿流自制下载，各自边界在哪？不同场景选择不同方案，并能说出理由，这才是资深前端的水准。

所以如果你正在准备面试，把这篇文章里的内容吃透，把第一到第四层都覆盖到，面试官往下追问什么你都有内容接住。

最后再分享一个我实际做项目常用的习惯：前端下载功能有很多边界Case容易漏，我一般会在开发一个下载模块时单独建一个自测清单，里面包含无权限下载、文件不存在、后端返回null、文件名含中文和空格、零字节文件、超大文件、断网取消——每个Case都对应一个现象和预期。下载这个功能，卡顿和报错总是最影响用户情绪的，预先把这些坑填平了，线上就少一多半事故。