Java后端HTML转PDF工具包：内置宋体字体，支持XHTML校验与中文渲染-CSDN博客

本文还有配套的精品资源，点击获取

简介：直接可用的Java HTML转PDF方案，基于iText 2.0.8和Flying Saucer渲染引擎，专为中文环境优化。自带simsun.ttc中文字体文件，避免常见乱码问题，无需额外配置字体路径。要求输入HTML符合XHTML 1.0 Transitional标准——DOCTYPE必须完整声明，meta、link等标签需闭合，br、img等自闭合标签须写成
、形式，不兼容HTML5宽松语法。项目结构清晰，含完整src源码、lib依赖（包括iTextAsian及对应CMaps）、bin编译输出、Eclipse工程配置，可一键导入IDE运行；也支持集成进Spring Boot、Servlet等Java Web应用，生成合同、发票、报表等固定格式PDF文档。整个流程纯服务端执行，不依赖Chrome、wkhtmltopdf等外部浏览器或命令行工具，部署轻量、调用稳定。

1. 项目概述：为什么这个“老派”组合在今天依然值得认真对待

你有没有遇到过这样的场景：客户发来一份合同模板，要求后端生成PDF并自动归档；财务系统需要每天凌晨批量导出带公章水印的电子发票；或者报表平台要支持一键下载“所见即所得”的月度经营分析PDF？这些需求看似简单，但一旦落到Java后端实现上，往往踩坑无数——用wkhtmltopdf得装系统依赖、配字体路径、处理超时；用Chrome Headless又得维护浏览器进程、担心内存泄漏；而纯iText手写布局？开发周期长、样式还原度低、改个边距都要重测三遍。这时候，我翻出了这套基于 iText 2.0.8 + Flying Saucer（core-renderer） 的HTML转PDF工具包，它没有炫酷的新技术标签，却在生产环境稳定跑了七年，至今仍是我们内部合同生成服务的主力引擎。

它的核心关键词非常明确：html转pdf、java生成pdf、中文字体支持、XHTML校验、iText。注意，这里说的不是iText 7或iText 5，而是被很多人忽略的2.0.8版本——它和Flying Saucer的耦合深度，恰恰是解决中文渲染顽疾的关键支点。Flying Saucer负责解析和布局，iText 2.x负责最终渲染，而中间最关键的桥梁，就是iTextAsian系列库。这套方案不追求HTML5语义化或CSS3动画，它只做一件事：把一份结构干净、语义严谨的XHTML文档，原样、稳定、无乱码地变成PDF。它内置了simsun.ttc（即Windows宋体），字体文件直接打包进jar，连FontFactory.register()都不用调，彻底规避“字体找不到”“编码映射失败”“CJK字符显示为方块”这三大经典问题。更重要的是，它对输入HTML施加了明确约束：必须是XHTML 1.0 Transitional，DOCTYPE完整、标签闭合严格、自闭合标签必须带斜杠（<br/>而非<br>）。这不是矫情，而是Flying Saucer在2.x时代对XML解析器（Xerces）的硬性依赖——它把HTML当XML解析，容错率为零。所以，它不适合做CMS前端预览，但极其适合生成合同、发票、质检单这类格式固定、内容结构化、发布前可人工校验的正式文档。整个流程纯Java执行，无外部进程、无本地浏览器、无网络请求，部署就是一个jar包，调用就是一行render(html, outputStream)。如果你正在为PDF生成的稳定性、中文兼容性和运维轻量化头疼，这套“复古但扎实”的方案，值得你花两小时真正搞懂它怎么工作、为什么这样设计、以及如何避开那些只有踩过才明白的坑。

2. 整体架构与技术选型逻辑：为什么是iText 2.0.8 + Flying Saucer，而不是其他组合？

2.1 核心组件协同关系：一个被低估的“解析-布局-渲染”铁三角

这套方案的底层逻辑，是将PDF生成拆解为三个不可分割的阶段：HTML解析 → CSS布局计算 → PDF字节流渲染。而iText 2.0.8与Flying Saucer的组合，恰好在这三个环节形成了高度定制化的闭环，远非简单拼凑。

