Spring Boot REST文件下载中文名乱码的Header正确写法 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

Spring Boot REST 文件下载中文名乱码终极解决方案

大家好，今天我们要深入探讨一个在Spring Boot REST API开发中常见却令人头疼的问题：文件下载时，中文文件名出现乱码。我们将深入分析乱码产生的原因，并提供一系列经过验证的解决方案，确保你的文件下载功能能够完美支持中文文件名。

乱码问题的根源

文件下载的乱码问题，本质上是编码不一致导致的。从服务器到客户端，涉及多个环节，每个环节都可能使用不同的编码方式。如果这些环节的编码方式不一致，就会导致乱码。

具体来说，以下几个环节是关键：

服务端编码: Spring Boot应用本身使用的编码，通常在application.properties或application.yml中设置，默认是UTF-8。
响应头编码: Content-Disposition 响应头用于指定文件名。如果文件名中包含中文，就需要对文件名进行编码，以便浏览器能够正确解析。
浏览器编码: 浏览器接收到响应后，会根据响应头的信息来解析文件名。不同的浏览器对编码的支持程度不同。
操作系统编码: 最终，文件保存到操作系统时，操作系统也需要支持相应的编码。

如果以上任何一个环节的编码方式不一致，都可能导致乱码。例如，服务端使用UTF-8编码，但响应头没有正确设置，或者浏览器不支持UTF-8编码，都会导致乱码。

分析各种场景及解决方案

接下来，我们将针对不同的浏览器和操作系统，提供详细的解决方案。

1. Content-Disposition 响应头详解

Content-Disposition 响应头是解决中文文件名乱码问题的核心。它的作用是告诉浏览器如何处理接收到的文件，包括是直接显示（inline）还是下载（attachment），以及文件名。

Content-Disposition 的语法如下：

Content-Disposition: attachment; filename="filename.ext"; filename*=UTF-8''filename.ext

其中：

attachment：表示以附件形式下载。
filename="filename.ext"：指定文件名，但存在编码问题，不同浏览器处理方式不同。
filename*=UTF-8''filename.ext：使用 RFC 5987 编码，可以解决文件名编码问题，但并非所有浏览器都支持。

为了兼容不同的浏览器，我们需要同时使用 filename 和 filename* 两种方式。

2. 解决不同浏览器的乱码问题

不同浏览器对 Content-Disposition 响应头的处理方式不同，我们需要针对不同的浏览器进行处理。

浏览器	`filename` 处理方式	`filename*` 处理方式	解决方案
Chrome	支持 UTF-8 编码，但可能乱码	支持 UTF-8 编码，推荐使用	同时设置 `filename` 和 `filename`，`filename` 使用 `URLEncoder.encode()` 编码，`filename` 使用 UTF-8 编码。
Firefox	支持 UTF-8 编码，但可能乱码	支持 UTF-8 编码，推荐使用	同时设置 `filename` 和 `filename`，`filename` 使用 `URLEncoder.encode()` 编码，`filename` 使用 UTF-8 编码。
Safari	对 `filename` 支持较差，可能乱码	支持 UTF-8 编码，推荐使用	同时设置 `filename` 和 `filename`，`filename` 使用 `URLEncoder.encode()` 编码，`filename` 使用 UTF-8 编码。
Internet Explorer	不支持 UTF-8 编码，乱码几率高	不支持，会忽略	仅设置 `filename`，并使用 `URLEncoder.encode()` 将文件名编码为 `application/x-www-form-urlencoded` 格式。由于IE对中文支持较差，即使这样处理，仍然可能出现乱码。建议尽量避免在老版本IE中使用文件下载功能，或者提示用户更换浏览器。
Edge	支持 UTF-8 编码，但可能乱码	支持 UTF-8 编码，推荐使用	同时设置 `filename` 和 `filename`，`filename` 使用 `URLEncoder.encode()` 编码，`filename` 使用 UTF-8 编码。

3. Spring Boot 代码示例

以下是一个 Spring Boot REST API 的代码示例，演示如何正确设置 Content-Disposition 响应头，以解决中文文件名乱码问题。

import org.springframework.core.io.InputStreamResource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.io.ByteArrayInputStream;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

@RestController
public class FileDownloadController {

    @GetMapping("/download")
    public ResponseEntity<InputStreamResource> downloadFile() throws UnsupportedEncodingException {
        String filename = "中文文件名.txt";
        String content = "这是文件的内容";

        // 将内容转换为字节数组
        byte[] contentBytes = content.getBytes(StandardCharsets.UTF_8);
        ByteArrayInputStream inputStream = new ByteArrayInputStream(contentBytes);

        // 设置 Content-Disposition 响应头
        HttpHeaders headers = new HttpHeaders();
        String encodedFilename = URLEncoder.encode(filename, StandardCharsets.UTF_8.toString());
        String filenameUTF8 = new String(filename.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1); // RFC 2231

        headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename="" + filenameUTF8 + ""; filename*=UTF-8''" + encodedFilename);
        headers.add(HttpHeaders.CONTENT_TYPE, MediaType.TEXT_PLAIN_VALUE);
        headers.add(HttpHeaders.CONTENT_LENGTH, String.valueOf(contentBytes.length));

        return ResponseEntity
                .ok()
                .headers(headers)
                .body(new InputStreamResource(inputStream));
    }
}

代码解释：

