在Java开发中，将HTML内容转换为PDF格式是常见的业务需求，尤其在生成报表、电子合同、在线文档等场景中。由于HTML与PDF在渲染机制上的差异，转换过程需要处理样式兼容性、字体嵌入、布局分页等复杂问题。本文ZHANID工具网将系统梳理五种主流的Java实现方案，通过技术原理、代码示例和注意事项的对比分析，为开发者提供可落地的技术选型参考。
一、基于wkhtmltopdf的命令行转换
技术原理：wkhtmltopdf是一个开源工具，通过集成WebKit渲染引擎将HTML转换为PDF。其核心优势在于高保真渲染，能准确还原现代HTML5和CSS3的视觉效果，尤其适合复杂页面布局的转换。
实现步骤：
环境配置：下载对应操作系统的二进制包，配置系统环境变量或指定绝对路径。
# Linux示例安装命令 wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.focal_amd64.deb sudo dpkg -i wkhtmltox_0.12.6-1.focal_amd64.deb
Java调用封装：通过
Runtime.exec()执行系统命令，需处理进程流以避免阻塞。public class WkhtmlToPdfConverter { private static final String TOOL_PATH = "/usr/local/bin/wkhtmltopdf"; public static boolean convert(String htmlPath, String pdfPath) { ProcessBuilder pb = new ProcessBuilder( TOOL_PATH, "--margin-top", "20mm", "--header-html", "header.html", // 可选页眉 htmlPath, pdfPath ); try { Process process = pb.start(); // 异步读取错误流防止阻塞 new Thread(() -> { try (BufferedReader errorReader = new BufferedReader( new InputStreamReader(process.getErrorStream()))) { String line; while ((line = errorReader.readLine()) != null) { System.err.println("[WKHTML Error] " + line); } } catch (IOException e) { e.printStackTrace(); } }).start(); return process.waitFor() == 0; } catch (IOException | InterruptedException e) { e.printStackTrace(); return false; } } }
关键注意事项：
字体兼容性：需确保系统安装了PDF所需的字体（如中文字体），可通过
--user-style-sheet参数指定CSS覆盖默认样式。性能瓶颈：每个转换请求都会启动新进程，高并发场景下建议使用连接池管理进程。
跨平台问题：Windows路径需转义反斜杠，Linux需处理权限问题。
二、iText 7 + html2pdf扩展库
技术原理：iText是商业级PDF生成库，其html2pdf扩展通过解析HTML DOM树并映射到PDF元素，支持CSS2.1标准和部分CSS3属性（如圆角、阴影）。
实现步骤：
依赖配置（Maven）：
<dependency> <groupId>com.itextpdf</groupId> <artifactId>html2pdf</artifactId> <version>5.0.4</version> </dependency> <dependency> <groupId>com.itextpdf</groupId> <artifactId>font-asian</artifactId> <version>7.2.5</version> <!-- 中文字体支持 --> </dependency>
核心转换代码：
public class ITextHtmlToPdf { public static void convert(String htmlPath, String pdfPath) throws IOException { try (PdfWriter writer = new PdfWriter(pdfPath); PdfDocument pdf = new PdfDocument(writer)) { ConverterProperties properties = new ConverterProperties(); // 设置中文字体 FontProvider fontProvider = new DefaultFontProvider(false, false, false); fontProvider.addFont("simsun.ttc"); // 宋体 properties.setFontProvider(fontProvider); // 执行转换 HtmlConverter.convertToPdf(new FileInputStream(htmlPath), pdf, properties); } } }
关键优化点：
分页控制：通过CSS的
page-break-after属性实现强制分页。表格处理：复杂表格需使用
<table layout="fixed">并显式设置列宽。性能优化：对于大文件，启用
setSplitLate(false)避免内存溢出。
三、Flying Saucer（XHTMLRenderer）
技术原理：基于iText的开源项目，通过XHTML+CSS 2.1渲染生成PDF，适合需要完全控制样式的场景。
实现步骤：
依赖引入：
<dependency> <groupId>org.xhtmlrenderer</groupId> <artifactId>flying-saucer-pdf</artifactId> <version>9.1.22</version> </dependency>
转换实现：
public class FlyingSaucerConverter { public static void convert(String html, String pdfPath) throws Exception { String outputFile = pdfPath; OutputStream os = new FileOutputStream(outputFile); ITextRenderer renderer = new ITextRenderer(); // 字体配置 ITextFontResolver fontResolver = renderer.getFontResolver(); fontResolver.addFont("simsun.ttc", BaseFont.IDENTITY_H, BaseFont.NOT_EMBEDDED); // 设置XHTML内容（需符合XML规范） renderer.setDocumentFromString(html); renderer.layout(); renderer.createPDF(os); os.close(); } }
常见问题解决：
HTML合法性：必须为格式良好的XHTML（如标签闭合、属性引号），可使用Jsoup预处理：
String cleanHtml = Jsoup.parse(rawHtml).html();
图片处理：相对路径需通过
setBaseURL()指定基准目录。
四、PD4ML（商业库）
技术原理：专为HTML转PDF设计的商业库，支持JavaScript渲染和动态内容，适合复杂Web应用。
核心特性：
动态表单支持：可交互的PDF表单字段
条形码生成：内置Code128/QRCode支持
高级布局：精确控制页眉页脚、水印、批注
代码示例：
public class Pd4mlConverter {
public static void convert(String htmlPath, String pdfPath) throws Exception {
PD4ML pd4ml = new PD4ML();
pd4ml.setPageSize(PD4Constants.A4);
pd4ml.setHtmlWidth(960);
pd4ml.useTTF("fonts", true); // 字体目录
pd4ml.setDefaultTTFs("SimSun", "SimSun", "SimSun"); // 中文字体
try (FileOutputStream fos = new FileOutputStream(pdfPath)) {
pd4ml.render("file://" + new File(htmlPath).getAbsolutePath(), fos);
}
}
}授权说明：PD4ML采用按域名授权模式，开发环境可申请免费试用许可。
五、OpenHTMLToPDF（Flying Saucer分支）
技术原理：Flying Saucer的现代分支，支持CSS3 Flexbox和部分Grid布局，适合响应式设计转换。
优势对比：
| 特性 | Flying Saucer | OpenHTMLToPDF |
|---|---|---|
| CSS Flexbox支持 | ❌ | ✅ |
| 字体子集嵌入 | ❌ | ✅ |
| Java模块化支持 | ❌ | ✅ |
实现代码：
public class OpenHtmlConverter {
public static void convert(String html, String pdfPath) throws Exception {
try (OutputStream os = new FileOutputStream(pdfPath)) {
PdfRendererBuilder builder = new PdfRendererBuilder();
builder.withFile(new File(html)); // 或使用withHtmlContent()
builder.useFastMode(); // 性能优化
builder.toStream(os);
builder.run();
}
}
}综合对比与选型建议
| 方案 | 适用场景 | 复杂度 | 性能 | 成本 |
|---|---|---|---|---|
| wkhtmltopdf | 高保真复杂页面 | 中 | 高 | 免费 |
| iText 7 | 企业级文档生成 | 高 | 中高 | 商业 |
| Flying Saucer | 精确样式控制的静态页面 | 中高 | 中 | 免费 |
| PD4ML | 动态内容/表单密集型应用 | 低 | 高 | 商业 |
| OpenHTMLToPDF | 现代CSS布局的响应式页面 | 中 | 中高 | 免费 |
推荐实践：
简单需求：优先选择OpenHTMLToPDF或Flying Saucer
企业级应用：iText 7（需购买商业授权）或PD4ML
高并发场景：wkhtmltopdf需配合进程池管理
中文支持：所有方案均需显式配置中文字体文件
常见问题解决方案
中文乱码：
确保HTML使用UTF-8编码
在PDF生成代码中显式注册中文字体
示例（iText）：
FontProvider fontProvider = new DefaultFontProvider(false, false, false); fontProvider.addFont("NotoSansCJKsc-Regular.otf"); // 思源黑体 properties.setFontProvider(fontProvider);表格跨页断裂：
/* 禁止表格跨页 */ table { page-break-inside: avoid; } /* 或指定最小行高 */ tr { min-height: 20mm; }背景色丢失：
避免使用CSS渐变，改用纯色
确保
<body>设置了背景色：body { background-color: #ffffff; }图片不显示：
使用绝对路径或base64编码内嵌图片
检查图片权限（特别是网络图片需处理SSL证书）
结语
HTML转PDF的技术选型需综合考虑渲染质量、开发成本和维护复杂度。对于大多数业务场景，iText 7或OpenHTMLToPDF可提供良好的平衡点；当遇到特殊需求（如动态表单、复杂交互）时，PD4ML的商业支持能显著降低开发风险。建议在实际项目中通过POC验证确定最终方案，并建立完善的测试用例库覆盖各种边界情况。
本文由@战地网 原创发布。
该文章观点仅代表作者本人，不代表本站立场。本站不承担相关法律责任。
如若转载，请注明出处：https://www.zhanid.com/biancheng/5249.html
