企业官网建设流程全解析

上周帮一位做后台系统的朋友看问题：他页面上有个「导出报表」的按钮，代码写得很朴素，<a href="/static/report.xlsx" download>下载报表</a>，自己电脑上点了一百遍都正常，交付给客户之后，客户点了一下，浏览器直接在标签页里刷出一屏乱码，文件名还变成了一串没有扩展名的东西。他第一反应是"后端文件坏了"，把文件拖到本地打开一看，好好的。问题根本不在文件，在于他对download这个属性的能力边界产生了误解。

a标签下载静态资源，看起来是前端最不值一提的一个需求——写个 href，加个 download，收工。但真正把它放到生产环境里，同源策略、MIME 类型、响应头、打包路径、CDN 前缀、中文文件名、移动端内嵌浏览器，任何一个环节没对上，都会让这个"最简单"的功能变成一个查半天查不出原因的疑难杂症。这篇内容我打算把这条链路上的每一个判定环节拆开讲清楚：浏览器到底是怎么决定"打开"还是"下载"的，静态文件放在哪个目录才不会上线就 404，跨域的时候为什么要绕一圈 blob，以及我这些年在这个小功能上踩过的具体坑。适合正在做后台管理系统、需要提供报表导出能力的前端同学，也适合刚入行、想知道"为什么我写的 download 不生效"的新人对照排查。

1. download 属性管不了的三件事：同源、MIME、响应头

很多人对download的理解是"加了这个属性就会下载"，这个理解只对了一半，而且在跨域场景下这一半也不成立。要搞清楚它，得先知道浏览器点击一个链接之后，内部到底走了哪几步判断。

1.1 浏览器决定"打开还是下载"的真实顺序

点下一个<a>标签，浏览器拿到响应之后并不是先看你的download属性，它有一套固定的优先级。第一优先级是响应头里的Content-Disposition，如果服务端返回了Content-Disposition: attachment; filename="report.xlsx"，那不管前端写了什么，浏览器一律走下载流程。第二优先级才是download属性，但它有一个硬性前提：链接地址必须和当前页面同源，或者协议是blob:、data:这类浏览器内部生成的地址。第三优先级是Content-Type，如果前两个都没触发下载，浏览器就按 MIME 类型自己判断——能渲染的就地渲染（PDF、图片、纯文本、HTML 都会被直接打开），不能渲染的才下载。

这个顺序解释了一个特别常见的困惑：为什么我明明写了download，PDF 还是在浏览器里预览了？因为那个 PDF 的地址跨域了，download被浏览器直接忽略，然后Content-Type: application/pdf告诉浏览器"我能渲染"，于是就渲染了。你的属性不是写错了，是被静默丢弃了，控制台连个警告都不会给。

我在实际项目里遇到过更隐蔽的一种：资源放在对象存储上，地址是另一个域名，前端写了download="报表.xlsx"。本地开发时因为配了代理，请求看起来是同源的，一切正常；上线之后直连存储域名，download 立刻失效，PDF 变成预览，Excel 变成乱码页。这种"开发环境正常、线上异常"的差异，八成都是同源判定在背后捣鬼。

1.2 同源到底卡在哪一步

同源指的是协议、域名、端口三者完全一致。http://a.com和https://a.com不同源，https://a.com和https://www.a.com不同源，https://a.com:8080和https://a.com也不同源。只要有一项对不上，download属性就失效。

这里有个细节值得说清楚：download失效不等于下载失败，它只是"不再强制下载"，最终行为交回给浏览器按 MIME 判断。所以你会看到三种截然不同的现象——PDF 在新标签页打开、图片直接铺满屏幕、xlsx 显示成一堆乱码或者干脆弹出一个空白页。看起来像三个不同的 bug，实际上是同一个原因。

顺带提一句，就算同源，download也有个小限制：它只对"用户点击触发"的导航有效。如果你是用脚本动态创建<a>然后click()，这在绝大多数浏览器里是允许的，但必须在用户交互的调用栈里（比如按钮的 click 回调里），否则某些浏览器会拦截。这一点在后面的 blob 方案里会反复用到。

1.3 MIME 类型：决定命运的第三个变量