首先看Flying Saucer（core-renderer R8版本）。它不是一个通用HTML渲染器，而是一个专为“XML+CSS→PDF/图像”设计的轻量级引擎。其核心是基于Xerces XML Parser进行DOM构建，这意味着它天然要求输入是well-formed XML（即XHTML）。当你传入<br>，Xerces会报The element type "br" must be terminated by the matching end-tag；当你漏掉</head>，它直接抛org.xml.sax.SAXParseException: Element type "html" must be terminated by the matching end-tag。这种“不宽容”，恰恰是稳定性的基石——它强制你在开发阶段就修复所有结构缺陷，避免PDF生成时因DOM树异常导致布局错乱或静默失败。Flying Saucer的布局引擎（ReplacedElementFactory）负责将CSS盒模型计算为绝对坐标，但它本身不生成任何字节流，只输出一个Document对象和一套LayoutContext。

真正的渲染任务，交给了iText 2.0.8。这里的关键在于，iText 2.x的PdfWriter和Document类，提供了极细粒度的底层控制权。Flying Saucer通过ITextRenderer（这是Flying Saucer官方提供的iText适配器）将布局结果喂给iText：每一个文本块、每一条线、每一个图片，都被转换为iText的Chunk、Phrase、Rectangle等原语。而iText 2.0.8的精妙之处在于，它对亚洲语言（CJK）的支持不是靠后期补丁，而是深度集成在字体子系统里。它不依赖JVM默认字体，而是通过BaseFont类直接加载.ttc字体文件，并利用iTextAsian.jar中的CMap（Character Map）映射表，将Unicode码位精准定位到字体中的字形索引。例如，汉字“合”（U+5408）在simsun.ttc中对应哪个glyph ID，完全由GB1-5或UniGB-UTF16-H这类CMap文件定义。iTextAsianCmaps.jar正是提供了这些标准CMap，确保“宋体”能正确显示简体中文、繁体中文、日文平假名、韩文谚文。

提示：iText 5+版本虽然也支持CJK，但其字体注册机制改为FontFactory.register()+FontFactory.getFont()，且CMap需手动指定。而iText 2.0.8的BaseFont.createFont("simsun.ttc", BaseFont.IDENTITY_H, BaseFont.NOT_EMBEDDED)一行搞定，嵌入逻辑由BaseFont内部自动处理，这对打包部署极其友好。

2.2 为什么放弃iText 7 / Flying Saucer R9+ / OpenPDF？

我试过所有主流替代方案，结论很明确：它们在“中文PDF生成”这个垂直场景下，要么增加复杂度，要么引入新风险。

iText 7：功能强大，API现代，但其HTML to PDF模块（pdfHTML）本质是将HTML解析为iText对象树再渲染。它对XHTML语法宽容度高，但中文支持需额外配置fontProvider，且pdfHTML对复杂CSS（如position: absolute、float）兼容性不如Flying Saucer成熟。更重要的是，iText 7商业授权严格，而iText 2.0.8（LGPL）和Flying Saucer（LGPL）组合完全免费商用，这对很多中小项目是决定性因素。
Flying Saucer R9+：新版增加了对HTML5部分特性的支持，但代价是放弃了对Xerces的强绑定，转向更宽松的Jsoup解析器。这导致XHTML校验能力大幅削弱——<br>不再报错，<meta charset="utf-8">也能解析。表面看是进步，实则埋雷：当你的模板里混入未闭合的<div>，Flying Saucer R9可能生成一个“看起来正常”的PDF，但实际DOM树已损坏，后续添加页眉页脚或数字签名时突然崩溃。而R8的“零容忍”，让问题暴露在开发期，而非上线后。
OpenPDF：作为iText 2.x的Fork，它修复了一些安全漏洞，但对iTextAsian的兼容性未经充分验证。我们曾尝试替换，结果发现BaseFont.createFont()加载simsun.ttc后，中文仍显示为方块，根源在于OpenPDF未同步更新iTextAsianCmaps.jar中的CMap定义。这印证了一个经验：字体支持不是简单的“加载ttf文件”，而是“字体文件 + CMap映射 + 渲染引擎解析逻辑”三者严丝合缝。原版组合经过十年以上生产检验，改动任一环节都需全链路回归测试。

