英文Mac环境下Safari下载日文字符文件名乱码问题求助

问题根源 #

1. 直接用ISO-8859-1编码日文文件名：日文不在ISO-8859-1字符集范围内，编码后字符被错误转换，导致Safari显示乱码。
2. 直接用UTF-8编码设置响应头：Java传统setHeader方法默认以ISO-8859-1序列化头内容，UTF-8字符超出0-255范围时会抛出IllegalArgumentException。

解决方案：兼容RFC 5987标准的双参数响应头 #

采用filename（兼容旧浏览器）+filename*=UTF-8''编码文件名（Safari等现代浏览器优先读取）的组合方式，既避免编码异常，又让Safari正确识别日文文件名。

Java代码实现

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

// 原始日文文件名
String originalFileName = "Report バリュードライバーステータスダッシュボード1.xlsx";

// 按RFC 5987标准编码UTF-8文件名，替换+为%20（符合URL空格编码规范）
String encodedUtf8FileName = URLEncoder.encode(originalFileName, StandardCharsets.UTF_8.name())
        .replace("+", "%20");

// 构造兼容双参数的Content-Disposition头
// 旧filename参数用ISO-8859-1转码（作为降级兼容，不影响Safari读取filename*）
String fallbackFileName = new String(originalFileName.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1);
String contentDisposition = String.format(
        "attachment; filename=\"%s\"; filename*=UTF-8''%s",
        fallbackFileName,
        encodedUtf8FileName
);

// 设置响应头
response.setHeader("Content-Disposition", contentDisposition);

关键说明 #

• filename*=UTF-8''编码值是RFC 5987定义的UTF-8文件名标准格式，Safari会优先解析该参数，正确显示日文。
• 保留filename参数是为了兼容不支持RFC 5987的旧浏览器，即便该参数显示乱码，不影响下载功能正常运行。
• 替换+为%20是因为URLEncoder会把空格编码为+，但URL标准中空格应表示为%20，避免文件名空格显示异常。

内容的提问来源于stack exchange，提问作者Karl