即使同源、即使写了download，服务端的Content-Type依然值得盯一眼，因为它是你排查问题时最快能看到的信号。下面这张表是我这些年整理下来的对应关系，直接对照着看就行：

看这张表就能明白，Excel 和 Word 之所以"天生"容易下载成功，是因为浏览器压根没法渲染它们，只能走下载。而 PDF 和 CSV 才是重灾区——它们能被渲染，所以只要download失效一点点，就会变成预览。

反过来也有个坑：有些服务端为了"保险"，把所有文件都返回application/octet-stream。这样确实一定会下载，但代价是浏览器丢失了文件类型信息，用户下载下来的是一个没有扩展名或者扩展名错误的文件，双击打不开。这时候download="报表.xlsx"里的扩展名就成了唯一的救命稻草，这也是为什么我后来养成习惯，download的值一定写全扩展名，不省略。

提示：如果前端完全无法控制服务端响应头（比如资源放在第三方存储上），那么download属性就是你唯一能施加影响的地方，而它只在同源时生效。这就是后面必须引入 blob 方案的根本原因。

2. 静态资源放在哪个目录，决定上线后能不能找到它

download 属性写对了、同源也没问题，还有一个更基础的问题经常被忽略：这个文件到底在不在你请求的那个地址上。前端工程里静态资源的存放位置是有讲究的，放错地方，本地跑得好好的，打包上线就是 404。

2.1 public 目录与 assets 目录的本质区别

现在主流的构建工具（无论是 Vite 还是 Webpack 体系）都会区分两类静态资源，理解它们的处理方式差异比记住目录名重要得多。

第一类是"原样拷贝"的目录，通常叫public。放在这里的文件在构建时会被原封不动地复制到产物根目录，不做哈希、不做压缩、不做引用分析。这意味着你可以用一个稳定的绝对路径访问它，比如public/docs/template.xlsx对应线上的/docs/template.xlsx。适合放那些地址需要固定、可能被外部系统引用的文件，比如下载模板、说明文档。

第二类是"经过构建处理"的目录，通常叫assets或src/assets。这里的文件会被加上内容哈希（比如template.a1b2c3d4.xlsx），目的是做长期缓存。你没法在代码里硬编码它的路径，必须通过import或者构建工具提供的 URL 解析方式拿到最终地址。好处是文件变了地址就变，用户不会拿到旧版本；坏处是地址不稳定，不能对外暴露。

我的选择习惯是这样：面向用户下载的固定文件（模板、说明书、示例数据）放 public，代码里引用的资源（图标、字体）放 assets。前者需要地址稳定，后者需要缓存友好，两者的诉求本来就是相反的。

2.2 base 前缀：那个让路径集体偏移的配置项

真正让人栽跟头的往往不是目录选错，而是部署路径。假设你的项目部署在https://example.com/admin/这个子路径下，而你在代码里写了<a href="/static/template.xlsx" download>，注意开头那个斜杠——它代表域名根目录，浏览器会去请求https://example.com/static/template.xlsx，而文件实际在https://example.com/admin/static/template.xlsx，结果就是 404。

这个问题的根源在于硬编码了以/开头的绝对路径。正确做法是让构建工具帮你拼前缀。以 Vite 为例，如果配置了base: '/admin/'，那么public目录下的文件应该这样引用：

// 不要这样写，斜杠开头会跳过 base 前缀 const url = '/static/template.xlsx'; // 这样写，构建时会自动拼上 base const url = import.meta.env.BASE_URL + 'static/template.xlsx'; // 结果：/admin/static/template.xlsx

如果用 Webpack 体系，对应的是process.env.PUBLIC_URL或者publicPath配置。原理是一样的：任何指向静态资源的路径，都不该由你手写死，而应该从构建配置里取。

还有一个更隐蔽的变种：资源上了 CDN，CDN 域名和页面域名不同源。这时候就算路径拼对了，跨域问题又回来了，download属性依然失效。所以"能不能找到文件"和"找到了能不能下载"是两个独立的问题，得分开排查。

2.3 用 import 引入资源换来的是什么

如果文件不大、且确实需要版本控制（比如某份随代码一起更新的数据字典），可以考虑用模块引入的方式：

import templateUrl from '@/assets/template.xlsx?url'; // 或者 const templateUrl = new URL('./template.xlsx', import.meta.url).href;

