Spring Boot生成大CSV文件丢失响应头导致无法正常下载的问题

这个问题我之前做大数据量CSV导出的时候也踩过坑，核心原因是响应头设置时机太晚，加上大数据量触发了HTTP分块传输（Transfer-Encoding: chunked），导致浏览器接收不到关键的Content-Type和Content-Disposition头，没法识别这是一个下载文件。

问题根源 #

HTTP协议要求响应头必须在响应体之前发送。当你先调用btcsv.write()或者response.getWriter()写入内容时，服务器会因为数据量较大直接触发缓冲区刷新，开始以分块的形式发送响应体。这时候再去设置响应头，这些头信息已经无法被添加到响应的开头，自然会被浏览器忽略，只能把接收到的文本直接展示出来。

解决方案 #

只需要调整代码的执行顺序，先设置响应头，再进行任何写入操作，同时优化资源管理和缓冲区配置，就能解决问题：

1. 提前设置响应头

把setContentType和setHeader移到try块的最开头，确保在获取Writer或者写入任何内容之前完成头信息的设置。

2. 使用try-with-resources自动管理资源

避免手动关闭Writer时可能出现的异常，让JVM自动处理资源释放。

3. 可选：设置响应缓冲区大小

如果数据量特别大，可以设置一个合适的缓冲区大小，避免过早触发分块传输（不过即使触发分块，只要头信息已经提前发送，浏览器依然能识别下载）。

修改后的完整代码 #

@GetMapping("/csv")
public void csvEmissions(HttpServletResponse response) {
    try {
        // 第一步：先设置响应头，在任何写入操作之前
        response.setContentType("text/csv");
        response.setHeader("Content-Disposition", "attachment; filename=file.csv");
        // 可选：设置缓冲区大小，根据数据量调整
        response.setBufferSize(1024 * 1024); // 1MB缓冲区

        ColumnPositionMappingStrategy<CsvRow> mapStrategy = new ColumnPositionMappingStrategy<>();
        mapStrategy.setType(CsvRow.class);
        String[] columns = new String[]{ "col1", "col2" };
        mapStrategy.setColumnMapping(columns);

        // 使用try-with-resources自动关闭CSVWriter
        try (CSVWriter csvWriter = new CSVWriter(response.getWriter())) {
            StatefulBeanToCsv<CsvRow> btcsv = new StatefulBeanToCsvBuilder<CsvRow>(response.getWriter())
                    .withMappingStrategy(mapStrategy)
                    .withSeparator(',')
                    .build();
            btcsv.write(csvrows());
        }
    } catch (IOException | CsvRequiredFieldEmptyException | CsvDataTypeMismatchException e) {
        // 异常处理：设置错误状态码，避免客户端等待超时
        response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
        throw new RuntimeException("导出CSV失败：" + e.getMessage(), e);
    }
}

额外注意事项 #

• 如果文件名包含中文，需要按照RFC 5987标准编码，避免乱码：

  String encodedFilename = URLEncoder.encode("导出数据.csv", StandardCharsets.UTF_8).replace("+", "%20");
  response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + encodedFilename);
  

• 确保csvrows()方法不会一次性加载所有数据到内存（比如用分页查询或者流式返回），避免OOM问题，这也是大数据量导出时的常见坑。

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