js代码下载怎么用：从准备到完成的实操步骤

在网页里实现“下载”，不一定需要引入下载库。对于文本、JSON、CSV 等由页面生成的小文件，原生 JavaScript 就能完成；对于服务器已有的文件，通常直接使用链接或让服务器返回下载响应更合适。选错方式，常见结果是下载按钮没有反应、文件内容乱码、跨域请求失败，或大文件占用过多内存。

本文从选择方案开始，依次介绍浏览器端生成文件、下载服务器文件、处理文件名和常见问题。示例使用现代浏览器支持的 Blob、URL.createObjectURL 和 Fetch API。

一、先判断你要下载的是什么

动手之前，先区分文件来源和大小。

• 网页生成的小文件：例如导出的配置、JSON、CSV、日志片段。可以把内容放进 Blob，再创建临时下载链接。
• 服务器上的现成文件：例如 PDF、压缩包、安装包。优先使用普通下载链接，由服务器返回文件。
• 需要请求鉴权接口的文件：可以用 Fetch 携带令牌或 Cookie，读取响应后生成下载；但这通常会把完整文件放进浏览器内存。
• 很大的文件：尽量让浏览器直接从服务器下载，避免先用 JavaScript 把全部内容读入内存。

JavaScript 负责触发浏览器下载，不代表网页可以任意读取用户电脑文件，也不意味着下载行为能够绕过浏览器的权限、安全提示或服务器的访问控制。

二、准备一个最小可运行页面

下面的例子保存为 download.html 后，用浏览器打开即可运行。点击按钮时，脚本生成一段文本并触发下载。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>JavaScript 下载示例</title>
<button id="downloadBtn" type="button">下载文本文件</button>
<script>
  document.querySelector("#downloadBtn").addEventListener("click", () => {
    const content = "这是由 JavaScript 生成的文件。\\n";
    const blob = new Blob([content], { type: "text/plain;charset=utf-8" });
    const url = URL.createObjectURL(blob);

    const link = document.createElement("a");
    link.href = url;
    link.download = "示例.txt";
    document.body.appendChild(link);
    link.click();
    link.remove();

    setTimeout(() => URL.revokeObjectURL(url), 1000);
  });
</script>
</html>

这个流程由四步组成：创建 Blob、为 Blob 生成临时 URL、通过带有 download 属性的链接触发下载、释放临时 URL。临时 URL 不是可长期保存或分享的文件地址；页面不再需要它时，应调用 URL.revokeObjectURL() 释放关联资源。

三、理解 Blob、MIME 类型和文件名

1. 用 Blob 表示待下载内容

Blob 可以看作一段不可变的二进制数据。它的第一个参数是数据片段数组，片段可以是字符串、其他 Blob 或类型化数组等；第二个参数可以指定媒体类型，也就是 MIME 类型。

const textBlob = new Blob(["hello"], {
  type: "text/plain;charset=utf-8"
});

const jsonBlob = new Blob(
  [JSON.stringify({ name: "Ada", enabled: true }, null, 2)],
  { type: "application/json;charset=utf-8" }
);

MIME 类型有助于系统和应用识别文件内容，但它不会自动转换内容格式。比如把一段普通文本的类型写成 application/pdf，不会因此得到有效的 PDF 文件。文件扩展名也应与实际内容相符。

当文本包含中文时，UTF-8 通常是合适的编码选择。某些旧版电子表格软件打开 CSV 时对编码识别不一致，可根据目标软件的要求调整编码或文件内容；不要把“换一个扩展名”当作编码转换。

2. 文件名由 download 属性指定

link.download 用来建议浏览器采用的下载文件名。浏览器或操作系统可能会清理不支持的字符、调整重名文件，或按自身规则处理扩展名。因此它不是对最终磁盘路径的控制手段，网页也不能借此指定用户电脑上的任意保存目录。

文件名如果来自用户输入或服务器数据，应限制长度，并过滤路径分隔符和控制字符，避免把路径片段或不合适的字符带入文件名。以下函数是一个基础示例，不应被视为适用于所有文件系统的完整命名规则：