这种写法的好处是构建工具会帮你处理哈希、处理 base 前缀、处理 CDN 域名，你拿到的就是一个可直接用的完整 URL。缺点是文件会被打进产物，更新一次就得重新发版，而且文件名带哈希，下载下来的默认名会很难看，必须配合download属性改名。

我个人的取舍标准很简单：文件会随业务版本变化、体积小于 1MB、只需要内部使用，就走 import；文件是给用户下载的对外交付物、地址需要稳定、可能被外部引用，就放 public 并用 base 前缀拼路径。没有绝对的优劣，只有场景匹配。

3. 纯 a 标签方案的完整写法与四种失效现场

把环境和路径理清楚之后，才有资格谈代码怎么写。这一节给的是同源场景下的最优解，以及它在什么情况下会突然不灵。

3.1 最小可用代码与三个必须写全的细节

同源静态文件下载，代码可以非常短，但细节不能省：

<a href="/admin/static/template.xlsx" download="员工信息导入模板.xlsx" rel="noopener" > 下载模板 </a>

这里有三处值得展开。第一，download的值一定要写完整文件名包括扩展名，不要写download空值。空值的情况下浏览器会从 URL 最后一段推断文件名，如果 URL 带了查询参数或者经过后端转发，推断出来的名字往往是一串乱码。第二，如果链接可能被脚本点击，记得加rel="noopener"，虽然对下载场景影响不大，但作为习惯可以保留。第三，href 里的路径要按上一节说的方式处理 base 前缀，别写死根路径。

如果需要在点击时做一些埋点或者权限校验，可以改成按钮加脚本触发：

function downloadByAnchor(url, filename) { const a = document.createElement('a'); a.href = url; a.download = filename; a.style.display = 'none'; document.body.appendChild(a); a.click(); document.body.removeChild(a); }

注意最后一定要把节点移除掉。虽然不移除也能工作，但反复点击会往 DOM 里堆一堆隐藏节点，长期运行的页面（比如挂着不关的后台系统）会积少成多。

3.2 四种典型的失效现场

我在排查这类问题时，总结出四种最高频的失效场景，基本覆盖了九成以上的求助。

第一种，跨域导致 download 被忽略。前面讲过，症状是 PDF 变预览、图片直接铺屏。判断方法很简单，打开 Network 面板看这个请求的域名和页面域名是否一致，不一致就基本可以确诊。

第二种，服务端返回了Content-Disposition: inline。有些后端框架默认把inline写死在响应头里，前端写了 download 也没用，因为响应头优先级更高。这种情况前端完全无解，必须让后端改。判断方法是在 Network 面板点开该请求的 Response Headers，直接看有没有这一行。

第三种，href 指向的地址 404 或者返回了一个 HTML 错误页。这时候浏览器下载下来的是一份 HTML 内容，扩展名却是 xlsx，用户打开提示文件损坏。这类问题八成是路径拼错或者 base 前缀没处理。

第四种，链接被前端路由拦截了。有些项目配了全局的链接拦截或者路由守卫，所有<a>的点击都被接管，download属性根本走不到浏览器原生流程。判断方法是临时把 href 换成一个真实存在的静态文件地址，看能不能下载，能就说明是拦截逻辑的问题。

这四种场景的排查顺序建议是：先看 Network 状态码（排除第三、第四种），再看请求域名（排除第一种），最后看响应头（排除第二种）。按这个顺序走，一般五分钟内能定位。

3.3 什么时候该放弃纯 a 标签

纯 a 标签方案的优势是简单、零依赖、不占内存，浏览器原生处理，大文件也不会有压力。但它在三种情况下必须放弃：

一是资源跨域，download必然失效；二是需要携带鉴权头（比如 token 放在请求头里而不是 URL 上），a 标签发的是普通导航请求，带不了自定义头；三是需要在下载前后做 loading 状态、进度提示、失败重试这类交互。

这三种情况都得走 blob 方案。所以我的判断逻辑是：同源、无需鉴权头、无需交互反馈，就用 a 标签；三者缺一，就上 blob。别为了省事硬用 a 标签，最后绕回来的成本更高。

4. 跨域场景：从 fetch 到 blob 再到 a.click 的每一步

