Java下载模板文件时中文名乱码如何解决？

Question

在Java Web项目中，通过浏览器下载含有中文名称的模板文件时，常出现文件名乱码问题。尤其是在使用`Content-Disposition`响应头指定文件名时，若未正确处理字符编码，Tomcat、Chrome等环境下中文会显示为问号或乱码字符。该问题根源在于HTTP协议默认不支持UTF-8编码的文件名，需根据RFC 5987标准对文件名进行URL编码，并兼容不同浏览器（如IE、Firefox、Chrome）的解析差异。如何在后端正确设置响应头，实现跨浏览器中文文件名正常显示，是开发中常见的技术难题。

Answer 1

Java Web项目中中文文件名下载乱码问题深度解析与跨浏览器兼容方案

1. 问题背景与现象描述

在Java Web应用开发过程中，文件下载功能是常见需求之一。当模板文件或导出文件的名称包含中文时，通过设置HTTP响应头Content-Disposition: attachment; filename="中文模板.xlsx"直接传递中文字符，往往会导致浏览器显示文件名为乱码（如“????.xlsx”）或编码异常。

该问题广泛存在于使用Tomcat、Jetty等Servlet容器的Spring MVC、Spring Boot、Struts等框架中，尤其在Chrome、Firefox、Edge和IE等主流浏览器上表现不一致，成为困扰开发者多年的经典难题。

2. 根本原因分析

HTTP协议本身对Content-Disposition头部中的filename参数有严格的字符集限制。根据RFC 2616规定，HTTP header字段应仅包含ISO-8859-1字符集内容，而UTF-8中文字符超出此范围，导致解析失败。

RFC 5987（Obsoletes RFC 2231）为此提出了解决方案：允许使用filename*参数进行扩展编码，格式为：

filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%A8%A1%E6%9D%BF.xlsx

然而，并非所有浏览器都支持这一标准，存在显著的兼容性差异：

浏览器	支持 filename*	支持 URL 编码 filename	特殊处理要求
Chrome / Edge	✅	✅	优先识别 filename*
Firefox	✅	✅	支持良好
Safari	⚠️ 部分支持	✅	需测试版本
IE 8-10	❌	✅（需 GBK 编码）	必须用 urlEncode(gbk)
IE 11+	✅	✅	支持 UTF-8*

3. 解决策略设计原则

• 遵循RFC 5987标准，优先提供filename*参数
• 保留传统filename作为降级 fallback
• 根据User-Agent判断客户端类型，动态选择编码方式
• 对IE系列浏览器单独处理，采用GB2312/GBK编码
• 确保URL编码过程正确处理空格、引号等特殊字符

4. Java后端实现代码示例

以下是一个通用工具方法，用于生成兼容多浏览器的Content-Disposition头：

public class DownloadUtils {

    public static String buildContentDisposition(HttpServletRequest request, String filename) {
        String userAgent = request.getHeader("User-Agent");
        String encodedFilename;

        if (userAgent != null && userAgent.contains("MSIE") || userAgent.contains("Trident")) {
            // IE 浏览器（IE 8-11）
            try {
                encodedFilename = URLEncoder.encode(filename, "GBK").replaceAll("\\+", "%20");
            } catch (UnsupportedEncodingException e) {
                throw new RuntimeException(e);
            }
            return "attachment; filename=\"" + encodedFilename + "\"";
        } else {
            // Chrome, Firefox, Safari, Edge
            try {
                String encoded = URLEncoder.encode(filename, "UTF-8")
                    .replaceAll("\\+", "%20") // 保持空格编码为%20
                    .replaceAll("'", "%27"); // 处理单引号
                return "attachment; filename=\"" + filename + "\"; filename*=UTF-8''" + encoded;
            } catch (UnsupportedEncodingException e) {
                throw new RuntimeException(e);
            }
        }
    }
}

5. Spring Boot控制器调用示例

结合Spring框架的实际使用场景：

@GetMapping("/download/template")
public ResponseEntity<Resource> downloadTemplate(HttpServletRequest request) throws IOException {
    Resource resource = new ClassPathResource("templates/用户数据模板.xlsx");
    String originalName = "用户数据模板.xlsx";

    String disposition = DownloadUtils.buildContentDisposition(request, originalName);

    return ResponseEntity.ok()
        .header(HttpHeaders.CONTENT_DISPOSITION, disposition)
        .header(HttpHeaders.CONTENT_TYPE, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
        .body(resource);
}

6. 浏览器兼容性处理流程图

graph TD
            A[获取User-Agent] -- 包含 MSIE 或 Trident --> B[使用GBK编码]
            A -- 其他浏览器 --> C[使用UTF-8编码]
            B --> D[生成传统filename=xxx]
            C --> E[生成filename*参数]
            C --> F[同时保留filename作为fallback]
            D --> G[返回响应头]
            E & F --> G

7. Tomcat配置注意事项

尽管问题主要出在响应头构造，但Tomcat的默认URI编码也可能影响整体字符处理一致性。建议在server.xml中显式设置：

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           URIEncoding="UTF-8" />

此外，若前端通过URL传递文件名参数，也需确保Spring的StringHttpMessageConverter使用UTF-8编码。

8. 安全性与边界情况考虑

实际生产环境中还需注意：

• 防止文件名注入攻击，应对输入做白名单过滤
• 避免过长文件名导致头部溢出（建议截断至255字符以内）
• 特殊符号如双引号、分号需转义处理
• 移动端浏览器（如iOS微信内置浏览器）可能存在独立解析逻辑
• CDN或反向代理可能修改或缓存响应头，需关闭相关缓存策略

9. 自动化测试建议

为保障跨浏览器兼容性，推荐建立自动化测试用例：

测试项	预期结果	测试工具
Chrome 下载中文名	正常显示“模板.xlsx”	Selenium + ChromeDriver
Firefox 中文文件名	无乱码	Mocha + Puppeteer
IE11 兼容模式	正确解码GBK编码	Protractor
移动端 Safari	文件保存名称正确	Appium
API 单元测试	不同UA生成正确Header	JUnit5 + MockMVC