Flying Saucer+Thymeleaf生成PDF时UTF-8中文字符不显示问题

问题表现 #

基于SpringBoot搭建的PDF生成服务，集成Flying Saucer、Thymeleaf组件时，生成的PDF文件拉丁字符渲染正常，所有UTF-8中文字符全部缺失，已完成Thymeleaf编码配置、字体加载代码编写、模板编码声明、相关依赖引入后问题仍存在。

问题根因与对应修复 #

以下是按优先级排序的问题点，逐一修复即可解决中文不显示问题：

• 字体加载逻辑不兼容jar包部署
  现有代码通过ClassPathResource.getPath()获取字体路径传入addFont方法，SpringBoot打包为jar后，类路径下的字体文件存储在压缩包内部，不存在可直接访问的文件系统路径，会导致Flying Saucer实际无法读取字体文件，静默加载失败。
  修复代码：替换原有字体加载逻辑，改用输入流方式加载类路径字体，兼容jar/war等所有部署模式

  ITextRenderer renderer = new ITextRenderer();
  ITextFontResolver resolver = renderer.getFontResolver();
  // 替换原resolver.addFont(fonts.getPath(), ...)逻辑
  try (InputStream fontInputStream = new ClassPathResource("fonts/PingFangSCRegular.ttf").getInputStream()) {
      resolver.addFont(fontInputStream, BaseFont.IDENTITY_H, BaseFont.EMBEDDED);
  }
  

• 未配置全局字体 fallback 规则
  现有代码仅完成了字体注册，但未在CSS中指定全局元素使用该中文字体，Flying Saucer默认使用内置西文字体渲染，遇到中文字符时无对应字形直接跳过渲染。
  修复方式：在模板的style标签中添加全局字体声明，确保所有元素优先使用注册的中文字体，注意font-family取值必须和代码中加载的字体名称完全匹配（大小写、空格一致）

  * {
      font-family: 'PingFang SC Regular', sans-serif;
  }
  

• 模板内@font-face配置无效
  模板中写的src: url('/fonts/PingFangSCRegular.ttf')是Web服务上下文路径，Flying Saucer渲染离线HTML字符串时不会发起Web请求拉取资源，该路径无法访问，反而可能触发字体加载警告。
  修复方式：直接删除模板中的@font-face代码块即可，Java代码中手动注册的字体只要名称匹配即可被CSS规则识别，无需重复定义。
• 依赖版本冲突排查（可选）
  手动引入的itextpdf、itext-asian版本可能和flying-saucer-pdf自带的iText版本不兼容，导致字体解析逻辑异常。推荐直接使用org.xhtmlrenderer:flying-saucer-pdf:9.1.22稳定版本，无需额外单独引入iText相关依赖，避免版本冲突。

校验注意事项 #

1. 确认Maven打包时已将字体文件放入类路径：打包后检查target/classes/fonts/目录下是否存在PingFangSCRegular.ttf，如果缺失需在pom.xml的build配置中添加资源规则，包含ttf格式文件。
2. 修复后重启服务生成PDF，若控制台无字体加载相关报错，中文即可正常渲染。

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