SpringBoot导出文件时中文名乱码或下载失败如何解决？

Question

在Spring Boot中导出文件时，若响应头 `Content-Disposition` 中的中文文件名未正确编码，浏览器（尤其是Chrome、Edge）会解析失败，导致下载文件名乱码（如显示为“%E6%96%87%E4%BB%B6.xlsx”）或直接拒绝下载（报错“Failed - No file”）。根本原因在于HTTP规范不支持UTF-8明文文件名，需按RFC 5987/6266标准进行编码：对IE/Edge使用`filename*=`（UTF-8 + percent-encoding），对旧版Firefox可兼容`filename=`（ISO-8859-1转义）。常见错误包括仅设置`filename=`且未转码、忽略浏览器兼容性、未设置`Content-Type`或未禁用响应体缓冲。此外，Tomcat 9+默认拒绝含非ASCII字符的`filename`字段，加剧问题。解决需统一采用`filename*=UTF-8''{encoded}`格式，并配合`URLEncoder.encode(name, "UTF-8")`处理，同时确保`response.setContentType()`与`response.setCharacterEncoding("UTF-8")`协同生效。

Answer 1

```html

一、现象层：浏览器下载异常的典型表现

• Chrome/Edge 显示下载文件名为 %E6%96%87%E4%BB%B6.xlsx（URL 编码未被识别）
• Edge 报错 “Failed - No file”，HTTP 响应中断且无文件流返回
• Firefox 旧版本（<60）显示乱码如 ?????.xlsx，新版本可正常但兼容性不可控
• Safari 在 macOS 上偶现截断（如仅显示前 8 字符）、或自动追加 .download 后缀

二、协议层：RFC 5987/6266 的强制约束与历史演进

HTTP/1.1 规范（RFC 2616）明确禁止在 Content-Disposition: filename="..." 中使用非 ISO-8859-1 字符；而 RFC 6266（2011）和 RFC 5987（2010）引入 filename* 扩展字段，定义：

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

字段	标准支持	编码要求	典型浏览器
filename	RFC 2616	ISO-8859-1 + \\ 转义	IE ≤10, Firefox ≤33
filename*	RFC 5987/6266	UTF-8 + percent-encoding（单引号分隔）	Chrome ≥15, Edge ≥12, Firefox ≥34, Safari ≥11

三、容器层：Tomcat 9+ 的安全强化与隐式拦截

Tomcat 9.0.10+ 默认启用 relaxedPathChars 和 relaxedQueryChars 白名单机制，且对响应头中含非 ASCII 的 filename= 字段直接拒绝写入（日志可见 Illegal character in header value）。此行为由 org.apache.catalina.connector.Response 的 isValidHeaderValue() 方法触发，本质是防御 HTTP Header Injection。

四、代码层：Spring Boot 中的正确实现路径

以下为生产级兼容方案（支持 Chrome/Edge/Firefox/Safari）：

@GetMapping("/export")
public void exportExcel(HttpServletResponse response) throws IOException {
    String fileName = "销售报表-2024Q3.xlsx";
    String encodedName = URLEncoder.encode(fileName, StandardCharsets.UTF_8)
        .replaceAll("\\+", "%20"); // 修复空格编码为+的问题
    
    response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
    response.setCharacterEncoding("UTF-8");
    response.setHeader("Content-Disposition",
        "attachment; " +
        "filename=\"" + escapeForAsciiFilename(fileName) + "\"; " +
        "filename*=UTF-8''" + encodedName);
    response.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    response.setHeader("Pragma", "no-cache");
    response.setDateHeader("Expires", 0);
    
    try (OutputStream os = response.getOutputStream();
         Workbook workbook = new XSSFWorkbook()) {
        // ... 构建 Excel 内容
        workbook.write(os);
    }
}

private String escapeForAsciiFilename(String name) {
    return name.chars()
        .mapToObj(c -> c <= 0x7F ? String.valueOf((char) c) : "_")
        .collect(Collectors.joining());
}

五、验证层：多端实测兼容性矩阵

graph LR A[Spring Boot Controller] --> B{设置 Content-Type} A --> C{设置 Content-Disposition} C --> D[filename=xxx.xlsx
ASCII only] C --> E[filename*=UTF-8''xxx.xlsx] D --> F[IE11 / Legacy FF] E --> G[Chrome 120+ / Edge 120+ / FF 115+ / Safari 17+] B --> H[避免 MIME sniffing] style F fill:#ffebee,stroke:#f44336 style G fill:#e8f5e9,stroke:#4caf50

六、工程实践：全局统一处理的最佳模式

• 封装 ResponseDispositionBuilder 工具类，内置浏览器 UA 检测（可选）与 fallback 策略
• 在 Spring WebMvcConfigurer 中注册 HandlerInterceptor，对所有 @ResponseBody 导出接口自动注入标准化头
• 禁用 Tomcat 默认响应缓冲：在 application.properties 中配置 server.tomcat.max-http-header-size=16384 并确保 response.flushBuffer() 显式调用
• 单元测试覆盖：MockMvc + MockHttpServletResponse 断言 getHeader("Content-Disposition") 是否含 filename*=

```