2.3 字体策略：为什么是simsun.ttc，而不是Noto Sans CJK或思源黑体？

项目内置simsun.ttc（宋体），绝非偶然。它解决了三个现实问题：

法律效力认可度：国内绝大多数电子合同平台、政务系统、银行票据，其PDF模板规范明确要求使用“宋体”或“仿宋”。simsun.ttc是Windows系统标配，其字形、字宽、标点位置符合国标GB2312/GBK，法院采信度高。换成开源字体，可能因字形微小差异（如“〇”与“零”的笔画数）引发合规性质疑。
嵌入体积与加载效率：simsun.ttc约12MB，而Noto Sans CJK SC完整版超100MB。iText 2.x在PDF中嵌入字体时，会将整个TTC文件（含所有字体变体）打包进去。12MB vs 100MB，直接影响PDF生成速度和内存占用。我们压测发现，用Noto字体生成100页合同，平均耗时比宋体高37%，GC压力显著上升。
CMap匹配成熟度：iTextAsianCmaps.jar中的GB1-5 CMap，就是为simsun.ttc这类GB2312编码字体设计的。它能100%覆盖常用汉字（65536个），且映射关系经多年验证无误。而Noto字体采用Unicode编码，需UniGB-UTF16-H CMap，该CMap在iText 2.x中存在少量映射遗漏（如某些生僻化学元素符号），导致个别字符渲染失败。

注意：simsun.ttc是TrueType Collection，包含Regular、Bold、Italic等多个字体。iText 2.0.8能自动识别并提取其中的字体变体，无需为粗体单独注册simsumbd.ttc。这是TTC格式相比单个TTF的优势。

3. 核心细节解析与实操要点：从XHTML校验到字体嵌入的全流程拆解

3.1 XHTML 1.0 Transitional规范：不是教条，而是稳定性的契约