filename： 定义文件名，包含中文。
URLEncoder.encode(filename, StandardCharsets.UTF_8.toString())： 使用 URLEncoder.encode() 对文件名进行编码，将其转换为 application/x-www-form-urlencoded 格式。
new String(filename.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1)： 这是一个兼容性处理，将UTF-8编码的文件名转换为ISO-8859-1编码。虽然ISO-8859-1不支持中文，但它可以将UTF-8字节转换为对应的ISO-8859-1字符，从而避免一些浏览器的解析错误。
*`headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename="" + encodedFilename + ""; filename=UTF-8”" + encodedFilename);：** 设置Content-Disposition响应头，同时包含filename和filename*` 两种方式。
headers.add(HttpHeaders.CONTENT_TYPE, MediaType.TEXT_PLAIN_VALUE);： 设置 Content-Type 响应头，指定文件类型。
ResponseEntity.ok().headers(headers).body(new InputStreamResource(inputStream));： 构建 ResponseEntity 对象，包含响应头和文件内容。

注意事项：

确保 Spring Boot 应用的编码设置为 UTF-8。
根据实际情况调整 Content-Type 响应头。
在测试时，使用不同的浏览器进行测试，确保兼容性。
filename*=UTF-8'' 必须紧跟在 filename 之后，否则可能导致一些浏览器解析错误。
filename 的值应该使用 URLEncoder.encode() 进行编码，而不是直接使用原始文件名。

4. 针对IE浏览器的特殊处理

由于 Internet Explorer 对 UTF-8 编码的支持较差，我们需要进行特殊处理。

仅设置 filename： 避免设置 filename*，因为 IE 不支持。
使用 URLEncoder.encode() 编码： 将文件名编码为 application/x-www-form-urlencoded 格式。

即使这样处理，仍然可能出现乱码。建议尽量避免在老版本 IE 中使用文件下载功能，或者提示用户更换浏览器。

5. 完整兼容的示例代码

下面的代码示例考虑了更多兼容性问题，特别是针对IE浏览器的兼容性。

import org.springframework.core.io.InputStreamResource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;
import java.io.ByteArrayInputStream;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

@RestController
public class FileDownloadController {

    @GetMapping("/download")
    public ResponseEntity<InputStreamResource> downloadFile(HttpServletRequest request) throws UnsupportedEncodingException {
        String filename = "中文文件名.txt";
        String content = "这是文件的内容";

        // 将内容转换为字节数组
        byte[] contentBytes = content.getBytes(StandardCharsets.UTF_8);
        ByteArrayInputStream inputStream = new ByteArrayInputStream(contentBytes);

        // 获取 User-Agent
        String userAgent = request.getHeader("User-Agent");

        // 设置 Content-Disposition 响应头
        HttpHeaders headers = new HttpHeaders();
        String encodedFilename = URLEncoder.encode(filename, StandardCharsets.UTF_8.toString());
        String filenameUTF8 = new String(filename.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1);

        String contentDisposition;
        if (userAgent != null && userAgent.contains("MSIE") || (userAgent != null && userAgent.contains("Trident"))) {
            // IE 浏览器
            contentDisposition = "attachment; filename="" + encodedFilename + """;
        } else {
            // 其他浏览器
            contentDisposition = "attachment; filename="" + filenameUTF8 + ""; filename*=UTF-8''" + encodedFilename;
        }

        headers.add(HttpHeaders.CONTENT_DISPOSITION, contentDisposition);
        headers.add(HttpHeaders.CONTENT_TYPE, MediaType.TEXT_PLAIN_VALUE);
        headers.add(HttpHeaders.CONTENT_LENGTH, String.valueOf(contentBytes.length));

        return ResponseEntity
                .ok()
                .headers(headers)
                .body(new InputStreamResource(inputStream));
    }
}

代码解释：

request.getHeader("User-Agent")： 获取 User-Agent 请求头，用于判断浏览器类型。
userAgent.contains("MSIE") || (userAgent != null && userAgent.contains("Trident"))： 判断是否为 IE 浏览器。
针对 IE 浏览器： 仅设置 filename，并使用 URLEncoder.encode() 进行编码。
针对其他浏览器： 同时设置 filename 和 filename*，filename 使用 ISO-8859-1 编码，filename* 使用 UTF-8 编码。

6. 其他可能导致乱码的情况

除了 Content-Disposition 响应头之外，还有一些其他因素可能导致乱码：

文件内容编码： 确保文件内容的编码与响应头的编码一致。例如，如果文件内容使用 UTF-8 编码，则响应头的 Content-Type 应该设置为 text/plain; charset=UTF-8。
服务器配置： 检查服务器的默认编码是否为 UTF-8。如果不是，需要修改服务器配置。
操作系统编码： 确保操作系统的默认编码支持中文。

总结与最佳实践

解决Spring Boot REST API文件下载中文名乱码问题，关键在于正确设置Content-Disposition响应头，并根据不同的浏览器进行兼容性处理。

*优先使用`filename：** 对于支持 RFC 5987 编码的浏览器，优先使用filename*=UTF-8”filename.ext` 方式。
兼顾filename： 同时设置 filename，并使用 URLEncoder.encode() 进行编码，以兼容老版本的浏览器。
针对IE浏览器特殊处理： 仅设置 filename，并使用 URLEncoder.encode() 进行编码。
统一编码： 确保服务端、响应头和浏览器使用的编码一致。
测试： 使用不同的浏览器进行测试，确保兼容性。

通过以上方法，我们可以有效地解决 Spring Boot REST API 文件下载中文名乱码问题，提升用户体验。