JS下载流文件时中文乱码如何解决？

Question

在使用JavaScript通过Blob和a标签下载服务端返回的流文件时，若文件名包含中文，部分浏览器（如Chrome）会出现文件名乱码或编码异常的问题。根本原因在于Content-Disposition响应头中的中文文件名未正确编码，而JS直接读取时未进行相应解码处理。常见表现为下载文件名为“.xlsx”等乱码字符。如何在前端正确解析响应头中的filename*字段，结合URL decode和字符集处理，确保中文文件名正常显示，是开发者常遇到的技术难题。

Answer 1

1. 问题背景与现象描述

在现代Web应用中，前端通过JavaScript使用Blob对象和a标签实现流式文件下载已成为标准做法。然而，当服务端返回的文件名包含中文字符时，部分浏览器（如Chrome、Edge）会出现文件名乱码或仅显示扩展名（如“.xlsx”），严重影响用户体验。

该问题的核心在于HTTP响应头Content-Disposition中的文件名编码未被前端正确解析。尤其当服务端使用filename*字段指定RFC 5987格式的编码文件名时，若前端未进行URL decode与字符集处理，浏览器无法还原原始中文名称。

典型响应头示例如下：

Content-Disposition: attachment; filename="filename.xlsx"; filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%96%87%E4%BB%B6.xlsx

• Chrome优先读取filename*，但需正确解码
• 旧版IE/Firefox可能仅支持filename
• 前端直接从Header提取字符串而不解码会导致乱码

2. 技术原理分析：Content-Disposition与编码规范

RFC 6266定义了Content-Disposition头用于指示资源的呈现方式（inline/attachment）。其中文件名可通过两个字段提供：

字段名	标准	编码要求	浏览器兼容性
filename	RFC 2616	仅允许ISO-8859-1，中文需转义为?编码	广泛支持，但中文易乱码
filename*	RFC 5987	支持UTF-8编码，格式：''	现代浏览器支持良好

filename* 的标准格式为：

filename*=utf-8''%E6%96%87%E4%BB%B6%E5%90%8D.xlsx

其中：

• utf-8 表示字符集
• '' 是分隔符（注意双单引号）
• %E6%96%87%E4%BB%B6%E5%90%8D 是URL编码后的UTF-8字节序列

3. 前端解析流程设计

为确保跨浏览器兼容性和中文文件名正确显示，前端需按以下优先级解析文件名：

1. 优先尝试解析 filename* 字段
2. 若不存在，则回退到 filename 字段
3. 对获取的编码值进行URL decode与字符集还原
4. 处理特殊字符与引号包裹情况
5. 最终用于Blob下载的a标签download属性

流程图如下：

graph TD
    A[获取Content-Disposition Header] --> B{包含filename*?}
    B -- 是 --> C[解析charset与encoded-value]
    C --> D[decodeURIComponent(encoded-value)]
    D --> E[构造Blob URL并设置a.download]
    B -- 否 --> F{包含filename?}
    F -- 是 --> G[去除引号并解码]
    G --> E
    F -- 否 --> H[使用默认文件名]
    H --> E

4. 核心代码实现方案

以下是完整的JavaScript函数，用于从响应头中安全提取并解码文件名：

function getFilenameFromHeader(contentDisposition) {
  if (!contentDisposition) return null;

  // 匹配 filename* (RFC 5987)
  const filenameStarMatch = contentDisposition.match(/filename\*=([^;]+)/i);
  if (filenameStarMatch) {
    const encodedPart = filenameStarMatch[1].trim();
    // 格式: charset''value
    const matches = encodedPart.match(/^(?:UTF-8|utf-8)\s*''(.+)$/);
    if (matches && matches[1]) {
      try {
        return decodeURIComponent(matches[1]);
      } catch (e) {
        console.warn('Failed to decode filename*', e);
        return null;
      }
    }
  }

  // 回退到 filename (RFC 2616)
  const filenameMatch = contentDisposition.match(/filename=([^;]+)/i);
  if (filenameMatch) {
    let filename = filenameMatch[1].trim();
    // 移除引号
    if (filename.startsWith('"') && filename.endsWith('"')) {
      filename = filename.slice(1, -1);
    }
    return filename;
  }

  return null;
}

// 使用示例
fetch('/api/export')
  .then(response => {
    const contentDisp = response.headers.get('Content-Disposition');
    const blob = await response.blob();
    const filename = getFilenameFromHeader(contentDisp) || 'download.xlsx';

    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = filename;
    document.body.appendChild(a);
    a.click();
    window.URL.revokeObjectURL(url);
    a.remove();
  });

5. 浏览器兼容性与边界情况处理

尽管主流现代浏览器支持filename*，但仍需考虑以下边界场景：

• 服务端错误地将UTF-8编码内容放入filename字段
• 某些代理或CDN修改了原始响应头
• IE11不完全支持filename*，需服务端降级兼容
• 移动端Safari对download属性支持有限，可能忽略文件名
• 部分系统文件系统限制文件名长度或特殊字符

增强版解析可加入字符集检测与fallback机制：

function robustFilenameParse(header) {
  // 支持gbk等其他编码（较少见）
  const charsetMatch = header.match(/filename\*=([^\s'';]+)''(.+)/i);
  if (charsetMatch) {
    const [, charset, encoded] = charsetMatch;
    if (charset.toLowerCase() === 'utf-8') {
      return decodeURIComponent(encoded);
    }
    // 可结合TextDecoder处理GBK等（需额外逻辑）
  }
  // ...其余同上
}

6. 最佳实践建议

为从根本上避免此类问题，建议前后端协同遵循以下最佳实践：

角色	建议措施
后端开发	始终同时设置filename和filename*，确保向下兼容
前端开发	优先解析filename*，失败后回退，并做好异常捕获
测试团队	覆盖多语言文件名、特殊符号、长文件名等测试用例
运维/网关	确保反向代理不篡改Content-Disposition头

此外，可在前端封装通用的downloadBlob工具函数，统一处理各类文件下载场景，提升代码复用性与健壮性。