Flying Saucer R8对XHTML的“苛刻”要求，常被开发者视为负担。但深入理解其原理后，你会发现这是一种主动的风险前置策略。下面以test.html为例，逐行解析关键约束及其背后的技术动因：

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>合同模板</title>
    <style type="text/css">
        body { font-family: "SimSun", "SimHei", sans-serif; }
        .header { text-align: center; font-size: 16pt; }
        table { border-collapse: collapse; width: 100%; }
        td { border: 1px solid #000; padding: 4px; }
    </style>
</head>
<body>
    <div class="header">
        <h1>商品购销合同</h1>
        <p>甲方：<span id="partyA">北京某某科技有限公司</span></p>
        <p>乙方：<span id="partyB">上海某某贸易有限公司</span></p>
    </div>
    <table>
        <tr><td>序号</td><td>商品名称</td><td>单价（元）</td><td>数量</td><td>金额（元）</td></tr>
        <tr><td>1</td><td>服务器机柜</td><td>8500.00</td><td>2</td><td>17000.00</td></tr>
        <tr><td>2</td><td>UPS电源</td><td>12000.00</td><td>1</td><td>12000.00</td></tr>
        <tr><td colspan="4" style="text-align:right;">合计：</td><td>29000.00</td></tr>
    </table>
    <p>签订日期：<span id="date">2024年06月15日</span></p>
    <br/> <!-- 关键：必须是<br/>，不能是<br> -->
    <p>甲方（盖章）：<br/>__________________</p>
    <p>乙方（盖章）：<br/>__________________</p>
</body>
</html>

DOCTYPE声明：<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ...> 这行不可或缺。Flying Saucer据此选择XHTML DTD进行验证，若缺失，Xerces会降级为“无DTD解析”，导致实体引用（如 ）无法识别，空格全部丢失。我们曾因漏写此行，导致合同中所有 变成问号，紧急回滚。
xmlns命名空间：<html xmlns="http://www.w3.org/1999/xhtml"> 告诉解析器这是XHTML文档，而非普通HTML。缺少它，CSS选择器如div.header可能失效，因为命名空间不匹配。
meta标签闭合：<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 必须带/>。Xerces将其视为一个空元素，若写成<meta ...>，解析器会等待</meta>，导致后续所有标签被吞入<meta>的content中，DOM树彻底错乱。
自闭合标签：<br/>、<img src="logo.png" alt="logo"/>、<input type="text"/> 等，必须带斜杠。这是XML语法铁律。<br>会被Xerces解释为<br></br>，在PDF中渲染出两个换行，合同段落间距翻倍。
CSS字体栈：font-family: "SimSun", "SimHei", sans-serif; 中，"SimSun"是关键。Flying Saucer会尝试用此名称查找已注册字体。而我们的代码中，BaseFont.createFont("simsun.ttc", ...)注册的字体，其PostScript名称正是SimSun（可通过BaseFont.getPostscriptFontName()验证）。若写成"simsun"或"宋体"，查找失败，回退到默认字体，中文乱码。

3.2 字体嵌入与中文渲染：一行代码背后的完整链路

字体支持是本方案的核心价值，其实现远不止“把ttc文件放进去”那么简单。以下是src/net/xxx/pdf/HtmlToPdfConverter.java中关键方法的深度解析：

public static void render(String htmlContent, OutputStream outputStream) throws Exception {
    // 1. 注册字体：仅需一行，路径为classpath资源
    FontFactory.register("simsun.ttc", "SimSun");

    // 2. 创建Flying Saucer渲染器实例
    ITextRenderer renderer = new ITextRenderer();

    // 3. 设置iText文档属性（关键：启用字体嵌入）
    SharedContext sharedContext = renderer.getSharedContext();
    sharedContext.setPrint(true); // 启用打印模式，优化分页
    sharedContext.setInteractive(false); // 禁用交互式PDF元素（如表单）

    // 4. 解析HTML为Document对象（触发XHTML校验）
    Document doc = XMLResource.load(new ByteArrayInputStream(htmlContent.getBytes("UTF-8"))).getDocument();

    // 5. 执行渲染
    renderer.setDocument(doc, null);
    renderer.layout();
    renderer.createPDF(outputStream);
}

这段代码看似简单，但每一步都暗藏玄机：

FontFactory.register("simsun.ttc", "SimSun")：simsun.ttc是放在src/main/resources/下的资源文件。FontFactory会通过ClassLoader.getResourceAsStream()加载它。"SimSun"是注册的逻辑名称，必须与CSS中font-family值完全一致（区分大小写）。注册后，FontFactory.getFont("SimSun")即可获取字体对象。
sharedContext.setPrint(true)：这是Flying Saucer的隐藏开关。当设为true时，它会禁用所有屏幕优化CSS（如@media screen），并强制使用@media print规则。更重要的是，它会激活iText的“字体子集嵌入”（subset embedding）。即PDF中只嵌入HTML实际用到的汉字（如合同中只出现“北京”“上海”“服务器”等200个字），而非整个simsun.ttc的65536字。这使生成的PDF体积从12MB降至200KB左右，且加载速度提升5倍。
XMLResource.load(...)：这是触发XHTML校验的入口。它内部调用Xerces的DocumentBuilder.parse()，任何XML语法错误都会在此处抛出SAXParseException，并附带精确的行号和列号（如Line 15, Column 22），极大缩短调试时间。
renderer.layout()：布局阶段，Flying Saucer计算每个元素的绝对位置。此时，BaseFont会根据当前字号（如12pt）和字符（如“合”），查询simsun.ttc中对应的字形轮廓（glyph outline），并缓存其宽度（advance width）。这个宽度值直接影响文本换行和表格列宽计算。如果字体注册失败，BaseFont返回null，布局引擎会用默认字体宽度（通常是等宽），导致中文文本严重挤占空间或换行错乱。

实操心得：在Spring Boot集成时，不要在@PostConstruct中注册字体！因为FontFactory是静态单例，多线程并发调用register()可能导致字体映射表污染。正确做法是在应用启动时（如ApplicationRunner）一次性注册，或在每次render()方法内检查是否已注册（FontFactory.isRegistered("SimSun")）。

3.3 项目结构与依赖管理：lib目录的深意

资源包中的lib目录并非随意堆放，而是精准匹配iText 2.x的依赖矩阵：

JAR文件	作用	为何不可替代
`itext-2.0.8.jar`	iText核心渲染引擎	2.0.8是Flying Saucer R8官方认证版本，更高版本API不兼容
`core-renderer-R8.jar`	Flying Saucer主引擎	R8是最后一个深度绑定Xerces的版本，提供最强XHTML校验
`iTextAsian-2.0.8.jar`	亚洲语言扩展包	提供`BaseFont`对CJK字体的增强支持，含`ChineseFont`等工具类
`iTextAsianCmaps-2.0.8.jar`	CMap映射表库	包含`GB1-5`, `UniGB-UTF16-H`等标准CMap，无此则中文无法映射

特别注意pom.xml中的依赖声明：

<dependency>
    <groupId>com.lowagie</groupId>
    <artifactId>itext</artifactId>
    <version>2.0.8</version>
</dependency>
<dependency>
    <groupId>org.xhtmlrenderer</groupId>
    <artifactId>flying-saucer-core</artifactId>
    <version>R8</version>
</dependency>
<!-- 注意：iTextAsian不发布在Maven Central，必须本地install -->
<dependency>
    <groupId>com.lowagie</groupId>
    <artifactId>iTextAsian</artifactId>
    <version>2.0.8</version>
</dependency>

iTextAsian和iTextAsianCmaps未上传至Maven Central，因此项目必须将这两个JAR放入lib目录，并在Eclipse中通过“Add External JARs”手动添加。若用Maven，需先执行：

mvn install:install-file -Dfile=lib/iTextAsian-2.0.8.jar \
                        -DgroupId=com.lowagie -DartifactId=iTextAsian \
                        -Dversion=2.0.8 -Dpackaging=jar

否则编译报错cannot find symbol class ChineseFont。这是新手最常见的卡点。

4. 实操过程与核心环节实现：从零开始集成到Spring Boot的完整指南

4.1 环境准备与工程导入：Eclipse与IDEA的差异化处理

项目结构清晰，但不同IDE对lib目录的处理逻辑不同，需针对性配置：

Eclipse导入：
1. File → Import → Existing Projects into Workspace，选择项目根目录。
2. 导入后，右键项目 → Properties → Java Build Path → Libraries → Add External JARs。
3. 重点添加lib/下的全部JAR（尤其是iTextAsian-2.0.8.jar和iTextAsianCmaps-2.0.8.jar）。
4. 检查src目录是否被识别为Source Folder（Properties → Java Build Path → Source中应有src条目）。
5. 运行net.xxx.pdf.TestMain，输入test.html路径，观察是否生成test.pdf。
IntelliJ IDEA导入：
1. File → Open，选择项目根目录。
2. IDEA会自动识别pom.xml，但lib目录不会被加入依赖。需手动操作：
- File → Project Structure → Modules → Dependencies → + → JARs or directories。
- 选择整个lib文件夹，Scope选Compile。
  3. 关键步骤：Project Structure → Libraries → + → Java，添加lib/iTextAsian-2.0.8.jar，并勾选Export（确保编译时可见）。
  4. 若提示Cannot resolve symbol 'ChineseFont'，重启IDEA并File → Invalidate Caches and Restart。

提示：test.html和simsun.ttc必须放在src/main/resources/下（而非src/），才能被ClassLoader.getResourceAsStream()正确加载。曾有同事将simsun.ttc放在src/，导致FontFactory.register()返回false，静默失败。

4.2 Spring Boot集成：封装为Starter的实战步骤

将工具包集成进Spring Boot，核心是将其封装为一个可自动配置的Starter。以下是pdf-starter模块的完整实现：

步骤1：创建自动配置类

@Configuration
@EnableConfigurationProperties(PdfProperties.class)
@ConditionalOnClass(ITextRenderer.class) // 确保Flying Saucer在classpath
public class PdfAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public HtmlToPdfService htmlToPdfService(PdfProperties properties) {
        // 初始化字体（应用启动时执行一次）
        try {
            FontFactory.register(properties.getFontPath(), properties.getFontName());
        } catch (Exception e) {
            throw new RuntimeException("Failed to register font: " + properties.getFontPath(), e);
        }
        return new HtmlToPdfServiceImpl();
    }
}

