简介面向需要在 Java 项目中把 HTML 模板转换为 PDF 文件的开发者提供一套可直接参考使用的工具类。该类基于 ITextRendererFlying Saucer编写覆盖 HTML 内容加载、CSS 样式布局、PDF 渲染输出等核心环节同时给出 pom.xml 依赖配置和示例调用代码适合有一定 Java 基础或前端经验、正在开发报表导出、订单下载或电子存档功能的读者使用。压缩包共 23 个文件大小约 28.74MB其中包含 10 个 jar 依赖包、2 个 Java 源码文件、HTML 测试页、PNG 渲染效果图、TTF/TTC 字体文件以及工程与类路径配置目录层次清晰便于直接导入项目后改造复用。已有 3249 人学习下载。借助这份工具类可以快速建立 HTML 到 PDF 的转换链路免去反复摸索依赖引入和字体乱码问题同时还可参考其错误处理、外部资源加载及扩展思路按需结合自身业务继续完善。1. 为什么还在用ITextRenderer做HTML转PDF老牌方案控制力最强的选择做后端报表交付时HTML转PDF的需求几乎躲不开订单确认函、月度对账单、资质证书前端打印一刷新就没截图方案又拿不到可检索的文本层。Java里能做的方案不少但我自己的项目里最终绕回ITextRenderer——它基于iText 2.x构建能把HTML按CSS 2.1的规则渲染出可控的PDF版面字体嵌入、纸张尺寸、页眉页脚都能精确指定而且整套渲染都发生在服务端模板改起来比改PDF模板库顺手得多。它不新但稳定适合那些需要「HTML模板 工具类封装 后端批量生成」的Java项目。如果你还在选型或者已经因为新版iText的API差异卡住了这篇按落地路径讲透。2. 先跑通最小链路依赖选型与ITextRenderer渲染一个HTML页面的核心流程ITextRenderer真正要跑起来第一步往往不是写代码而是把依赖配对搞清楚。很多翻车现场都是因为直接引入了新版iText 5/7/8的坐标结果类名对不上编译期就崩了。这一章先把依赖选型钉死再给一个能出PDF的最小代码链路。2.1 依赖选型为什么ITextRenderer必须搭配iText 2.x系列ITextRenderer不是iText官方的类它来自开源渲染引擎Flying Saucer组织坐标org.xhtmlrenderer。这个引擎自己负责解析HTML和CSS排版完成后把页面元素逐个画到PDF上而画PDF这一步调用的底层库是iText 2.x。这里的API包名是com.lowagie.text不是新版iText的com.itextpdf。也就是说如果项目里已经有iText 5或更新版本类名会直接冲突或者因为包名对不上运行期报NoClassDefFoundError。dependency groupIdorg.xhtmlrenderer/groupId artifactIdflying-saucer-pdf/artifactId version9.x/version /dependency !-- flying-saucer-pdf 会传递依赖 com.lowagie:itext:2.x不需要手动重复加 --这段坐标是我个人常用的路子。flying-saucer-pdf内部已经声明了对老iText的传递依赖正常用Maven拉下来就能工作。需要注意的是如果项目里其他模块引入了新版iTextMaven仲裁可能把老版顶掉这时候打开mvn dependency:tree看一眼com.lowagie是否还在不在就得在web层排除新iText或者强制锁定老版本。另外jdk版本如果已经是17老iText某些类会有反射访问告警但不影响功能别被日志吓到。选型的另一个理由是这个库对HTML的容错率比较现实它按XML的well-formed规范解析HTML但日常模板里标签没闭合、属性带中文引号这类脏数据它抛异常是明确的不会静默产出烂版面。相比用浏览器内核无头渲染的方案比如无头浏览器截图ITextRenderer不需要额外安装浏览器进程在容器环境里部署负担小得多这是很多团队一直保留它的根本原因。2.2 最小示例从HTML字符串到PDF文件的四个步骤依赖就位后生成一个PDF只需要四步构建Renderer实例、把HTML字符串交给Renderer并告知资源基准路径、做排版、输出到流。这个流程里最有门槛的是第二步的baseURL参数它决定了HTML里的img src和link href相对路径去哪里找资源。import com.lowagie.text.DocumentException; import org.xhtmlrenderer.pdf.ITextRenderer; import java.io.FileOutputStream; import java.io.IOException; import java.io.OutputStream; public class MinimalDemo { public static void main(String[] args) throws IOException, DocumentException { // 1. 准备一个最简单的XHTML字符串 String html htmlheadmeta charset\UTF-8\//head bodyh1Hello PDF/h1p这是测试内容/p/body/html; // 2. 创建输出流 OutputStream out new FileOutputStream(/tmp/hello.pdf); // 3. 核心渲染流程 ITextRenderer renderer new ITextRenderer(); renderer.setDocumentFromString(html, null); renderer.layout(); renderer.createPDF(out); out.close(); } }setDocumentFromString的第二个参数传了null是因为当前HTML里没有引用任何外部图片和样式表。一旦模板里有相对路径资源这里就必须传一个合法的URL前缀比如file:///opt/templates/。传null时资源解析会失效这是后面图片不显示最常见的原因。layout()是做排版计算的关键调用千万别省漏了它createPDF输出的页面全是空白。整段流程跑通后/tmp/hello.pdf就是一个带文本层、可检索的PDF文件不是截图。这个最小链路的价值在于验证环境如果连这个都跑不出来问题基本集中在依赖冲突或JDK版本上先解决环境再看业务模板排查效率最高。下一步就是把它封装成项目里真正能调的工具类。3. 落地为工具类HtmlToPdfUtils封装与字体、baseURL、编码三个必调参数生产项目里不可能每次调用都裸写ITextRenderer三步必须收敛成一个工具类。封装的核心不是把代码缩短而是把三个参数变成可配置项中文字体、baseURL、输出编码。这三个参数任何一个没处理好生成的PDF都会出现中文方块、图片红叉或者乱码属于高频翻车区。3.1 工具类骨架输入输出设计与非线程安全本质ITextRenderer实例不是线程安全的同一个实例在并发下复用会导致排版数据互相污染。所以工具类的典型形态是每次调用内部新建Renderer把HTML和资源路径作为入参输出用OutputStream承接这样既能写文件也能走HTTP响应流。返回byte[]的做法也常见但大PDF会在内存里攒一份完整字节对批量场景不友好我更推荐直接用输出流。import com.lowagie.text.DocumentException; import org.xhtmlrenderer.pdf.ITextRenderer; import java.io.IOException; import java.io.OutputStream; public class HtmlToPdfUtils { /** 字体文件绝对路径按部署环境配置 */ private static final String FONT_PATH /usr/share/fonts/source-han-sans/SourceHanSansSC-Regular.ttf; /** 模板资源根目录对应HTML里相对路径的解析前缀 */ private static final String RESOURCE_BASE_URL file:///opt/templates/; private HtmlToPdfUtils() { } public static void htmlToPdf(String html, OutputStream out) throws IOException, DocumentException { // 每次调用创建新实例避免线程安全问题 ITextRenderer renderer new ITextRenderer(); // 字体注册必须在使用前完成否则中文输出为空白 renderer.getFontResolver().addFont(FONT_PATH, Identity-H, true); // 第二个参数传baseURL供img/link解析相对路径 renderer.setDocumentFromString(html, RESOURCE_BASE_URL); renderer.layout(); renderer.createPDF(out); } }调用方只需管好输出流的打开与关闭。这里有个细节DocumentException是检查型异常工具类上抛后由业务层统一处理不要在工具类里吞掉否则PDF写一半失败时调用方拿不到任何反馈。另一个细节是FONT_PATH与RESOURCE_BASE_URL用静态常量方便部署时按环境替换不需要改业务代码。3.2 中文字体注册为什么默认配置下中文是方块ITextRenderer默认字体解析器不认识中文字形模板里出现中文时渲染出来的PDF里这些字符全变成空心方块但英文字母和数字正常。这个现象非常误导人容易让人以为是编码问题其实根因是字体解析器找不到支持中文字形的字体。处理方式就是用addFont把中文字体文件注册进去。// 注册方式一注册单个字体文件第三个参数控制是否嵌入PDF renderer.getFontResolver().addFont(/path/to/SourceHanSansSC-Regular.ttf, Identity-H, true); // 注册方式二注册系统字体目录addFont第二个参数传null时按字体名匹配 renderer.getFontResolver().addFont(/usr/share/fonts/chinese/, null, true);第二个参数Identity-H是CID编码名表示按Unicode字符集建立字形映射中文场景下必须用它换成Cp1252这种单字节编码中文依然出不来。第三个参数true表示把字体嵌入PDF文件这样PDF在别的机器上打开也不会因为缺字体而替换字形。嵌入字体的代价是文件体积变大但对于正式交付的文件嵌入是值得的。选择的字体文件建议用开源中文字体如思源黑体或系统自带的文泉驿字体不要直接依赖Windows的宋体路径因为生产服务器大多是Linux字体文件不一定存在。我一般把字体文件随应用一起打包到固定目录部署时校验文件存在性启动阶段就打日志避免生成时才发现路径不对。3.3 baseURL的正确传法处理图片与样式文件的相对路径模板里写img srcimages/logo.png/的时候ITextRenderer需要知道images相对于哪个根目录解析。工具类里RESOURCE_BASE_URL就是干这个的。常见错误是传一个不带file://前缀的普通路径渲染器会把它当URL解析失败图片全部静默丢失。// 正确的文件系统路径写法 String baseUrl file:///opt/templates/; // 如果需要从classpath读资源用类的URL String classpathBase HtmlToPdfUtils.class.getResource(/templates/).toExternalForm(); // 如果图片走HTTP直接传域名根路径 String httpBase https://cdn.example.com/assets/;toExternalForm()返回的字符串以file:/开头正好是setDocumentFromString需要的格式。注意根路径末尾必须带/否则images/logo.png会被解析到/opt/templatesimages这种错误路径上。这个尾斜杠问题我踩过不止一次每次都是排查到最后才发现拼接少了/。编码方面的坑集中在模板本身的字符集声明。setDocumentFromString解析的是字符串如果外部传入的是字节流工具类要先按UTF-8解码再传同时HTML的head里最好带上meta charsetUTF-8/声明双保险。某些老模板里写gb2312声明但实际内容按UTF-8存储渲染器按声明解析就会出现乱码这时候统一改模板比改代码省事。4. 页面尺寸、页眉页脚与CSS兼容边界别用现代CSS挑战ITextRenderer输出端的控制力是ITextRenderer相对无头浏览器方案的优势但边界也很清楚它吃CSS 2.1不吃现代CSS。页面大小、页边距、页眉页脚都能用CSS控制flex、grid、box-shadow这类属性要么被忽略要么直接破坏版面。理解这条边界模板设计才不会翻车。4.1 用page控制纸张大小与页边距ITextRenderer支持CSS的page规则纸张尺寸和页边距可以直接写在模板的style里不需要在Java代码里调iText的页面对象。这种方式的好处是模板作者自己就能调整版面不用改代码重新部署。page { size: A4; margin: 20mm 15mm; } page landscapePage { size: A4 landscape; margin: 10mm; }size支持A4、A3、letter以及具体的毫米单位比如210mm 297mm。横版页面用landscape关键字但要配合元素的page属性使用否则所有页面共享同一个page规则。实际项目中纵向A4为主横向表格多的场景可以用page: landscapePage给特定区块切页面方向ITextRenderer对此支持是正常的但要注意横竖混排时页边距变化带来的表格宽度适配问题。页边距的单位用mm最直观px在这种场景下会按96dpi折算成物理尺寸跟Word里看到的版面会有偏差。另外page里设置边距后HTMLbody的margin其实已经不重要了模板里不要再重复叠加body{margin:20px}这类规则否则真实出纸边距是两者叠加的视觉结果很难调准。4.2 running元素实现页眉页脚服务端生成PDF的场景几乎都要带页眉页脚比如客户名称、页码、日期。ITextRenderer的做法是CSS的running()函数配合page边距盒模板里定义一个元素为running元素然后在页边距区域引用它。style page { size: A4; margin: 20mm 15mm 25mm 15mm; top-center { content: element(header); } bottom-right { content: 第 counter(page) 页 / 共 counter(pages) 页; } } .page-header { position: running(header); } /style body div classpage-header客户对账单 - 某某贸易有限公司/div !-- 正文内容 -- /bodyposition: running(header)把元素从正常文档流中抽离element(header)在页边距区域引用它。counter(page)是当前页码counter(pages)是总页数这两个计数器是内置的直接拼在字符串里就能用。需要注意的是running元素不能太大页边距区域放不下的内容会被截断所以页眉里放一行文本最稳妥。页码这块有个细节第一页往往不想显示页码可以用page :first单独定义把bottom-right的content置空。ITextRenderer对:first伪类的支持是到位的但:left和:right这些对称双页的伪类在它内部基本不生效写模板时别指望奇偶页眉不同这种Word级能力。4.3 CSS支持边界flex、grid、box-shadow都是坑这一节是给模板作者划红线的。ITextRenderer源自CSS 2.1时代HTML布局走得是传统文档流模型现代布局属性它要么忽略要么解析错。CSS特性支持情况说明float / clear支持经典文档流布局的主力但浮动高度塌陷还是要小心inline-block支持横排块级元素的常用替代注意垂直对齐border-radius基本支持圆角能渲染但嵌套场景有时出现重叠毛边box-shadow不支持属性被静默忽略阴影效果直接消失flex / grid不支持布局完全错乱子元素会按块级流顺序堆叠position: fixed不支持表现为absolute随内容滚动而不是固定在页面opacity部分支持半透明整体失效的情况常见表现为全不透明media query不支持自适应布局无效按最大宽度渲染这些边界意味着模板设计要降级到传统布局多列用table或float垂直居中用line-height或表格单元格的vertical-align不要在新模板里引入任何基于flex的栅格系统。我见过一个团队把后台管理系统的HTML直接丢进去渲染整份PDF变成一列竖直堆叠的方块排查到最后是flex布局导致的。另一点是position: fixed的失效会直接影响每页底部固定签章这种需求ITextRenderer里固定定位元素只出现在一页。替代方案就是把签章内容放到bottom-center边距盒里或者老老实实放在正文末尾。给模板作者定一条规矩拿给这个工具类用的HTML要当作2005年的网页来写不然后果自负。5. HTML转PDF常踩的5个坑现象、原因与排查方案工具类封装完接下来基本就是排坑时间。这一章直接把最常踩的几个现象按现象、原因、解决列清楚遇到问题时按图索骥能省下不少查源码的功夫。5.1 中文乱码或方块现象是英文字母正常中文全是空心方块或者全文乱码。原因分两类一类是没注册中文字体字形映射表里根本没有汉字另一类是HTML声明了gb2312但实际内容按UTF-8解析字节错位导致字符本身就已经错了。解决方法是按3.2节注册中文字体并统一模板编码。如果字体注册了还出方块检查字体文件本身是否包含目标字形有些精简版字体只收录了常用字生僻字照样出方块换成思源黑体这类全字符集字体即可。字体相关的另一个隐蔽问题是addFont的第二个参数写错比如写UnicodeBigUnicode这种不存在的编码名渲染器不报错但输出全是乱码。用Identity-H最稳不需要纠结别的值。5.2 图片不显示或间歇性白图现象是HTML里图片区域空白或者日志里出现类似URI is not absolute的报错。原因基本都是baseURL传错或没传相对路径解析失败。解决方式是确认baseURL以/结尾并且是file://或http://开头的合法URL。如果图片来自网络直接在img src里写完整URL同时baseURL传null这样渲染器按绝对地址拉取。偶尔出现的白图还有一种情况图片是data:image/png;base64开头的内嵌格式ITextRenderer对data URI的支持不稳定小图偶尔能出大图直接跳过。解决方法是把内嵌图片先解码成文件再改写src为相对路径不要依赖data URI。5.3 渲染突然抛EOFException或DocumentException现象是生成PDF的过程中异常中断有时是随机发生的重跑一次又好。原因八成是输出流被提前关闭或者临时目录里的字体文件被其他进程占用导致iText读到半截数据。解决方式是把createPDF放到try块里确保out.close()在所有渲染完成后执行不要在layout()之前关闭流。排查时可以打印完整堆栈看看异常是不是发生在FontFileReader内部是的话检查字体文件权限和完整度。还有一种场景是并发批量生成时多个线程共用了同一个OutputStreamiText内部写数据时互相覆盖。这种问题报错位置飘忽不定排查起来最费时间解决办法也简单每个线程独立创建输出流工具类不要持有任何共享流状态。5.4 表格边框缺失与分页断裂现象是表格的边框时有时无或者一个单元格被拦腰截断跨到下一页。原因通常是模板里用了border-collapse: collapse之外的表格边框方案或者单元格里的大块内容没法在分页处拆开。ITextRenderer对表格的border处理依赖CSS 2.1标准行内border1这种HTML属性它接触不多表现不稳定。解决方式是表格样式统一走CSS边框写到td和table上不要依赖HTML属性。分页断裂的解法是靠page-break-inside: avoid保护单行和单元格以及把表头放在thead里ITextRenderer会自动在跨页时重复表头。如果表格实在跨页多给大单元格内部加一层display: block包装这样拆页点会落在包装元素边界上不再从文本中间硬切。5.5 PDF文件体积异常偏大现象是几页的PDF跑出几十MB打开却没什么特殊内容。原因基本是字体嵌入方式的问题addFont第三个参数传true时默认嵌入整个字体文件如果是全字符集字体光字体就要十几MB。解决方式有几个路径换用子集化能力较强的字体文件本身就小或者接受体积换兼容性——正式商业交付时嵌入是必要的内部临时文件则可以考虑不嵌入。实在要控制体积可以试试setPDFEncryption之类的手段压缩但效果有限。我更推荐在模板设计阶段控制字体数量一个PDF里不要引用超过两款字体每多一款字体嵌入体积就多一份完整字形表。思源黑体Regular加Bold两套字体就会让单文件体积明显上涨能用字重模拟就别塞第二套字体文件。6. 从能用走向可控批量生成的性能观察与两个生产技巧工具类稳定运行之后下一个问题通常是性能几百上千份PDF的批量任务怎么缩短总时长。不少人默认瓶颈在ITextRenderer渲染本身但其实资源加载和流的生命周期管理往往占用更多时间。第一个技巧是区分开销new ITextRenderer()本身轻量真正昂贵的是每次调用都要重复执行的字体加载。getFontResolver().addFont每次都会解析字体文件一个十几MB的字体文件解析耗时在几百毫秒到一秒以上批量100份就多出几十秒纯等待。优化方向是把字体解析结果做进程级缓存但ITextRenderer的FontResolver底层没有公开的缓存入口我实际用过的落地做法是让工具类以静态初始化块只加载一次字体配置配合ThreadLocal持有渲染器实例减少重复构建。这个方案要注意渲染器不能跨线程复用ThreadLocal天然满足每线程一份的要求实测下来批量场景有可见提升。第二个技巧是流的回收习惯。批量循环里最容易出现的是OutputStream开了不关文件描述符耗尽后整批任务随机失败。我吃过一次亏某次生成300份对账单跑到第200份时开始抛Too many open files当时还以为是渲染引擎的问题最后排查发现是List里攒了一堆没关闭的流。从那以后我在批量代码里坚持用try-with-resources逐份关闭生成完一份立刻落盘不攒内存。文本层可检索这一点也值得验证生成的PDF用阅读器打开直接搜索关键词能命中才说明是真的矢量PDF而不是图片贴上去的假PDF。日常上线前我习惯抽三份不同模板的PDF做这三件事检查首页页眉、翻到中间页看表格跨页、搜索一个业务单号确认文本层完好。ITextRenderer给控制力但最终交付物是否达标靠的还是这些朴素的检查习惯。希望帮到你。本文还有配套的精品资源点击获取