CFMaker导出PDF时字体丢失，如何嵌入字体确保显示一致？

Question

CFMaker导出PDF时字体丢失，本质是未嵌入字体子集所致。默认情况下，CFMaker（基于iText或Flying Saucer等引擎）仅引用系统字体路径，而目标设备若无对应字体（如“思源黑体”“微软雅黑”），PDF阅读器将回退至默认字体（如Helvetica），导致排版错乱、中文显示为方框。解决关键在于**强制嵌入字体**：① 将TrueType（.ttf）或OpenType（.otf）字体文件置于项目资源目录；② 在CSS中通过`@font-face`声明，并设置`src: url('fonts/msyh.ttc') format('truetype');`；③ 确保CFMaker配置启用字体嵌入（如iText需调用`font.setEmbedded(true)`，Flying Saucer需启用`fs-pdf-font-embedding: embed;`）；④ 中文字体建议选用全字重、支持GB18030的版本，并预生成子集以减小体积。验证方式：用Adobe Acrobat「文件→属性→字体」查看是否标注“Embedded Subset”。忽略此步，跨环境交付必然失真。

Answer 1

```html

一、现象层：PDF中文显示为方框或排版错乱

在CFMaker导出PDF过程中，终端用户频繁反馈“中文变方块”“标题缩进异常”“行高突变”等视觉失真问题。该现象在Windows/macOS/Linux跨平台预览、邮件附件打开、打印输出等场景中高度复现，且与本地是否安装“微软雅黑”“思源黑体”强相关——本质是PDF未携带可渲染的字形数据。

二、机制层：字体引用 ≠ 字体嵌入，PDF规范的底层约束

• PDF 1.4+ 规范要求：所有非标准字体（即非Adobe Base-14）必须显式嵌入，否则阅读器按FontDescriptor回退至Helvetica/Arial等替代字体
• CFMaker默认行为：基于iText 7.x或Flying Saucer（XHTMLRenderer）时，仅解析CSS中的@font-face路径，但不自动触发嵌入逻辑
• 关键误区：“src: url('msyh.ttc')”仅声明资源位置，不等于嵌入；若未配置引擎级嵌入开关，实际生成PDF中字体对象为空引用

三、技术栈层：主流引擎嵌入配置对照表

引擎	嵌入启用方式	子集控制	中文字体兼容要点
iText 7.2+	PdfFontFactory.createFont(fontPath, PdfEncodings.IDENTITY_H).setEmbedded(true)	默认开启Unicode子集；禁用：.setSubset(false)	必须使用IDENTITY_H编码，否则GB18030汉字映射失败
Flying Saucer (9.1.20+)	CSS中添加fs-pdf-font-embedding: embed;，并确保font-family与@font-face名称严格一致	通过fs-pdf-font-subsetting: true;启用	需将.ttf转为单字重文件（.ttc多字体集合不被FS原生支持）

四、实施层：四步闭环嵌入工作流

1. 资源准备：将fonts/msyh.ttf（非msyh.ttc）、fonts/NotoSansSC-Regular.otf置于src/main/resources/static/fonts/，确保Maven/Gradle打包后可被ClassPathResolver定位
2. CSS声明：

   @font-face {
     font-family: 'Microsoft YaHei';
     src: url('fonts/msyh.ttf') format('truetype');
     font-weight: normal;
     font-style: normal;
   }
   body { font-family: 'Microsoft YaHei', sans-serif; }

3. 引擎配置：iText中注入自定义PdfFontFactory，覆盖getDefaultInstance()，强制返回setEmbedded(true)字体实例
4. 子集优化：使用fonttools subset预生成GB18030常用字子集（约65536字），体积从20MB→1.8MB，避免全量嵌入拖慢渲染

五、验证层：不可绕过的交付质检动作

graph LR
  A[生成PDF] --> B{Adobe Acrobat Pro}
  B --> C[文件 → 属性 → 字体]
  C --> D[检查每项字体状态]
  D -->|含“Embedded Subset”| E[✅ 通过]
  D -->|含“Not Embedded”或“Standard”| F[❌ 失败：立即回溯CSS路径与引擎配置]

六、避坑层：高频失效场景深度归因

• ❌ 使用.ttc文件：iText/Flying Saucer均不支持TrueType Collection，必须拆分为独立.ttf（如msyh.ttf, msyhbd.ttf）
• ❌ CSS中font-family拼写与@font-face不一致：大小写敏感，空格数敏感（如'Microsoft YaHei '末尾空格导致匹配失败）
• ❌ Spring Boot应用中静态资源路径错误：未配置spring.web.resources.static-locations=classpath:/static/，导致url('fonts/xxx') 404
• ❌ 忽略字体许可证：微软雅黑为Windows系统专有，商用PDF嵌入需获微软授权；推荐采用SIL Open Font License的Noto Sans SC或Source Han Sans

```