步骤2：定义配置属性

@ConfigurationProperties(prefix = "pdf")
@Data
public class PdfProperties {
    private String fontPath = "simsun.ttc"; // classpath路径
    private String fontName = "SimSun";
    private boolean embedSubset = true; // 是否启用字体子集嵌入
}

步骤3：实现服务接口

@Service
public class HtmlToPdfServiceImpl implements HtmlToPdfService {

    @Override
    public byte[] render(String htmlContent) throws IOException {
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        try {
            ITextRenderer renderer = new ITextRenderer();
            SharedContext sharedContext = renderer.getSharedContext();
            sharedContext.setPrint(true);
            sharedContext.setInteractive(false);

            // 解析HTML（此处可加入XHTML校验拦截器）
            Document doc = XMLResource.load(
                new ByteArrayInputStream(htmlContent.getBytes(StandardCharsets.UTF_8))
            ).getDocument();

            renderer.setDocument(doc, null);
            renderer.layout();
            renderer.createPDF(baos);
            return baos.toByteArray();
        } catch (Exception e) {
            throw new PdfGenerationException("Failed to render HTML to PDF", e);
        }
    }
}

步骤4：在application.yml中配置

pdf:
  font-path: simsun.ttc
  font-name: SimSun
  embed-subset: true

步骤5：Controller中调用

