简介在不同业务系统中经常需要把包含样式的网页文本转成 PDF以便打印、存档或离线阅读。对于 Java 后端开发者ITextRenderer 是一种常见选择这份资源围绕它在 Java 环境下的使用整理出一套可直接借鉴的 HTML 转 PDF 工具类同时也适合需要快速实现报表导出的初级或中级开发者。压缩包共 23 个文件大小约 28.74 MB主要包含 10 个 jar 依赖、2 个 Java 源码、示例 HTML/XML 以及 ttf/ttc 字体文件并附有 pom.xml、.classpath、.project 等配置整体可按 Maven 或 Eclipse 工程导入查看。已有3249人学习下载。资源内部集成了 flying-saucer、itext、freemarker、bcprov/bcmail 等常用库覆盖从依赖引入到文档加载、布局计算、PDF 生成的完整路径同时给出字体和示例页面有助于处理中文乱码、样式不生效、图片或字体无法访问等实际问题。通过阅读源码和运行示例可以较快掌握 setDocument、layout、createPDF 的调用方式并进一步扩展异常处理、批量转换或其他定制功能。1. 一个工具类引出的话题ITextRenderer 为什么能成为 HTML 转 PDF 的首选做 Java 后端的人迟早会碰到一个需求把一份写好的 HTML 模板变成 PDF用来生成合同、报告、票据或者服务单。很多人第一反应是启用本机 Chrome 的无头模式或者调 wkhtmltopdf但这两条路在服务端都不省心要额外维护进程、处理二进制依赖还得处理并发时的一堆怪问题。ITextRenderer 是纯 Java 的渲染库不依赖外部浏览器直接吃 XHTML 和 CSS 输出 PDF部署起来就是一个 jar。这篇文章只围绕一件事怎么把 ITextRenderer 封装成一个好用又不容易翻车的 HTML 转 PDF 工具类适合正在选型的开发者也适合已经遇到中文乱码、CSS 不生效问题的熟手。2. ITextRenderer 的原理与选型字体、CSS 解析和渲染管线是怎么串起来的2.1 ITextRenderer 到底是什么从 XHTML 到 PDF 的渲染管线ITextRenderer 是开源项目里的一个 PDF 渲染器内部走的是 Flying Saucer 那套「XHTML CSS 2.1」渲染管线。它先把 HTML 字符串解析成符合 XML 规范的文档树再由自带的 CSS 解析器计算样式和布局最后调用底层的 PDF 生成器把排好的页面一笔一笔画出来。这套管线决定了三件事。第一进入渲染器的 HTML 必须是 XHTML 格式标签闭合、属性带引号否则解析阶段就报错。第二页面里的 JavaScript 不会被执行任何依赖脚本动态拼出来的内容都拿不到。第三字体不是系统自动发现的必须通过代码显式注册不注册中文就是一片方块。搞明白这三条后面很多踩坑记录都能对上号。2.2 为什么选 ITextRenderer跟其他 HTML 转 PDF 方案放在一起看不少人在选型时会在 ITextRenderer、wkhtmltopdf、Chrome Headless 三者之间纠结。只看功能列表ITextRenderer 不是最强的但放在服务端批量生成场景里它的部署收益很突出。方案部署复杂度CSS 支持JS 支持并发表现适用场景wkhtmltopdf高依赖系统二进制优秀有限支持多进程管理麻烦本地工具、少量生成Chrome Headless高需管理浏览器实例完整完整内存占用大易被打挂页面截图、复杂模板ITextRenderer低纯 jar 依赖CSS 2.1 为主完全不支持单例复用不现实但每次新建很轻服务端批量合同、报告OpenHTMLtoPDF低ITextRenderer 的继承者CSS 2.1 为主不支持同样轻量但接口有差异维护更活跃的新项目我一般会这样选模板里没有复杂的弹性布局也不依赖脚本动态渲染页面以表格、段落、页眉页脚为主优先考虑 ITextRenderer。它最别扭的地方就是 CSS 版本停留在 2.1 附近写模板时心里得有这根弦。2.3 CSS 支持边界哪些属性值得写哪些写了不生效ITextRenderer 的 CSS 解析器不支持 flex、grid、box-shadow、position: fixed 这类现代属性。写模板时可以把它当成一个「认真支持 CSS 2.1 的老式排版引擎」而不是一个浏览器。类别支持情况典型写法字体与颜色支持font-family、font-size、color盒模型支持margin、padding、border、background表格支持border-collapse、width、text-align分页部分支持page-break-inside、page-break-before定位不支持 fixedfloat 可用但不推荐依赖弹性布局不支持flex、grid 一律忽略动态内容不支持JavaScript 不执行这个边界是选型时最重要的判断依据。如果业务方给的模板是从网页里直接拖出来的满屏 flex 和 JS 渲染ITextRenderer 大概率搞不定如果模板本身就是给打印设计的用表格和块级元素排版就能省掉一整条无头浏览器运维链路。3. 最小可运行 Demo用 ITextRenderer 把第一份 HTML 变成 PDF3.1 引入依赖版本兼容和字体注册要一起考虑Maven 项目里引入 Flying Saucer 的 PDF 模块即可它会把 iText 那层打包进来。版本选择上不要追最新优先选经过大量项目验证的稳定版本具体版本号以 Maven Central 上能拉到的最新稳定版为准。dependency groupIdorg.xhtmlrenderer/groupId artifactIdflying-saucer-pdf/artifactId version9.1.22/version /dependency这段配置说明两点。第一ITextRenderer 和 OpenHTMLtoPDF 的包名、类名不同代码里 import 的是org.xhtmlrenderer.pdf.ITextRenderer。第二这个模块内部捆绑了旧版 iText所以不要再往工程里塞其他版本的 iText 核心包否则类冲突会以各种诡异方式爆发最常见的就是NoSuchMethodError。3.2 准备一份合法的 XHTMLDOCTYPE、根节点和编码ITextRenderer 对输入的宽容度比浏览器低很多。下面这份是最小可渲染模板结构上少一个根节点属性都可能让样式整体失效。!DOCTYPE html html xmlnshttp://www.w3.org/1999/xhtml head meta charsetUTF-8 / style body { font-family: SimSun; } .title { font-size: 24px; font-weight: bold; } /style /head body p classtitle模拟项目X服务确认单/p p这是一段用于测试的中文内容。/p /body /html这里的xmlns不是摆设渲染器要靠它来识别 XHTML 命名空间。meta charset必须放在 head 区域并且 HTML 解析时按 UTF-8 读入否则中文内容后面显示乱码时很难怀疑到编码头上。font-family: SimSun只是给 CSS 一个字体名真正能不能渲染出来要看下一步注册了哪些字体文件。3.3 渲染核心代码注册字体、构建文档、输出文件写一个最少依赖的渲染方法只做四件事创建渲染器、注册字体、加载 HTML、输出 PDF。import java.io.FileOutputStream; import java.io.OutputStream; import org.xhtmlrenderer.pdf.ITextFontResolver; import org.xhtmlrenderer.pdf.ITextRenderer; import com.lowagie.text.pdf.BaseFont; public class DemoRenderer { public static void main(String[] args) throws Exception { // 1. 创建渲染器每一次渲染都使用新实例 ITextRenderer renderer new ITextRenderer(); // 2. 注册中文字体路径对应 Linux 下的字体文件 ITextFontResolver resolver renderer.getFontResolver(); resolver.addFont(/usr/share/fonts/truetype/simfang.ttf, BaseFont.IDENTITY_H, BaseFont.NOT_EMBEDDED); // 3. 加载 XHTML 字符串 String html html xmlns\http://www.w3.org/1999/xhtml\ bodyp你好ITextRenderer/p/body/html; renderer.setDocumentFromString(html); // 4. 排版后输出 PDF renderer.layout(); try (OutputStream out new FileOutputStream(output.pdf)) { renderer.createPDF(out); } } }setDocumentFromString传入的是 XHTML 字符串内部会走 XML 解析所以字符串必须闭合标签。layout()负责计算分页和坐标调用之后才能创建 PDF。createPDF写入输出流这里用了 try-with-resources避免文件句柄泄漏。字体注册里的BaseFont.IDENTITY_H表示按 Unicode 编码映射NOT_EMBEDDED表示不内嵌字体文件生成的 PDF 体积更小但换机器打开时依赖对方系统的中文字体追求稳定分发可以改成BaseFont.EMBEDDED。4. 把渲染代码包成工具类模板加载、参数绑定与输出封装4.1 工具类接口设计输入模板与数据输出文件路径工具类的目标是把渲染细节关在内部让业务代码只关心三件事模板从哪来、数据怎么填、PDF 写到哪。方法签名可以设计成下面这样。public class HtmlToPdfUtils { /** * 渲染 classpath 下的模板文件 * * param templatePath 模板路径如 templates/contract.html * param params 模板中的占位符变量 * param destPath 生成的 PDF 目标路径 */ public static void renderClasspathTemplate( String templatePath, MapString, String params, String destPath) { // 实现见后续小节 } }把输出路径写进参数而不是返回值是为了让调用方挨着业务逻辑直接落盘不用再自己写一对流。参数 Map 只处理字符串替换模板里渲染循环、条件判断这类逻辑不要放在这个工具类里那是模板引擎的职责后面第 6 章会讲怎么接。4.2 模板加载classpath 路径与本地文件两种方式实际项目中模板文件通常放在 classpath 的 templates 目录下但排错时又经常想直接用本地文件验证。工具类里把这两种来源都覆盖掉。import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Paths; public class HtmlToPdfUtils { public static String loadTemplate(String templatePath) throws Exception { // 先尝试从 classpath 读取 var resource HtmlToPdfUtils.class.getClassLoader() .getResource(templatePath); if (resource ! null) { return new String(resource.openStream().readAllBytes(), StandardCharsets.UTF_8); } // classpath 没有按本地文件读 return Files.readString(Paths.get(templatePath)); } }先查 classpath 再落本地文件是一个实用习惯。比如某公司在测试环境把模板打进 jar本地调试又直接改 templates 目录下的文件这种加载顺序能两边不误。readAllBytes在 JDK 9 以后可用注意整个文件大小要可控一个合同模板通常几十 KB没有内存压力。4.3 完整工具方法占位符替换、字体注册与 PDF 输出合并把前面三段组装成一个完整工具方法业务方一行就能调。import java.util.Map; import java.io.FileOutputStream; public class HtmlToPdfUtils { /** * 渲染模板并生成 PDF * * param templatePath 模板路径 * param params 占位符变量例如姓名、订单号 * param destPath 输出 PDF 路径 */ public static void renderClasspathTemplate( String templatePath, MapString, String params, String destPath) throws Exception { String html loadTemplate(templatePath); // 按 key 替换模板中的 {{key}} 占位符 for (Map.EntryString, String entry : params.entrySet()) { html html.replace({{ entry.getKey() }}, entry.getValue()); } // 渲染器不便宜但每次创建成本可控且避免了线程安全问题 ITextRenderer renderer new ITextRenderer(); ITextFontResolver resolver renderer.getFontResolver(); resolver.addFont(/usr/share/fonts/truetype/simfang.ttf, com.lowagie.text.pdf.BaseFont.IDENTITY_H, com.lowagie.text.pdf.BaseFont.NOT_EMBEDDED); renderer.setDocumentFromString(html); renderer.layout(); try (FileOutputStream out new FileOutputStream(destPath)) { renderer.createPDF(out); } } }render一行完成模板加载、变量替换和 PDF 生成。占位符用{{key}}而不是${key}是为了避开 CSS 里花括号选择器的干扰这点在自己设计模板规范时值得沿用。工具方法每次 new 一个ITextRenderer原因在后面细说简单讲就是它内部有非线程安全的状态复用一个实例反而容易出脏页。5. 避坑指南中文乱码、CSS 失效、分页错位的 5 个典型踩坑记录5.1 中文变成方块或者乱码现象HTML 里明明是正常中文PDF 打开全是方框或问号。原因渲染器没有找到支持中文的字体它按默认字体画字形缺字就画方块。解决必须调用resolver.addFont注册一个包含中文字形的 TTF并保证注册路径真实存在。不能只在 CSS 里写font-family: SimSun就完事。CSS 里的字体名和实际注册字体之间的关系不是自动的渲染器拿到 CSS 字体名后要去自身注册表里查找不到就静默降级。我一般会在工具类里做一次启动校验注册完字体后取一次已注册字体列表确认没有加载失败避免线上环境字体文件缺失时批量生成全乱码的 PDF。5.2 图片一张也不显示现象PDF 生成成功但页面里所有img区域是空白。原因setDocumentFromString没有告诉渲染器基准 URL图片的相对路径无从解析。解决调用renderer.getSharedContext().setBaseURL(...)把模板所在目录的绝对路径传进去。renderer.getSharedContext().setBaseURL(file:///opt/templates/);如果是网络图片需要额外处理超时和网络不可用。还有一个更隐蔽的问题图片路径里带空格或中文file://协议要求 URL 编码直接拼路径会加载失败。我在工具类里统一对路径做URLEncoder编码再拼成 file 协议这个坑就消失了。5.3 CSS 类样式只生效一半现象文字大小变了但颜色、边框没变或者 class 选择器完全不生效。原因最常见的有两个HTML 没有声明xmlns导致解析器没有按 XHTML 处理其次渲染器对 CSS 2.1 之外的新属性直接忽略。解决先把模板根节点的xmlns补上再去检查用到的 CSS 属性是否在支持列表里。排查时先用小样例验证把 CSS 内联到style属性里如果内联生效而 class 不生效问题基本就在 XHTML 解析那层。如果内联也不生效去看属性本身是否超出支持范围。这个排查顺序能省很多时间。5.4 表格跨页时行内文字被切掉现象一个长表格在分页处某一行被从中间截断文字压在页面边缘。原因渲染器的表格分页逻辑比较原始不会自动避让行内截断。解决给表格行加page-break-inside: avoid并在 CSS 里重复表头。table { width: 100%; border-collapse: collapse; } tr { page-break-inside: avoid; } thead { display: table-header-group; }page-break-inside: avoid的意思是这一行尽量不要拆开放不下就整体移到下一页。对于特别长的行实在避不开时至少确认表格列的宽度设置合理别让内容被压缩到截断。5.5 page 设置不起作用页面边距完全不对现象CSS 里写了page { margin: 20mm; }但生成的 PDF 边距是默认值。原因渲染器对page的部分属性支持有限且margin实际由底层 PDF 写入逻辑控制。解决不用page控制边距改为调用renderer.setPDFPageListener或直接操作底层 writer 的页面尺寸。// 创建 PDF 前设置页面边距 PDFDocumentObserver observer new PDFDocumentObserver() { // 覆写写入页面的逻辑调整边距 }; renderer.setPDFObserver(observer);这是我的习惯做法把页边距、页眉页脚这类 PDF 层面的配置放进工具类方法参数里CSS 只负责内容排版不负责纸张布局。这样逻辑清晰也不会出现改一个 CSS 属性把整份文档页距带偏的问题。6. 进阶玩法模板变量注入与批量导出的生产级用法6.1 用占位符工具方法之外的方式接入模板引擎上一章的render方法只支持简单占位符替换真实业务很快会发现不够用。最常见的是遍历一个订单列表把多行明细渲染到表格里。这种循环、判断逻辑交给模板引擎更合适做法是先用 Thymeleaf 这类引擎把 HTML 字符串解析成完整体再交给 ITextRenderer。TemplateEngine engine new TemplateEngine(); Context context new Context(); context.setVariable(orderList, orderList); String html engine.process(contract.html, context); // 此时 html 已是完整 XHTML再走工具类渲染 PDF HtmlToPdfUtils.renderHtmlString(html, destPath);模板引擎和渲染器各管一段引擎负责把数据变成 HTML渲染器负责把 HTML 变成 PDF。只要模板引擎最终输出的字符串是合法 XHTML两条链路就能无缝衔接。做这个分层时要注意 Thymeleaf 标准方言可能会输出 HTML 实体字符渲染器解析时一般能处理但遇到特殊字符乱码时可以先打印渲染前的 HTML 字符串检查一遍。6.2 批量生成多份 PDF流关不好会撑爆内存批量场景最常见的翻车不是渲染出错而是输出流没关或者渲染器实例被循环以外的地方共享。下面这段是我通常采用的批量生成写法每轮循环都使用独立的渲染器和完整的资源释放。for (Contract contract : contractList) { String html engine.process(contract.html, wrapContext(contract)); try (FileOutputStream out new FileOutputStream( exports/ contract.getId() .pdf)) { ITextRenderer renderer new ITextRenderer(); // 字体注册后复用 resolver 配置 configureFonts(renderer); renderer.setDocumentFromString(html); renderer.layout(); renderer.createPDF(out); } }关键动作有两个一个是每次循环里新建ITextRenderer避免上一份文档的布局状态污染下一份另一个是 try-with-resources 确保输出流一定关闭。批量导出几百份时如果流没有及时关闭文件句柄先耗尽随后内存也跟着涨上去这属于典型的批量处理安全事故。6.3 验证生成的 PDF文件头、页数和内容抽检开发时肉眼看不出来问题服务端批量生成必须有一套自动校验。最轻的验证是读文件头PDF 文件一定以%PDF-开头进一步可以统计页数更严格的是抽几份用 PDF 解析库提取文本确认关键字段没被吞掉。head -c 5 export/CF-1001.pdf # 期望输出 %PDF-按这个思路我在导出程序里加了一个校验步骤每批次生成完后抽查第一份和最后一份的文件头解析出页数再从关键字段表里抽几个值做文本匹配。这套验证曾帮我抓住过一个模板缩进错误导致的整批合同缺字段问题从那以后我就养成了「生成后必抽检」的习惯只要批量导出的报告数量超过 50 份这个步骤就不省略。希望帮到你。本文还有配套的精品资源点击获取