Thymeleaf模板结合iText生成PDF遇500错误求助

1. 验证依赖兼容性 #

确保项目依赖中包含匹配版本的Thymeleaf和iText组件，避免版本冲突：

<!-- Maven 依赖示例 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>html2pdf</artifactId>
    <version>5.0.1</version>
</dependency>
<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>kernel</artifactId>
    <version>7.2.5</version>
</dependency>

2. 修正PDF生成服务实现 #

确保服务类正确处理模板渲染与PDF转换，保留异常栈便于排查：

import org.springframework.stereotype.Service;
import org.thymeleaf.TemplateEngine;
import org.thymeleaf.context.Context;
import com.itextpdf.html2pdf.HtmlConverter;
import java.io.ByteArrayOutputStream;
import java.util.Map;

@Service
public class PdfGenerationService {

    private final TemplateEngine templateEngine;

    public PdfGenerationService(TemplateEngine templateEngine) {
        this.templateEngine = templateEngine;
    }

    public byte[] generatePdf(String templateName, Map<String, Object> data) {
        Context context = new Context();
        context.setVariables(data);
        String htmlContent = templateEngine.process(templateName, context);

        try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
            HtmlConverter.convertToPdf(htmlContent, outputStream);
            return outputStream.toByteArray();
        } catch (Exception e) {
            throw new RuntimeException("PDF生成失败: " + e.getMessage(), e);
        }
    }
}

3. 调整控制器响应逻辑 #

设置正确的响应头与媒体类型，避免浏览器解析异常：

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.util.HashMap;
import java.util.Map;

@RestController
public class TestController {

    private final PdfGenerationService pdfGenerationService;

    public TestController(PdfGenerationService pdfGenerationService) {
        this.pdfGenerationService = pdfGenerationService;
    }

    @GetMapping("/generate-pdf")
    public ResponseEntity<byte[]> generatePdf() {
        Map<String, Object> data = new HashMap<>();
        data.put("title", "测试PDF文档");
        data.put("content", "这是通过Thymeleaf填充、iText转换的PDF内容");

        byte[] pdfBytes = pdfGenerationService.generatePdf("mapage", data);

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_PDF);
        headers.setContentDispositionFormData("attachment", "test-output.pdf");

        return ResponseEntity.ok()
                .headers(headers)
                .body(pdfBytes);
    }
}

4. 修正模板文件 #

确保模板语法符合Thymeleaf规范，且避免iText不支持的复杂HTML/CSS：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title th:text="${title}">默认标题</title>
    <style>
        body { font-family: Helvetica, sans-serif; padding: 20px; }
        .content-block { margin-top: 30px; border-top: 1px solid #eee; padding-top: 10px; }
    </style>
</head>
<body>
    <h1 th:text="${title}">默认标题</h1>
    <div class="content-block" th:text="${content}">默认填充内容</div>
</body>
</html>

5. 关键排查点 #

• 确认模板文件mapage.html放在src/main/resources/templates/目录（Spring Boot Thymeleaf默认路径）
• 查看服务器日志的完整异常堆栈，定位是模板渲染错误还是PDF转换错误
• 避免在模板中使用iText不支持的CSS特性（如flex布局、复杂选择器）
• 确保填充数据无null值，防止Thymeleaf渲染时抛出空指针异常

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