@RestController
public class PdfController {

    @Autowired
    private HtmlToPdfService pdfService;

    @PostMapping("/api/pdf/generate")
    public ResponseEntity<byte[]> generateContract(@RequestBody ContractRequest request) {
        String html = buildContractHtml(request); // 构建XHTML字符串
        byte[] pdfBytes = pdfService.render(html);
        return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_TYPE, "application/pdf")
                .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=contract.pdf")
                .body(pdfBytes);
    }
}

实操心得：在Spring Boot中，务必在application.properties中添加spring.main.allow-bean-definition-overriding=true。因为FontFactory是静态单例，多个@Bean方法注册同一字体时，Spring会报BeanDefinitionOverrideException。此配置允许后者覆盖前者，确保字体注册幂等。

4.3 生成合同PDF的完整代码示例与参数详解

以下是一个生产环境使用的ContractGenerator类，展示了如何动态填充数据并生成PDF：

@Component
public class ContractGenerator {

    @Autowired
    private HtmlToPdfService pdfService;

    public byte[] generatePurchaseContract(ContractData data) throws IOException {
        // 1. 读取模板（XHTML格式）
        String template = IOUtils.toString(
            getClass().getClassLoader().getResourceAsStream("templates/purchase-contract.xhtml"),
            StandardCharsets.UTF_8
        );

        // 2. 使用StringTemplate进行安全填充（避免XSS）
        ST st = new ST(template);
        st.add("partyA", escapeHtml(data.getPartyA()));
        st.add("partyB", escapeHtml(data.getPartyB()));
        st.add("date", formatDate(data.getDate()));
        st.add("items", data.getItems()); // items是List<Item>

        String filledHtml = st.render();

        // 3. 调用PDF服务
        return pdfService.render(filledHtml);
    }

    private String escapeHtml(String input) {
        if (input == null) return "";
        return StringEscapeUtils.escapeHtml4(input); // Apache Commons Text
    }

    private String formatDate(LocalDate date) {
        return DateTimeFormatter.ofPattern("yyyy年MM月dd日").format(date);
    }
}

关键参数说明：

escapeHtml()：必须对所有用户输入进行HTML实体转义。否则，若partyA为<script>alert('xss')</script>，将直接注入到PDF中，虽无执行环境，但破坏文档结构。StringEscapeUtils.escapeHtml4()将<转为<，>转为>。
ST（StringTemplate）：比MessageFormat或Thymeleaf更轻量，无运行时依赖，模板语法简单（ $partyA$ ），且天然支持循环（$items:{item|<tr><td>$item.name$</td></tr>}$）。
purchase-contract.xhtml模板：必须严格遵循XHTML规范。我们约定所有模板文件后缀为.xhtml，并在CI流程中加入xmllint --valid --noout *.xhtml校验，确保提交前语法正确。

