使用Content-Disposition时非ASCII文件名下载异常问题排查

核心问题点 #

1. 编码标识不符合RFC 6266规范
   RFC 6266明确要求UTF-8编码的标识为UTF-8（带连字符），但你通过Spring ContentDisposition生成的头中使用了简写UTF8，部分现代浏览器对该简写兼容性不足，无法正确识别编码规则，导致文件名解析失败。

2. 头末尾存在多余分号
   你生成的Content-Disposition头末尾多了一个;，这违反了HTTP头的语法规范，会干扰浏览器的解析逻辑，出现类似attachment被截断为ttachment的异常。

解决方法 #

1. 明确指定UTF-8编码 #

使用ContentDisposition.Builder的重载方法，显式传入StandardCharsets.UTF_8指定编码，确保生成符合RFC要求的UTF-8标识：

import org.springframework.http.ContentDisposition;
import java.nio.charset.StandardCharsets;

// 构建合规的Content-Disposition
ContentDisposition disposition = ContentDisposition.attachment()
    .filename("Результаты обновления учебных данных.docx", StandardCharsets.UTF_8)
    .build();

2. 避免手动拼接多余字符 #

不要手动给生成的头字符串添加分号，直接通过Spring的HttpHeaders方法设置头：

HttpHeaders headers = new HttpHeaders();
headers.setContentDisposition(disposition);

验证正确的头格式 #

生成的Content-Disposition头应如下，无多余分号且编码为UTF-8：

attachment; filename*=UTF-8''%D0%A0%D0%B5%D0%B7%D1%83%D0%BB%D1%8C%D1%82%D0%B0%D1%82%D1%8B_%D0%BE%D0%B1%D0%BD%D0%BE%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D1%83%D1%87%D0%B5%D0%B1%D0%BD%D1%8B%D1%85_%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85.docx

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