SpringBoot整合Thymeleaf与Flying Saucer生成PDF报错求助

根因 #

现有Thymeleaf配置类仅注册了ClassLoaderTemplateResolver Bean，未注册关联模板解析器的TemplateEngine实例，Spring上下文无对应类型可注入Bean，直接触发启动失败。
另外原配置存在冗余代码：重复调用两次setTemplateMode方法，后一次设置的XHTML模式会覆盖前一次的HTML5配置。

修复方案 #

修改ThymeleafConfig类，补充TemplateEngine Bean定义，将已配置的模板解析器注入关联，修正后完整配置代码如下：

@Configuration
public class ThymeleafConfig {

    @Bean
    public ClassLoaderTemplateResolver templateResolver() {
        ClassLoaderTemplateResolver templateResolver = new ClassLoaderTemplateResolver();
        templateResolver.setPrefix("templates/");
        templateResolver.setSuffix(".html");
        templateResolver.setTemplateMode("XHTML");
        templateResolver.setCharacterEncoding("UTF-8");
        templateResolver.setOrder(1);
        return templateResolver;
    }

    @Bean
    public TemplateEngine templateEngine(ClassLoaderTemplateResolver templateResolver) {
        TemplateEngine templateEngine = new TemplateEngine();
        templateEngine.setTemplateResolver(templateResolver);
        return templateEngine;
    }
}

配置中保留XHTML模板模式是为了适配后续flying-saucer组件的XML解析规则，避免语法不兼容问题。

根因 #

该异常由flying-saucer内置的XML解析器抛出，核心原因是传入setDocumentFromString方法的HTML内容，在XML声明（prolog区域）之前存在非法内容，常见触发场景包括：

• 模板文件以UTF-8 BOM格式存储，渲染后内容开头携带BOM不可见字符
• 模板文件开头存在多余空行、空格或其他不可见特殊字符
• 模板未遵循XHTML语法规范，缺少标准XML声明，或字符集配置不匹配导致开头出现乱码

修复方案 #

按以下步骤逐一排查处理：

• 打开templates/helloworld.html模板文件，将文件编码改为UTF-8 无BOM格式保存，删除文件开头所有多余空行、空格，在文件最顶部添加标准XHTML文档声明，参考模板结构如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>PDF Test</title>
</head>
<body>
    <p>Hello <span th:text="${name}"></span></p>
</body>
</html>

• 可在templateEngine.process方法执行后添加日志，打印渲染完成的HTML字符串全量内容，检查字符串最开头是否为<?xml声明，若存在其他多余字符直接清理模板文件对应位置的内容即可。
• 确认模板文件实际编码和templateResolver中配置的UTF-8字符集一致，避免编码不匹配导致的乱码问题。

以上修改完成后重启应用，即可正常执行PDF生成逻辑。

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