5. 常见问题与排查技巧实录：那些只有亲手踩过才知道的坑

5.1 典型问题速查表

问题现象	可能原因	排查命令/方法	解决方案
PDF中中文显示为方块（□□□）	字体未注册或注册名称不匹配	`System.out.println(FontFactory.isRegistered("SimSun"));`	检查`FontFactory.register()`参数，确认`"SimSun"`与CSS中`font-family`完全一致；验证`simsun.ttc`文件是否损坏（用FontForge打开）
生成PDF为空白页	HTML解析失败，但异常被静默捕获	在`XMLResource.load()`外层加`try-catch`，打印`e.getMessage()`	检查`test.html`的DOCTYPE和命名空间；用`xmllint --noout test.html`验证XHTML有效性
表格边框不显示或错位	CSS中`border-collapse: collapse`未生效	在PDF中检查`<table>`元素的`border`属性是否被继承	在`<table>`标签上显式添加`style="border: 1px solid #000;"`，避免依赖继承
生成PDF体积过大（>10MB）	字体未启用子集嵌入	查看PDF属性中的“Fonts”列表，确认是否为`SimSun Subset`	确保`sharedContext.setPrint(true)`已调用；检查`iTextAsianCmaps.jar`是否在classpath
`ClassNotFoundException: com.lowagie.text.pdf.BaseFont`	`itext-2.0.8.jar`与`iTextAsian-2.0.8.jar`版本不匹配	`jar -tf itext-2.0.8.jar \\| grep BaseFont`	下载官方iText 2.0.8完整包，确保`iTextAsian`版本号严格一致

5.2 独家避坑技巧：来自七年的生产经验

技巧1：XHTML校验前置到CI/CD
不要等到运行时才发现<br>写成了<br>。我们在GitLab CI中加入以下步骤：

stages:
  - validate
validate-xhtml:
  stage: validate
  script:
    - apt-get update && apt-get install -y libxml2-utils
    - find src/main/resources/templates -name "*.xhtml" -exec xmllint --noout --dtdvalid http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd {} \;

任何XHTML语法错误，CI立即失败，阻断问题代码入库。

技巧2：字体嵌入调试的终极方法
当怀疑字体嵌入失败时，用pdfinfo -listfonts output.pdf命令查看PDF中实际嵌入的字体。正常输出应为：

name                                 type              encoding         emb sub uni object ID
------------------------------------ ----------------- ---------------- --- --- --- ---------
SimSun+0000000000000000000000000000 TrueType          Identity-H       yes yes yes      5  0

若显示Type: Unknown或emb: no，说明嵌入失败。此时检查iTextAsianCmaps.jar是否在运行时classpath（System.getProperty("java.class.path")打印验证）。

技巧3：解决Flying Saucer分页错乱的“黄金三原则”
合同PDF常需精确控制分页（如“签字页必须单独一页”）。Flying Saucer的分页算法易受浮动元素干扰，我们总结出：
- 原则一：禁用float。所有布局用display: inline-block或table模拟。
- 原则二：关键分页点（如签字栏）前插入<div style="page-break-before: always;"></div>。
- 原则三：为整个文档设置<body style="orphans: 3; widows: 3;">，防止标题孤行。

技巧4：性能优化的临界点
单次生成PDF耗时超过1.5秒，需警惕。我们通过JProfiler发现瓶颈常在XMLResource.load()的DOM解析。解决方案：
- 对高频模板（如发票），启动时预编译为Document对象并缓存（ConcurrentHashMap<String, Document>）。
- 缓存Key为模板MD5，Value为Document。填充数据时，直接doc.getElementsByTagName("span").item(0).setTextContent(value)，跳过重复解析。

最后分享一个小技巧：在test.pdf生成后，用Adobe Acrobat Pro打开，File → Properties → Fonts，确认SimSun字体状态为“Embedded Subset”。这是中文渲染正确的唯一金标准。任何其他状态（如“Not Embedded”或“Embedded”无Subset），都意味着PDF在某些PDF阅读器上可能显示乱码。

本文还有配套的精品资源，点击获取