function safeFileName(input, fallback = "download") {
  const cleaned = String(input)
    .replace(/[\\\/\u0000-\u001f\u007f]/g, "_")
    .trim()
    .slice(0, 120);

  return cleaned || fallback;
}

function downloadBlob(blob, fileName) {
  const url = URL.createObjectURL(blob);
  const link = document.createElement("a");

  link.href = url;
  link.download = safeFileName(fileName);
  document.body.appendChild(link);
  link.click();
  link.remove();

  setTimeout(() => URL.revokeObjectURL(url), 1000);
}

示例中的名称清理主要避免路径分隔符和控制字符，并限制字符数量。不同系统对保留名称、特殊字符和扩展名的规则并不完全相同。若业务对文件名有严格要求，应在服务端也执行相应校验。

四、导出 JSON 和 CSV

导出 JSON

JSON 导出时，先把 JavaScript 数据序列化为字符串，再创建 Blob。JSON.stringify 的缩进参数可以让文件更便于阅读。

function exportJson(data, fileName = "data.json") {
  const json = JSON.stringify(data, null, 2);
  const blob = new Blob([json], {
    type: "application/json;charset=utf-8"
  });

  downloadBlob(blob, fileName);
}

const report = {
  generatedAt: new Date().toISOString(),
  items: [
    { id: 1, name: "项目一" },
    { id: 2, name: "项目二" }
  ]
};

document.querySelector("#exportJson").addEventListener("click", () => {
  exportJson(report, "报告.json");
});

实际页面需要存在一个 id="exportJson" 的按钮。导出数据前要考虑敏感信息：页面中可访问的数据可能会被用户下载，不能把密钥、其他用户的数据或内部调试信息不加区分地写入导出文件。

导出 CSV

CSV 看起来只是用逗号分隔字段，但字段内容可能本身就包含逗号、双引号或换行符。下面的实现会对双引号进行转义，并将每个字段包在双引号中：

