JavaScript文件下载方法详解：从HTML5到Fetch API的三种方案

文件下载是 Web 开发中一个高频且基础的功能需求，无论是导出用户数据、下载生成的报表，还是获取应用程序包，前端开发者都需要掌握多种实现方案。每种方案都有其特定的适用场景和优缺点，了解它们的原理能帮助我们在不同需求下做出最合适的选择。

1. <a> 标签的 download 属性（最简单直接）

这是实现文件下载最简单直接的方式，尤其适用于下载服务器上的静态资源或已知 URL 的文件。

原理：
HTML5 为 <a> 标签引入了 download 属性。当用户点击带有此属性的链接时，浏览器会强制下载链接指向的资源，而不是导航到该页面。你还可以为 download 属性指定一个值，作为建议给用户的下载文件名。

示例代码：

优点：

• 实现简单：无需编写任何 JavaScript 代码。
• 语义化好：清晰表达了链接的下载意图。
• 兼容性好：现代浏览器均提供良好支持。

缺点：

• 同源限制：对于跨域资源，如果目标服务器没有正确设置 Access-Control-Allow-Origin 响应头，download 属性可能会被忽略（浏览器可能转为导航或无法使用指定文件名）。
• 不适用于动态内容：无法处理需要先通过 API 获取数据、再动态生成文件的场景。
• 缺乏请求控制：无法添加自定义请求头（如 Authorization 用于身份验证）。

2. window.open() 或 window.location.href（传统导航方式）

这种方式本质上是让浏览器导航到一个文件 URL。其下载行为完全依赖服务器的响应头：如果服务器在响应中设置了 Content-Disposition: attachment; filename="filename.ext" 这样的 HTTP 头部，浏览器就会触发下载对话框。

示例代码：

优点：

• 实现简单：一行代码即可触发。
• 可下载跨域文件：只要目标服务器正确设置了 Content-Disposition 响应头。

缺点：

• 文件名由后端控制：下载的文件名由服务器的 Content-Disposition 头部决定，前端难以直接干预（除非将文件名编码在 URL 参数中）。
• 体验可能不佳：使用 window.location.href 会导致当前页面跳转，若下载失败或响应非文件流，用户体验差。window.open() 则可能被浏览器的弹出窗口拦截器阻止。
• 无法自定义请求：同样不能添加认证头等自定义请求头。
• 不适用前端Blob数据：无法用于下载前端在内存中生成的 Blob 对象数据。

3. 使用 Fetch API / XHR + Blob + URL.createObjectURL()（最灵活强大）

这是目前功能最全面、控制力最强的前端下载方案，特别适用于需要身份认证、动态生成内容或处理 API 返回的二进制数据等复杂场景。

原理：

1. 使用 Fetch API 或 XMLHttpRequest 向服务器发送请求，获取文件数据。
2. 将响应体（二进制数据）转换为 Blob 对象。Blob 对象代表一个不可变的、原始数据的类文件对象。
3. 使用 URL.createObjectURL(blob) 为该 Blob 对象在浏览器内存中创建一个临时的本地 URL。
4. 动态创建一个隐藏的 <a> 标签，将其 href 属性指向这个临时 URL，并设置 download 属性为期望的文件名。
5. 通过 JavaScript 模拟点击该 <a> 标签，触发下载。
6. （重要）下载触发后，使用 URL.revokeObjectURL(objectURL) 释放临时 URL，以避免内存泄漏。

示例代码 (使用 Fetch API)：

优点：

• 完全控制请求：可以灵活设置自定义请求头（如 Authorization）、请求方法、请求体等，非常适合访问需要认证的API。
• 高效处理动态数据：完美适配从后端 API 获取数据后再触发下载的流程。
• 完善的错误处理：可以精确捕获并处理网络请求、服务器错误等各种异常。
• 支持进度监控：XMLHttpRequest 支持 progress 事件，可用于实现下载进度条（Fetch API 通过 ReadableStream 也能实现，稍复杂）。
• 可下载前端生成的内容：可以将前端生成的 Canvas 图片、JSON 字符串等数据转换为 Blob 并直接提供下载。

缺点：

• 实现相对复杂：需要编写更多的 JavaScript 代码来处理请求、Blob 和 URL。
• 需注意内存管理：必须记住调用 URL.revokeObjectURL() 来释放资源。

方案选择指南

面对具体需求时，你可以参考以下思路进行选择：

• 场景一：下载已知的静态文件（如同域图片、文档）
  首选方案：使用 <a> 标签的 download 属性。简单、高效、语义明确。

• 场景二：服务器动态生成文件并直接返回文件流（可跨域）
  可考虑方案：使用 window.open() 或 window.location.href。确保后端同事在响应中正确设置了 Content-Disposition: attachment 头部。

• 场景三：需要携带 Token 认证、从 API 获取数据后下载、或需要精确控制下载过程
  最佳方案：使用 Fetch API 或 XHR 结合 Blob 和 URL.createObjectURL()。这是应对复杂下载需求的终极解决方案，提供了最大的灵活性和控制力。

理解这些前端下载技术背后的原理和各自的适用边界，能帮助你在实际开发中快速定位问题，并为项目选择最优雅、高效的实现方式。如果你想深入了解更前沿的 Web 开发技术，欢迎在 云栈社区 与其他开发者交流探讨。