Spring Boot 后端生成 PDF 并实现浏览器自动下载的完整解决方案-java教程-PHP中文网

Spring Boot 后端生成 PDF 并实现浏览器自动下载的完整解决方案

本文详解 Spring Boot 中通过 ResponseEntity 返回 PDF 文件时，为何浏览器不触发下载、仅显示乱码，并提供包含正确响应头、跨域配置及前端调用建议的完整实践方案。

本文详解 spring boot 中通过 responseentity 返回 pdf 文件时，为何浏览器不触发下载、仅显示乱码，并提供包含正确响应头、跨域配置及前端调用建议的完整实践方案。

在 Spring Boot 应用中，后端成功生成 PDF 流（如 ByteArrayInputStream）并返回 ResponseEntity 是常见做法。但许多开发者遇到一个典型问题：Postman 能正常预览 PDF，而浏览器点击下载按钮后却只显示原始 PDF 二进制内容（如 %PDF-1.4 开头的乱码），并未触发文件下载。根本原因在于：HTTP 响应缺少明确且正确的 Content-Type 响应头，导致浏览器无法识别资源类型并启用附件下载行为。

✅ 正确响应头是关键

虽然 @PostMapping(..., produces = "application/pdf") 声明了控制器支持的媒体类型（用于 Spring MVC 的内容协商和请求映射匹配），但它不会自动设置实际 HTTP 响应的 Content-Type 头。当手动构造 ResponseEntity 并写入原始字节流时，必须显式添加：

headers.add("Content-Type", "application/pdf");

⚠️ 注意：使用 "Content-type"（小写 t）在部分环境可能被忽略，推荐使用标准常量 HttpHeaders.CONTENT_TYPE，确保大小写与规范一致。

以下是修复后的完整后端代码示例：

@PostMapping(value = "/download/generateReport/{id}", produces = "application/pdf")
public ResponseEntity<inputstreamresource> generateFavoriteReport(@PathVariable String id) throws Exception {
    ReportRequest reportRequest = this.reportService.findByRequestWithId(id);
    ByteArrayInputStream in = this.reportService.generateFavoriteReport(reportRequest);

    HttpHeaders headers = new HttpHeaders();
    headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=FavoriteReport.pdf");
    headers.add(HttpHeaders.CONTENT_TYPE, "application/pdf"); // ✅ 强制声明 MIME 类型
    headers.add("Access-Control-Expose-Headers", "Content-Disposition"); // 仅暴露必要头，更安全
    headers.add(HttpHeaders.CACHE_CONTROL, "no-cache, no-store, must-revalidate");
    headers.add(HttpHeaders.PRAGMA, "no-cache");
    headers.add(HttpHeaders.EXPIRES, "0");

    return ResponseEntity.ok()
            .headers(headers)
            .body(new InputStreamResource(in));
}</inputstreamresource>

? 补充说明与最佳实践

produces 的作用：仅影响 Spring 的 HandlerMapping 和 ContentNegotiationManager，用于决定是否将该请求路由到此方法（例如区分 /report.pdf 和 /report.json）。它不参与响应体的实际序列化或头设置。
Content-Disposition: attachment：这是触发浏览器下载的核心头。若省略或拼写错误（如 content-disposition 小写），多数现代浏览器将尝试内联渲染（尤其对 PDF），而非下载。

跨域注意事项（CORS）：若前端与后端域名不同，除 Access-Control-Expose-Headers 外，还需确保全局或控制器级 CORS 配置允许 Content-Disposition 头被前端 JavaScript 访问（用于调试或自定义下载逻辑）：

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(Arrays.asList("https://your-frontend.com"));
    configuration.setAllowedMethods(Arrays.asList("GET", "POST", "OPTIONS"));
    configuration.setExposedHeaders(Arrays.asList("Content-Disposition")); // 关键！
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", configuration);
    return source;
}

前端调用方式建议：
❌ 错误：直接用 fetch() 或 axios.get() 获取 PDF 流后尝试 window.open(URL.createObjectURL(blob)) —— 易受 CORS 和 Blob URL 生命周期限制。
✅ 推荐：使用标签 download 属性发起导航（无需 JS 解析响应）：

<a href="/api/download/generateReport/123" download="FavoriteReport.pdf" class="btn btn-primary">下载报告</a>

或在 JS 中动态触发：

function downloadReport(id) {
    const link = document.createElement('a');
    link.href = `/api/download/generateReport/${id}`;
    link.download = 'FavoriteReport.pdf';
    document.body.appendChild(link);
    link.click();
    document.body.removeChild(link);
}