function toCsv(rows) {
  return rows.map((row) =>
    row.map((value) => {
      const text = String(value ?? "");
      return '"' + text.replace(/"/g, '""') + '"';
    }).join(",")
  ).join("\r\n");
}

function exportCsv(rows, fileName = "data.csv") {
  const csv = toCsv(rows);
  const blob = new Blob(
    ["\uFEFF", csv],
    { type: "text/csv;charset=utf-8" }
  );

  downloadBlob(blob, fileName);
}

const rows = [
  ["姓名", "备注"],
  ["小林", '内容包含逗号, 和双引号"']
];

exportCsv(rows, "人员.csv");

这里的 \uFEFF 是 UTF-8 BOM，在一些表格软件中有助于识别 UTF-8 编码，但并非所有 CSV 消费方都需要或偏好 BOM。如果下游程序严格按字节解析，应根据其格式要求决定是否保留。CSV 转义也不等同于对所有电子表格公式注入风险的处理：如果导出内容可能以 =、+、- 或 @ 等字符开头，应评估目标软件如何解释单元格，并按业务需要额外处理不可信数据。

五、下载服务器上的文件

方案一：使用普通链接

如果文件已经由服务器提供，最简单的方式通常是链接到文件地址：

<a href="/files/manual.pdf">下载手册</a>

服务器可以通过响应头 Content-Disposition: attachment 告知浏览器将响应作为附件处理，并提供建议文件名。例如：

Content-Type: application/pdf
Content-Disposition: attachment; filename="manual.pdf"

浏览器对响应类型、站点策略和链接来源等因素的处理可能不同。HTML 的 download 属性对跨源链接不一定生效；如果文件来自其他域名，不能假设仅添加 download 就能强制下载。更可靠的方式通常是由文件服务器正确设置响应头，或通过受控的同源接口提供文件。

不要把敏感文件放在公开可猜测的静态地址上，再仅依赖前端隐藏链接来保护它。真正的访问控制应由服务器验证用户身份和权限。

方案二：Fetch 请求后生成下载

当文件接口需要自定义请求头，或需要在前端处理响应时，可以使用 Fetch。以下示例会在请求成功后读取整个响应为 Blob：

async function downloadFromApi() {
  const response = await fetch("/api/export", {
    method: "GET",
    headers: {
      "Authorization": "Bearer YOUR_TOKEN"
    }
  });

  if (!response.ok) {
    throw new Error(`下载失败：HTTP ${response.status}`);
  }

  const blob = await response.blob();
  downloadBlob(blob, "export.bin");
}

document.querySelector("#downloadApi").addEventListener("click", () => {
  downloadFromApi().catch((error) => {
    console.error(error);
    alert("文件下载失败，请稍后重试。");
  });
});

将 YOUR_TOKEN 替换为应用实际获得的令牌，不要把长期有效的密钥硬编码在公开网页代码中。若接口依靠同站 Cookie 鉴权，应按接口设计配置请求和服务端的 Cookie、跨站请求相关策略，而不是盲目复制示例中的令牌写法。

Fetch 读取跨域响应受同源策略和 CORS 约束。服务器必须允许当前页面来源访问相应资源；仅在前端设置某个请求头，不能绕过浏览器的跨域限制。跨域请求若需发送凭据，服务端也必须正确配置凭据相关的 CORS 响应，且不能用通配来源代替明确授权。浏览器控制台里的 CORS 错误通常需要在服务器端排查。

上例通过 response.blob() 读取响应后再创建下载链接。对大文件而言，这种模式通常需要在客户端保存完整响应数据，内存占用会增加；进度展示和取消也需要额外设计。若只是下载文件，优先考虑直接导航到下载地址或普通链接，并让服务端返回附件响应。

六、处理下载失败与接口文件名

普通链接和 Fetch 方案的错误处理方式不同。普通链接的下载过程由浏览器管理，页面脚本不一定能方便地获知下载是否最终保存成功；Fetch 则可以检查 HTTP 状态，但读取文件仍可能因网络中断、权限失败或浏览器限制而失败。

服务器可能在 Content-Disposition 中提供文件名。若前端采用 Fetch 并自行创建 Blob 链接，不能指望浏览器把原响应的附件文件名自动传给新链接；如果业务需要沿用服务端文件名，需要读取响应头，并确保服务器允许页面读取该响应头。跨域场景通常还需要服务器通过 CORS 的响应头暴露相应字段。

不同浏览器和服务器对文件名参数的编码支持可能不一致。服务端应按照 HTTP 规范生成 Content-Disposition，避免直接拼接未经处理的用户输入。前端解析文件名时也要把它当作不可信数据，经过安全清理后再赋给 download。

七、大文件、进度与用户手势

大文件不宜一律转成 Blob

Fetch 后调用 response.blob() 是易于理解的方案，但响应内容需要被读取并用于构造 Blob，文件越大，内存和处理成本越值得关注。浏览器是否能顺利处理，还取决于设备资源、浏览器实现和具体数据，不存在一个适用于所有浏览器的通用安全文件大小上限。

如果文件在服务器上，优先让浏览器直接下载通常更合适。需要断点续传、可靠进度、取消下载或传输大文件时，常见做法是在服务端支持相应能力，并选择适合的下载流程；仅靠创建一个 Blob 链接并不能自动实现断点续传。

用户手势与弹窗限制

下载最好由用户明确操作触发，例如点击“导出”按钮。浏览器会限制脚本在没有用户手势时打开页面或触发某些下载，自动下载也可能被设置拦截。不要把多个下载任务安排为点击后连续触发的弹窗式操作，并假设所有浏览器都会接受。

如果生成内容需要异步请求，用户点击后再启动任务通常更清晰。某些浏览器会对等待异步操作后才执行的下载采取不同策略，因此应在目标浏览器中测试。对于较长任务，可以先显示准备状态，完成后呈现明确的下载按钮。

八、安全与隐私边界

• 下载不等于可信：文件名和扩展名都不能证明文件内容安全。服务端应根据实际内容和业务规则验证上传、导出或转发的数据。
• 不要把秘密写进前端文件：下载内容会到达用户设备。任何页面可读的数据都不能被视作只有服务器可见的秘密。
• 谨慎处理用户数据：导出前明确列出字段，避免意外包含身份信息、令牌、内部备注或超出授权范围的数据。
• 校验文件名和输入：不可信的名称可能包含控制字符或特殊路径字符；输出给 HTML 时还需按 HTML 上下文转义，不能直接拼接进页面标记。
• 不要靠前端鉴权：隐藏按钮、限制下载次数的 JavaScript 或难以猜测的文件名都不能代替服务器权限检查。
• 及时释放临时 URL：由 URL.createObjectURL() 创建的 URL 应在不再需要时撤销，避免长期保留页面资源引用。

九、常见错误排查

点击后没有下载

• 确认事件确实绑定到了按钮，并查看浏览器控制台是否有 JavaScript 异常。
• 检查下载是否由用户操作触发，以及浏览器是否拦截了自动下载。
• 检查目标 URL 是否有效，网络请求是否返回了预期内容。
• 跨域链接的 download 属性可能不起作用；检查服务器是否返回附件响应。

下载的文件是空的或内容不对

• 确认传给 Blob 的字符串或字节数据符合预期，不要把接口错误页面误当成文件。
• Fetch 下载时先检查 response.ok，避免把 401、403 或 500 响应保存为文件。
• 检查 MIME 类型和文件扩展名是否与真实数据相符。
• 检查字符编码、换行符以及 CSV 的字段转义。

中文文件名或内容出现乱码

• 创建文本 Blob 时指定与实际编码一致的类型，例如 text/plain;charset=utf-8。
• 确认数据源本身没有被错误解码。仅修改 Blob 的 MIME 类型无法修复已经损坏的字符。
• 若问题只出现在特定表格软件，针对该软件测试 CSV 编码要求；BOM 可能有帮助，但不是普遍必需。

跨域 Fetch 报错

• 检查开发者工具中的网络请求和响应头，确认服务器是否为页面来源返回了适当的 CORS 配置。
• 如果携带凭据，检查服务端是否允许凭据及对应来源；不能用前端代码消除 CORS 限制。
• 不要为了“修复”问题而将令牌放进公开 URL。URL 可能进入日志、浏览器历史记录或引用信息，认证方案应按服务端设计选择。

大文件下载导致页面卡顿或内存紧张

• 确认是否有必要先用 Fetch 读取整个响应再创建 Blob。
• 如果文件在服务器上，优先改成浏览器直接下载。
• 为文件大小、网络失败和用户取消设计反馈；需要进度或续传时，应同时评估服务端支持。

十、上线前的检查清单

1. 确认文件是由页面生成，还是已经存在于服务器，选择合适方案。
2. 确认实际内容、MIME 类型和扩展名一致。
3. 文件名经过长度和字符清理，且没有将用户输入直接拼接进 HTML。
4. Fetch 请求检查 HTTP 状态，并处理网络错误、鉴权失败和 CORS 配置。
5. 评估文件大小及内存占用；服务器现成的大文件优先考虑直接下载。
6. 下载由用户明确触发，并在目标浏览器和设备上验证。
7. 导出数据只包含当前用户有权获得的字段，不包含密钥等不应下发的信息。
8. Blob URL 使用完毕后及时调用 URL.revokeObjectURL()。

结语

浏览器端下载的核心并不复杂：小型动态内容使用 Blob 和临时链接，服务器文件优先使用普通下载地址，只有确实需要前端处理响应时再考虑 Fetch。真正容易出问题的部分，是跨域和鉴权边界、文件名与编码、用户手势以及大文件的内存成本。先根据文件来源和体量选择流程，再按清单验证响应、权限和资源释放，通常比直接套用一段下载代码更可靠。