浏览器文件下载链路的渐进增强设计：从另存为到跨域兜底

原文链接浏览器文件下载链路的渐进增强设计从另存为到跨域兜底文件下载看似只是创建一个a标签并调用click()但一旦加入跨域资源、鉴权接口、用户自定义保存位置、Safari/Firefox 兼容性以及数百 MB 以上文件下载能力就会变成一个需要分层设计的问题。一个可落地的前端下载链路可以按能力渐进增强File System Access API让用户主动选择保存位置和文件名并由页面写入文件fetchBlob Object URL a[download]在 JavaScript 能读取响应字节时转换为同源blob:URL 后下载直连a[download]作为通用兜底但跨域 HTTP(S) 地址无法仅靠download属性强制下载。这三层不是互斥实现而是一条应根据浏览器能力、CORS 条件、文件体积和服务端契约选择的下载策略。先建立边界网页不能静默写入用户任意路径浏览器把“写入本地文件系统”和“读取跨域响应”都视为高风险能力。因此前端不能通过 JavaScript 静默把文件保存到用户磁盘上的任意目录也不能绕过服务端 CORS 设置把跨域响应转成 Blob。下载方案的选择取决于两个关键问题用户是否需要选择保存位置如果需要优先考虑showSaveFilePicker()。JavaScript 能否读取文件字节如果资源跨域fetch()必须获得服务端的 CORS 授权否则 Blob 路径和流式写入路径均不可用。三层能力矩阵方案用户可选保存位置跨域可控性大文件内存表现浏览器覆盖后端配合File System Access API是仍要求响应可被fetch读取可流式写入较优主要为 Chromium 系跨域时需要 CORSfetch Blob Object URL否由浏览器下载设置决定可控但必须有 CORS文件通常会完整进入内存现代浏览器普遍可用跨域时需要 CORS直连a[download]否跨域不可由前端保证不需要前端缓存完整文件覆盖最广跨域稳定下载依赖Content-Disposition第一层File System Access API——真正的“另存为”体验window.showSaveFilePicker()会由浏览器打开保存选择器。用户选择目录、输入文件名或确认已有文件后页面才获得一个FileSystemFileHandle随后可通过createWritable()创建写入流并在写完后调用close()提交文件。这不是静默下载能力而是用户主导的保存与写入能力。该 API 需要 HTTPS 安全上下文并要求瞬时用户激活。因此应在点击事件开始时立即调用选择器而不是等网络请求或文件生成结束后再调用。用户取消选择器通常会得到AbortError脱离用户手势调用可能得到SecurityError。MDNshowSaveFilePicker基础写入适合前端已生成 Blob 或中小文件async function saveBlobWithPicker(blob: Blob, filename: string) { const handle await window.showSaveFilePicker({ suggestedName: sanitizeFilename(filename), }); const writable await handle.createWritable(); try { await writable.write(blob); await writable.close(); } catch (error) { await writable.abort(); throw error; } }这里的close()很重要它表示写入完成并提交结果。若写入过程失败应尝试abort()避免将不完整内容作为成功文件保留。大文件变体先选路径再把响应流写入文件如果文件可能达到数百 MB 或 GB先fetch()再response.blob()会让完整文件在浏览器内存中缓冲。对于支持 File System Access API 的浏览器更合理的顺序是在用户点击时立刻打开保存选择器获得文件句柄后再发起请求检查 HTTP 状态将response.body直接pipeTo()文件写入流。async function saveRemoteFileByStream( url: string, filename: string, init: RequestInit {}, ) { // 调用此函数本身应直接发生在点击处理函数中避免丢失用户激活。 const handle await window.showSaveFilePicker({ suggestedName: sanitizeFilename(filename), }); const response await fetch(url, init); if (!response.ok) { throw new Error(下载失败HTTP ${response.status}); } if (!response.body) { throw new Error(当前浏览器未提供可读取的响应流); } const writable await handle.createWritable(); try { await response.body.pipeTo(writable); } catch (error) { // pipeTo 默认会在源流失败时中止目标流此处额外尝试 abort兼容异常路径。 try { await writable.abort(); } catch { // 写入流已关闭或已中止时无需覆盖原始异常。 } throw error; } }FileSystemWritableFileStream是可写流因此可以与ReadableStream.pipeTo()配合避免把整个响应先聚合为 Blob。这个优化并不突破跨域限制只要响应不能被 CORS 授权读取response.body同样不可供脚本使用。MDNFile System API MDNFetch API兼容性与权限边界showSaveFilePicker()属于非 Baseline 的实验性能力不能作为唯一链路。它主要适合 Chromium 系浏览器中的增强体验而不支持该 API 的浏览器网页通常不能替代浏览器原生下载设置来让用户选择系统保存路径。即使业务保存过文件句柄后续也不应假定写入权限永久有效用户或浏览器可能撤销授权。恢复句柄后应重新检查权限并在需要时由用户操作触发权限请求。Chrome for DevelopersFile System Access API第二层fetch Blob Object URL——把“可读响应”变成可下载资源当浏览器不支持 File System Access API或者业务不需要用户指定保存路径时常用方案是fetch 响应 → 检查 HTTP 状态 → response.blob() → URL.createObjectURL(blob) → 临时 a[download] → a.click() → URL.revokeObjectURL(url)核心不是a[download]本身而是先将 JavaScript 已成功读取的内容变成blob:URL。blob:URL 是当前页面创建并可控制的临时资源因此download属性在这里通常可可靠生效。async function downloadWithBlob( url: string, filename: string, init: RequestInit {}, ) { const response await fetch(url, init); if (!response.ok) { throw new Error(下载失败HTTP ${response.status}); } const blob await response.blob(); const objectUrl URL.createObjectURL(blob); const link document.createElement(a); link.href objectUrl; link.download sanitizeFilename(filename); link.style.display none; document.body.appendChild(link); link.click(); link.remove(); // 没有通用的“下载已结束”事件。延迟释放以避免过早回收同时避免长期持有 Blob。 window.setTimeout(() URL.revokeObjectURL(objectUrl), 60_000); }Object URL 会持有 Blob 的引用不再需要时应调用URL.revokeObjectURL()释放资源。延迟时间应结合文件大小、浏览器行为和产品测试确定不能将“点击后立刻释放”视为所有浏览器中的无条件安全做法。MDNrevokeObjectURL跨域限制Blob 路径的前提是 CORS 可读跨域fetch()默认走 CORS。服务端必须返回正确的Access-Control-Allow-Origin浏览器才会把响应交给 JavaScript否则前端拿不到响应体自然也无法blob()。不要把mode: no-cors当成绕过方案。它得到的是 opaque response状态为0、响应头为空、响应体对 JavaScript 不可读因此不能用于可靠地创建可下载 Blob。MDNCORS 错误与 opaque response若下载接口依赖跨域 Cookie前端需要设置credentials: include服务端则必须返回精确的Access-Control-Allow-Origin而非*并返回Access-Control-Allow-Credentials: true。若请求带有Authorization等非简单请求头还需正确处理 OPTIONS 预检。MDNCORS文件名前端建议值与服务端真实值a.download中的文件名只是建议值浏览器仍可能基于安全策略、用户设置或资源类型调整最终名称。需要区分两种情形对Blob/Object URL 下载生成的blob:URL 不携带原始 HTTP 响应的Content-Disposition通常应由前端在download属性中指定文件名。对直连 HTTP(S) 下载服务端的Content-Disposition可影响浏览器是否下载及最终文件名并可能优先于download建议值。如果前端希望从跨域fetch()响应中读取Content-Disposition并解析服务端文件名后端还必须额外发送Access-Control-Expose-Headers: Content-Disposition因为Content-Disposition不属于默认暴露给脚本读取的 CORS 响应头。MDNAccess-Control-Expose-Headers前端应清洗文件名至少移除路径分隔符、控制字符及业务不允许的字符扩展名应与实际内容类型保持一致而不是仅相信用户输入。第三层直连 a[download]——必要但能力有限的兜底当 File System Access API 不可用、资源没有 CORS 授权、或者文件过大而不适合前端完整缓冲时最后的策略是直接导航到下载地址function downloadByLink(url: string, filename?: string) { const link document.createElement(a); link.href url; if (filename) link.download sanitizeFilename(filename); link.rel noopener; link.style.display none; document.body.appendChild(link); link.click(); link.remove(); }但必须明确download属性对同源 URL、blob:URL 和data:URL最可靠对于跨域 HTTP(S) URL前端不能依赖它强制浏览器下载。浏览器可能导航到该地址、在页内预览 PDF 或图片或者按照用户浏览器设置处理。MDNa 元素 download 属性因此直连跨域下载是否稳定不取决于前端是否写了download而取决于服务端是否返回合适的下载响应头。服务端下载契约前端无法绕过的部分如果需要跨浏览器稳定下载跨域文件后端至少应提供以下两类能力之一。契约一允许前端读取文件字节适用于fetch Blob或 File System Access API 流式写入Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Credentials: true Access-Control-Expose-Headers: Content-Disposition, Content-Length是否需要Access-Control-Allow-Credentials取决于请求是否携带 Cookie 或 HTTP 认证信息不携带凭据时可按安全策略使用更宽松的Access-Control-Allow-Origin。若前端读取Content-Length还需注意压缩传输、分块传输和服务端未提供该头时大小提示可能不准确或不存在。契约二提供可直接导航的附件下载地址适用于直链方案Content-Type: application/pdf Content-Disposition: attachment; filenamereport.pdf; filename*UTF-8report.pdfContent-Disposition: attachment表示浏览器应将响应视为附件下载而非优先页内展示。filename*支持 UTF-8 编码的文件名同时提供filename和filename*通常有利于兼容性。MDNContent-Disposition当远端既不给 CORS也不提供Content-Disposition: attachment前端没有可靠的浏览器端绕过方法。此时应考虑由自有后端代理下载或调整对象存储/CDN 的响应头和签名 URL 策略而不是试图用no-cors或强制点击链接解决。推荐决策顺序按能力探测而不是 UA 嗅探不要根据浏览器名称硬编码策略。应根据实际能力和资源条件判断支持showSaveFilePicker且资源可被fetch读取用户需要指定保存位置时优先使用大文件优先流式pipeTo()写入。资源可被fetch读取且文件大小可接受使用 Blob Object URL适合需要前端附加认证头、改名、二次处理的下载。无法 CORS 读取或不适合前端缓存完整文件退化到直连 URL服务端有Content-Disposition: attachment时通常能稳定下载。跨域直链没有 attachment明确告知用户文件可能在新页面打开或被浏览器预览不要承诺“已开始下载”。function canUseSavePicker(): boolean { return typeof window.showSaveFilePicker function; }能力探测只回答“能否尝试第一层”不能替代对 CORS、文件体积、鉴权方式和服务端下载头的判断。对跨域资源而言通常无法在不实际发起请求的前提下可靠预判 CORS 是否允许读取因此实现中应将fetch失败视为可降级条件之一。一个可复用的策略骨架以下骨架统一传递请求配置避免第一层、第二层意外使用不同的鉴权方式。调用downloadFile()应直接发生在用户点击处理函数中尤其是启用保存选择器时。type DownloadOptions { url: string; filename: string; preferSavePicker?: boolean; sizeHint?: number; requestInit?: RequestInit; fallbackToLink?: boolean; }; async function downloadFile(options: DownloadOptions) { const { url, filename, preferSavePicker true, sizeHint, requestInit { credentials: same-origin }, fallbackToLink true, } options; try { if (preferSavePicker canUseSavePicker()) { await saveRemoteFileByStream(url, filename, requestInit); return { strategy: file-system-access as const }; } // 阈值应按真实产品内存预算配置而不是写死为统一数字。 const isTooLargeForBlob typeof sizeHint number sizeHint 200 * 1024 * 1024; if (!isTooLargeForBlob) { await downloadWithBlob(url, filename, requestInit); return { strategy: blob as const }; } } catch (error) { if (error instanceof DOMException error.name AbortError) { return { strategy: cancelled as const }; } console.warn(增强下载链路失败, error); } if (!fallbackToLink) { return { strategy: failed as const }; } downloadByLink(url, filename); return { strategy: link as const }; }生产实现中应将“增强链路失败后是否自动发起直链”作为产品决策而不是无条件行为。例如用户在保存选择器中点击取消时不应立刻再触发直链下载而 CORS 或网络失败时更适合提供“尝试在浏览器中打开该文件”的显式按钮。还应注意携带Authorization请求头的 Blob 或流式请求无法原样降级为普通链接因为浏览器导航不能由前端附加该请求头此时应由后端提供签名直链或同源代理地址。错误分类与用户体验不要把所有异常都提示为“下载失败”。至少应区分以下情形AbortError用户取消了保存位置选择应静默结束或提示“已取消保存”。SecurityError保存选择器没有在用户手势中触发或受到安全策略限制应检查调用时机和 HTTPS 环境。HTTP 非 2xx这是服务端业务或资源错误不应继续把错误页保存为文件。fetch被浏览器拒绝可能是 CORS、网络、DNS、证书或浏览器策略问题前端通常无法仅凭该异常精确断言为 CORS 失败应结合开发者工具和服务端日志排查。本地写入失败可能是权限、磁盘空间或用户撤销授权应保留可重试入口。直链退化跨域地址可能打开预览页应明确说明“浏览器将尝试打开或下载该文件”。此外下载按钮应防重复点击对长时间任务提供进行中状态对超大文件尽量使用服务端附件直链或 Chromium 中的流式写入而不要默认走全量 Blob。结语浏览器下载能力的关键不是选一个“万能 API”而是承认不同层级的权限边界File System Access API 提供最佳的用户可控保存体验但不是全浏览器方案Blob/Object URL 能提高跨域下载的可控性但前提是 CORS 允许脚本读取响应且要承担内存成本直连链接覆盖最广却无法仅凭download属性强制跨域下载稳定性最终仍依赖服务端的Content-Disposition。因此合理的下载设计应把前端能力探测、CORS 契约、附件响应头、文件体积和清晰的降级提示组合起来。前端可以优化体验但不能从根本上绕过浏览器同源策略与用户文件系统权限模型。参考资料MDNWindow.showSaveFilePicker()Chrome for DevelopersFile System Access APIMDNUsing the Fetch APIMDNHTML a 元素与 download 属性MDNContent-DispositionMDNAccess-Control-Expose-HeadersMDNURL.revokeObjectURL()