Freemarker设置字体后pe:documentViewer无法正常渲染PDF问题

问题根因 #

该异常是pe:documentViewer组件或后端PDF渲染引擎（常见为Flying Saucer、OpenPDF、iText）的字体加载逻辑变更导致：你配置的font-family:Courier, monospace无法被渲染引擎识别，旧版本组件对缺失字体的容错度较高，找不到字体时会自动 fallback 到系统默认字体完成渲染；新版本对字体合法性校验更严格，加载失败后直接中断渲染，最终出现弹窗空白的情况。

解决方案 #

• 调整FTL模板字体配置：将Courier, monospace替换为PDF标准内置字体的通用写法，比如'Courier New', Courier, monospace，也可先替换为渲染引擎默认支持的sans-serif/serif验证是否能正常渲染。
• 强制嵌入所需字体：如果业务必须使用指定的Courier字体，在后端PDF生成逻辑中手动注册并嵌入字体文件，以Flying Saucer为例参考代码如下：

ITextRenderer renderer = new ITextRenderer();
// 第三个参数设为true代表将字体嵌入PDF文件，避免跨环境找不到字体
renderer.getFontResolver().addFont("your_project_path/courier.ttf", BaseFont.IDENTITY_H, true);

• 回滚组件版本：若近期升级过PrimeFaces Extensions版本，13.x及之后版本的pe:documentViewer底层依赖的PDF.js新增了跨域字体加载限制，可先回滚到之前正常运行的旧版本（如12.0.x稳定版）验证是否解决问题。
• 校验HTML输出格式：排查FTL渲染后的最终HTML代码，确认字体样式的引号、语法没有转义错误，避免渲染引擎解析样式失败。

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