blob 下载是这类需求里绕不开的方案，网上代码一搜一大把，但大部分只给了代码没讲清楚每一步为什么这么写。我按执行顺序拆一遍。

4.1 完整链路与每一行的作用

async function downloadByBlob(url, filename) { // 第一步：把文件内容取到内存里 const response = await fetch(url, { method: 'GET', headers: { // 如果需要鉴权，在这里带上 Authorization: `Bearer ${getToken()}`, }, }); if (!response.ok) { throw new Error(`下载失败，状态码 ${response.status}`); } // 第二步：把响应体转成二进制大对象 const blob = await response.blob(); // 第三步：给这个内存里的对象生成一个临时地址 const objectUrl = URL.createObjectURL(blob); // 第四步：用一个同源的临时地址触发下载 const a = document.createElement('a'); a.href = objectUrl; a.download = filename; a.style.display = 'none'; document.body.appendChild(a); a.click(); document.body.removeChild(a); // 第五步：释放临时地址占用的内存 setTimeout(() => URL.revokeObjectURL(objectUrl), 1000); }

关键在第一和第四步。第一步用fetch发请求，属于 XHR 范畴，受 CORS 约束但不受"同源才能下载"的限制，只要服务端允许跨域就能拿到内容。第四步的objectUrl是以blob:开头的，浏览器认为它和当前页面同源，所以download属性重新生效了。整条链路的核心思路就是：把跨域的资源"搬"到本地内存，再用同源的方式下载它。

注意：URL.revokeObjectURL千万不要紧跟在click()后面同步调用。有些浏览器（尤其老版本 Safari 和 Firefox）在click()之后才开始真正读取 blob，如果地址已经被释放，下载会静默失败。延迟一段时间再释放是最稳妥的做法。

4.2 Content-Disposition 解析：让后端决定文件名

很多时候文件名不是前端定的，而是后端在响应头里返回的，比如导出报表这种场景，文件名里往往带着时间戳。这时候前端需要从响应头里把它读出来。

async function downloadWithServerFilename(url) { const response = await fetch(url); const disposition = response.headers.get('Content-Disposition'); let filename = 'download'; if (disposition) { // 优先匹配 RFC 5987 的 filename*=UTF-8''xxx 形式 const utf8Match = disposition.match(/filename\*=UTF-8''([^;]+)/i); if (utf8Match) { filename = decodeURIComponent(utf8Match[1]); } else { const normalMatch = disposition.match(/filename="?([^";]+)"?/i); if (normalMatch) { filename = normalMatch[1]; } } } const blob = await response.blob(); const objectUrl = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = objectUrl; a.download = filename; document.body.appendChild(a); a.click(); document.body.removeChild(a); setTimeout(() => URL.revokeObjectURL(objectUrl), 1000); }

这里有个跨域场景下极易踩的坑：默认情况下，跨域请求的响应头对前端 JS 是不可见的，response.headers.get('Content-Disposition')会返回null，不是后端没返回，是浏览器出于安全策略把它藏起来了。解决办法是让后端在 CORS 配置里加上：

Access-Control-Expose-Headers: Content-Disposition

少了这一行，前端不管怎么改代码都拿不到文件名，只能用一个默认值。我见过有团队为此排查了大半天，最后发现是这一行配置漏了。

4.3 大文件的内存账要提前算

blob 方案最容易被忽视的代价是内存。response.blob()会把整个文件读进浏览器内存，下载一个 200MB 的视频文件，意味着浏览器要额外占用 200MB 以上的内存（实际往往翻倍，因为还要算上生成 objectUrl 时的引用）。内存紧张的低配设备上，直接表现为页面白屏或者标签页崩溃。

如果文件确实很大，有几条路可以走。一是让后端给一个带签名的临时下载地址，前端用 a 标签直接跳转，完全绕过内存；二是用response.body.getReader()做流式读取，一边读一边写（需要配合 File System Access API，兼容性有限）；三是用分片下载再拼接，实现复杂度高，一般业务场景不值得。

我的经验判断线是这样：文件小于 20MB 走 blob 完全没问题；20MB 到 100MB 之间要谨慎，加上 loading 提示和失败重试；超过 100MB 就坚决不用 blob，去推动后端出方案。这条线不是拍脑袋定的，是在几个不同配置的设备上实测出来的大致区间，具体还要看你们的用户设备情况。

5. 文件名这条链路：中文、编码与乱码的真实成因

文件名看似是最不起眼的一环，实际上是我接到相关求助里占比最高的。用户下载下来一个叫download或者%E6%8A%A5%E8%A1%A8.xlsx的文件，体验直接崩掉。

5.1 前端 download 属性的中文处理

先说前端这一侧。a.download = '员工信息模板.xlsx'这种写法，在现代浏览器上是可以正常工作的，中文会被正确识别。但有两个前提：一是这个赋值发生在同源地址上，跨域时整个 download 都失效了，中文自然也谈不上；二是不要手动对它做decodeURIComponent或者encodeURIComponent，浏览器会自己处理。

我见过有人为了"保险"写成a.download = encodeURIComponent('员工信息模板.xlsx')，结果下载下来文件名变成了%E5%91%98%E5%B7%A5...。这个错误很典型——编码是给 URL 用的，不是给 download 属性用的，混淆了两者的作用域。

还有一个边界情况：文件名里包含/、\、:、*、?、"、<、>、|这些字符时，不同操作系统和浏览器的处理方式不一样，有的直接替换成下划线，有的截断。如果文件名是由用户输入或者业务数据拼出来的（比如"XX公司-2024年报表.xlsx"），一定要先做一次过滤：

function sanitizeFilename(name) { return name.replace(/[\\/:*?"<>|]/g, '_').trim(); }

5.2 响应头里的中文：两种编码格式的取舍

后端返回文件名时，如果带中文，用普通的filename="报表.xlsx"是不安全的，HTTP 头默认按 ISO-8859-1 编码，中文会变成乱码。正确做法是用 RFC 5987 定义的扩展语法：

Content-Disposition: attachment; filename="report.xlsx"; filename*=UTF-8''%E6%8A%A5%E8%A1%A8.xlsx

这里同时给了两个 filename，是给不同浏览器做兼容的：老浏览器读第一个，新浏览器优先读第二个（带了*=UTF-8''前缀的那个，值是 URL 编码后的 UTF-8 字节）。前端解析的时候也应该按这个优先级来，先找filename*，找不到再退回普通filename，就是上一节代码里那段正则的逻辑。

顺便说一句，filename*后面的值必须是encodeURIComponent处理过的，而且注意是 UTF-8 编码，不是 GBK。如果后端用了 GBK 编码，某些浏览器上依然会乱码，这个得让后端确认。

5.3 扩展名丢失：最容易被忽略的细节

还有一种情况：文件名是对的，但扩展名没了，用户下载下来是一个叫"报表"的未知文件，双击提示"选择打开方式"。这通常是因为前端在截取文件名时把扩展名一起截掉了。

比如从 URL 里取文件名，用url.split('/').pop()拿到的可能是report.xlsx?token=abc，带着查询参数；如果业务代码里又做了一次按点分割取后缀的判断，就容易出错。我的处理习惯是写一个专门的提取函数，把查询参数和哈希先去掉，再取最后一段：

function getFilenameFromUrl(url) { const clean = url.split('?')[0].split('#')[0]; const segments = clean.split('/'); const last = segments[segments.length - 1]; return last || 'download'; }

这个函数虽然简单，但能避免大量"文件名不对"的低级问题。写完记得保留扩展名，别在后续处理中再截断。

6. 点了没反应：从 Network 面板开始的排查路径

前面讲的都是"下载了但结果不对"，还有一类更让人抓狂的问题：点了按钮，什么都没发生。没有报错、没有下载、页面也没跳转，安静得像个假按钮。这类问题必须有一套固定的排查路径，否则就是瞎猜。

6.1 第一步永远是看 Network 面板

打开开发者工具的 Network 面板，勾选 Preserve log（防止页面跳转后记录被清空），然后点一次下载按钮，看有没有产生新的请求。

如果没有请求，说明问题在点击事件本身。可能性有三种：按钮被其他元素遮挡（比如一个透明蒙层）、事件被preventDefault了、或者按钮根本没绑定上（组件复用时的常见坑）。判断方法是直接在 Console 里查一下那个 DOM 节点，手动调用一次click()，看有没有反应。

如果有请求但状态码不是 200，那就是后端或者路径问题。404 是路径拼错或 base 前缀没处理，403 是鉴权失败或者链接过期，500 是后端自己出错。这类问题看状态码基本就能定位，不需要在前端纠结。

如果有请求且状态码 200，那就往下看响应头和响应体，进入下一节的判断。

6.2 200 之后还能出什么问题

状态 200 但下载没成功，通常落在下面这几种情况里，我做了一张对照表，排查的时候直接对号入座：

表格里第五行那个"文件名是 UUID"的情况特别有意思，我遇到过两次，都是因为用了对象存储的临时地址，地址最后一段本身就是一串哈希，浏览器没拿到download属性也没拿到Content-Disposition，就只能拿 URL 最后一段当文件名。这种问题前端加个download属性就能解决，前提还是那句话——同源。

6.3 一个容易被遗忘的排查点：CORS 预检

如果请求是跨域的、且带了自定义头（比如 Authorization），浏览器会先发一个OPTIONS预检请求。这个预检如果失败，真正的 GET 请求根本发不出去，Network 面板上只会看到一个红色的 OPTIONS 请求，Console 里报 CORS 错误。

排查这类问题时，别只盯着 GET 请求看，先看有没有 OPTIONS，它的响应头里有没有Access-Control-Allow-Origin、Access-Control-Allow-Headers这两项。少一项预检就过不了。尤其在加了新的自定义头之后，一定要确认后端的Access-Control-Allow-Headers里包含了它，否则就是加一个头挂一次。

7. 手机端与内嵌浏览器里那些电脑上测不出的问题

这个功能最坑的地方在于，你在电脑上把所有浏览器都测了一遍，一切正常，交付给用户之后，用户在手机上点了一下，反馈"没反应"。移动端和桌面端的差异，在这类下载功能上体现得特别明显。

7.1 iOS Safari 与安卓 WebView 的不同脾气

iOS Safari 对 blob 下载的支持是分版本的。较早的版本里，a.download对 blob 地址基本无效，点了之后要么什么都不发生，要么在新标签页里打开一个空白页。iOS 13 之后情况好转，但对大文件依然不友好，因为移动端内存更紧张。

安卓的情况又不一样。原生浏览器一般能正常处理，但在 WebView 里（也就是 App 内嵌的浏览器），下载行为完全由宿主 App 决定。如果 App 没有实现DownloadListener，点击下载链接就是没反应。这种问题前端完全无解，得让客户端同学配合。

微信内置浏览器是另一个重灾区。它出于自身策略考虑，对很多下载行为做了限制，尤其是文件类型不在白名单里的时候。表现通常是提示"已限制在此页面下载"或者干脆无响应。比较稳妥的处理是检测到微信环境时，直接给一个引导层的提示，让用户在右上角菜单里选择"在浏览器中打开"。

7.2 检测环境与降级策略

环境检测这块，不用引入任何库，UA 字符串就够用了：

function isWechat() { return /micromessenger/i.test(navigator.userAgent); } function isIOS() { return /iphone|ipad|ipod/i.test(navigator.userAgent); }

拿到环境判断结果之后，策略要分档。微信环境直接弹提示引导外部打开，不要浪费时间去尝试下载；iOS 环境优先用 a 标签方案（同源时最稳），blob 方案作为备选；安卓环境正常处理，但要注意 WebView 的差异，可以在下载后加一个"如果 3 秒内没有反应，请长按链接另存为"的兜底提示。

还有个小技巧：移动端触发下载之后，页面很容易因为内存占用过高被系统回收，用户切回来发现页面重新加载了。如果这个下载动作是在一个填了很多表单的页面上做的，用户体验会非常糟。我的做法是在下载前用sessionStorage存一份表单草稿，页面恢复时自动回填。这个处理不是必须的，但对表单类后台系统来说，能省掉大量"我填的东西没了"的投诉。

7.3 移动端的文件名处理差异

同一个download="员工信息模板.xlsx"，在电脑上文件名正常，在某些安卓浏览器上下载下来变成download.xlsx或者干脆没有扩展名。这种差异确实存在，而且没有统一的解决方案，因为不同厂商的浏览器内核实现不一样。

能做的优化是把文件名处理得更"保守"一点：尽量用英文加数字的组合，避免空格、括号、特殊符号；如果业务必须用中文，至少保证扩展名完整，这样即使用户拿到的名字不对，文件本身还能正常打开。这是我能给出的最实际的建议——文件名这件事，在移动端不要追求完美，追求"能打开"就行。

8. 收敛成一个能复用的下载工具与我的几条经验

项目里这类下载需求往往会散落在十几个页面里，每个页面各写一套，改的时候满代码库搜createElement('a')。我后来的做法是把它收敛成一个统一的工具函数，所有页面都调它，行为统一、bug 也只在一个地方修。

8.1 工具函数的完整形态

下面这个版本是我在多个项目里迭代出来的，覆盖了同源直连、跨域 blob、文件名解析、错误提示几个核心场景：

export async function downloadFile(options) { const { url, filename, headers = {}, onProgress, } = options; // 同源且无需鉴权头，直接走 a 标签，省内存 if (isSameOrigin(url) && Object.keys(headers).length === 0) { const a = document.createElement('a'); a.href = url; if (filename) a.download = filename; a.style.display = 'none'; document.body.appendChild(a); a.click(); document.body.removeChild(a); return; } // 其余情况走 blob const response = await fetch(url, { headers }); if (!response.ok) { throw new Error(`下载失败：${response.status}`); } const finalName = filename || parseFilename(response.headers.get('Content-Disposition')) || 'download'; const blob = await response.blob(); const objectUrl = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = objectUrl; a.download = sanitizeFilename(finalName); a.style.display = 'none'; document.body.appendChild(a); a.click(); document.body.removeChild(a); setTimeout(() => URL.revokeObjectURL(objectUrl), 1000); }

这段代码里有一个关键的分支判断：同源且不带自定义头时走 a 标签，否则走 blob。这个优化看起来不起眼，但效果很实在——同源的大文件下载不会占用额外内存，用户下载一个 500MB 的备份包也不会把页面搞崩。我最初偷懒全用 blob，结果在一个导出大文件的场景里被用户投诉页面卡死，才补上这个分支。

isSameOrigin的实现很简单，用new URL(url, location.href).origin === location.origin判断即可，注意要处理相对路径的情况，所以第二个参数传了location.href。

8.2 我在这个功能上踩出来的几条经验

第一条，别信"本地测过了"。这个功能涉及同源、跨域、CORS、浏览器策略、打包路径、移动端内核，每一层都可能是变量，本地环境恰好把所有变量都对齐了。我的习惯是上线前至少验证三种环境：本地开发环境、测试环境的真实部署地址、以及一个跨域的资源地址。

第二条，优先推动后端改响应头。前端能做的所有绕行方案（blob、代理、临时地址）都是成本，而后端加一行Content-Disposition: attachment和Access-Control-Expose-Headers几乎没有成本。能用配置解决的，别用代码解决。

第三条，文件名一定要做兜底。不管从哪儿解析出来的文件名，最后都要过一遍sanitizeFilename，并且确保有扩展名。用户下载下来一个打不开的文件，比下载失败更让人恼火，因为失败至少还知道是失败了。

第四条，下载失败要有明确提示。很多实现里fetch报错了直接被吞掉，用户点了没反应也不知道为什么。至少要把错误状态码和一句人话提示抛出去，比如"文件生成中，请稍后重试"或者"下载失败，请检查网络"。这一条不是技术问题，是产品意识。

提示：如果你们的下载接口耗时较长（比如后端要实时生成报表），不要只给一个静态的 loading，最好能拿到生成进度。这种场景下用 XHR 的onprogress或者 fetch 的流式读取会比一次性 blob 体验好很多，虽然实现复杂度上去了，但用户能看见进度条在动，焦虑感会低很多。

最后分享一个小习惯：我现在做任何下载功能，都会先问一句"这个文件多大、给谁下、在什么网络环境下下"。这三个问题的答案直接决定了方案选型——几十 KB 的模板文件，a 标签加同源就够；几十 MB 的报表，得考虑后端异步生成加轮询；几百 MB 的备份包，前端就不该碰，老老实实让后端出一个临时直链。方案是为场景服务的，没有万能写法，只有对当下场景最不别扭的那一种。