前端下载JSON文件时中文乱码如何解决？

Question

前端通过 `a.download` 或 `Blob` 下载 JSON 文件时，若内容含中文却显示乱码（如“”或编码异常），主因是未正确指定 UTF-8 编码。常见错误包括：① 创建 Blob 时未显式传入 `{type: 'application/json;charset=utf-8'}`；② 使用 `encodeURIComponent` 错误转义 JSON 字符串导致二次编码；③ 在 IE/Edge 旧版中未用 `Blob` 而直接 `data:text/json,` URL，丢失 charset 声明。解决方案：统一使用 `new Blob([JSON.stringify(data, null, 2)], {type: 'application/json;charset=utf-8'})`，再通过 `URL.createObjectURL()` 触发下载；对兼容性要求高的场景，可追加 BOM 头（`\uFEFF`）确保编辑器识别 UTF-8。切忌用 `encodeURI` 处理整个 JSON 字符串——它破坏原始结构且不可逆。

Answer 1

```html

一、现象层：乱码的直观表现与触发场景

当用户点击下载按钮，生成的 .json 文件在 VS Code、Notepad++ 或 Windows 记事本中打开时，中文字段（如 "姓名": "张三"）显示为方块、问号或 Mojibake（如 "姓名": "张三"）。该问题高频复现于 Vue/React 项目导出配置、后台管理系统的日志导出、低代码平台的数据快照下载等场景。

二、协议层：HTTP 响应头与 MIME 类型的隐式契约

浏览器依据 Content-Type 响应头（服务端）或 Blob 的 type 选项（前端）推断字符编码。若未显式声明 charset=utf-8，Chrome/Firefox 默认按 UTF-8 解析，但 Windows 记事本、Excel、部分国产编辑器会回退至系统默认编码（如 GBK），导致解码错位。关键事实：MIME 类型中的 charset 参数是前端可控的唯一编码声明入口。

三、技术根因分析：三大典型错误模式

错误类型	错误代码示例	后果
① Blob type 缺失 charset	new Blob([jsonStr])	浏览器无编码提示，依赖 UA 猜测
② 误用 encodeURIComponent	encodeURIComponent(JSON.stringify(obj))	双引号、斜杠被转义，JSON 结构破坏，解析失败
③ data: URL 无 charset 支持	href="data:text/json;charset=utf-8,..."	IE/Edge Legacy 完全忽略 charset 参数，强制使用系统编码

四、标准解决方案：现代浏览器兼容性实践

以下为生产环境验证通过的核心逻辑（含 BOM 防御）：

function downloadJSON(data, filename = 'data.json') {
  const jsonStr = JSON.stringify(data, null, 2);
  // ✅ 强制 UTF-8 + BOM（\uFEFF）确保 Windows 编辑器正确识别
  const blob = new Blob(['\uFEFF' + jsonStr], {
    type: 'application/json;charset=utf-8'
  });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url); // 内存清理
}

五、兼容性增强：针对 IE11/Edge Legacy 的降级路径

当需支持 IE11 时，不可依赖 Blob（其 type 在 IE 中被忽略），而应采用 msSaveOrOpenBlob API，并配合 TextEncoder 手动构造 UTF-8 字节流（polyfill 可用 text-encoding 库）：

if (window.navigator.msSaveOrOpenBlob) {
  const encoder = new TextEncoder(); // UTF-8 编码器
  const uint8Array = encoder.encode('\uFEFF' + jsonStr);
  const blob = new Blob([uint8Array], { type: 'application/json' });
  window.navigator.msSaveOrOpenBlob(blob, filename);
} else {
  // 使用标准 Blob 流程（见上节）
}

六、深度避坑指南：为什么不能用 encodeURI/encodeURIComponent？

二者设计目标是 URI 组件编码，非文本转义：
• encodeURI('{ "name": "张三" }') → %7B%20%22name%22%3A%20%22%E5%BC%A0%E4%B8%89%22%20%7D
• 此结果已将双引号、空格、花括号全部转义，**不再是合法 JSON 字符串**；
• 若再传入 new Blob([...])，写入文件后内容为 URL 编码串，而非原始 JSON —— 这是不可逆的语义破坏，非编码问题，而是数据污染。

七、验证闭环：从生成到打开的全链路检测

graph LR
  A[前端调用 downloadJSON] --> B[生成含 BOM 的 UTF-8 字节数组]
  B --> C[Browser 创建 Blob 并设置 type=application/json;charset=utf-8]
  C --> D[触发 a.download 下载]
  D --> E[文件系统保存 .json]
  E --> F{打开方式}
  F -->|VS Code/IDE| G[自动识别 BOM → UTF-8]
  F -->|Windows 记事本| H[检测 BOM → 显示为 UTF-8]
  F -->|旧版 Notepad| I[若无 BOM → 提示编码选择]

八、工程化建议：封装为可复用 Hook / 工具函数

在大型项目中，应将该逻辑抽象为：

• useDownloadJSON()（React Hook），支持 abortController 和 loading 状态
• downloadAsJSON(data, options)（通用工具），options 支持 bom: true/false、indent: 2、filenameTemplate
• CI 阶段加入字节流校验：断言生成文件前 3 字节为 EF BB BF（UTF-8 BOM）

九、延伸思考：服务端协同优化空间

虽然本问题聚焦前端，但最佳实践需前后端对齐：
• 后端 API 返回 Content-Type: application/json; charset=utf-8（Spring Boot 默认已满足）；
• 若前端需“二次下载”服务端 JSON（如 fetch('/api/config').then(r => r.json()).then(downloadJSON)），则服务端响应头中的 charset 对前端 Blob 构造无影响——因为 response.json() 已完成 UTF-8 解码，前端拿到的是 JS 对象，JSON.stringify 输出天然 UTF-8；
• 真正风险点在于：前端自行拼接 JSON 字符串（如表单导出）且未管控编码。

十、终极检查清单（Checklist）

1. ✅ 是否在 Blob 构造时显式传入 { type: 'application/json;charset=utf-8' }？
2. ✅ 是否在 JSON.stringify 结果前拼接了 '\uFEFF'？
3. ✅ 是否完全规避了 encodeURI/encodeURIComponent 对整个 JSON 字符串的操作？
4. ✅ 是否对 IE11 做了 navigator.msSaveOrOpenBlob 降级？
5. ✅ 是否在测试环节使用 Windows 记事本 + VS Code 双环境验证中文显示？
6. ✅ 是否在 CI 中校验生成文件的 Magic Number（BOM）？
7. ✅ 是否将该逻辑封装为团队共享的 SDK 模块，避免重复踩坑？

```