html2pdf转换HTML到PDF时现代CSS样式失效（如Flex布局异常），咨询替代Java库

阿华AIGC实验室

2026-4-7

我完全理解你遇到的困扰——用基于iText的HTML转PDF方案（你代码里的ITextRenderer属于Flying Saucer生态，常被和html2pdf混淆）转换时，Flexbox这类现代CSS特性无法正确渲染，调整CSS也达不到网页的布局效果，确实很影响小票这类精准布局的场景。

下面推荐几个对现代CSS支持更好的Java库，适配你的需求：

1. OpenHtmlToPdf（首推）

这是Flying Saucer的活跃分支，专门针对现代CSS兼容性做了大量优化，完美支持Flexbox、Grid布局、CSS3媒体查询、打印样式，维护频率高，是后端Java转PDF的首选方案之一。

优势：

原生支持标准CSS3特性，不需要依赖外部浏览器内核
API设计和你现在用的ITextRenderer非常接近，代码迁移成本低
支持字体嵌入、自定义页面尺寸，完全适配你80mm小票的需求

迁移示例（对应你的现有代码）：

public static byte[] createPDF(String htmlTmpStr, String fontFile) throws Exception {
    ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
    
    PdfRendererBuilder builder = new PdfRendererBuilder();
    // 加载HTML内容
    builder.withHtmlContent(htmlTmpStr, null);
    // 嵌入自定义字体，和你的原有逻辑一致
    builder.useFont(new File(fontFile), "Arial", PdfRendererBuilder.FontStyle.NORMAL, true);
    // 配置页面尺寸（和你的CSS @page 配置匹配）
    builder.useDefaultPageSize(80, 80, PdfRendererBuilder.PageSizeUnits.MM);
    builder.withMarginTop(0);
    builder.withMarginRight(16); // 对应1rem（假设1rem=16px）
    builder.withMarginBottom(0);
    builder.withMarginLeft(0);
    
    builder.toStream(outputStream);
    builder.run();
    
    return outputStream.toByteArray();
}

使用时，只需要引入OpenHtmlToPdf的Maven依赖，替换原有的Flying Saucer/iText依赖即可，你的现有CSS（包括Flex布局）不需要大改就能正确渲染。

2. WKHTMLToPDF（Java调用/封装）

WKHTMLToPDF基于WebKit内核（和Chrome/Safari同源），相当于用真实浏览器渲染HTML再导出PDF，支持所有浏览器兼容的CSS特性——包括Flex、Grid、CSS变量、甚至JavaScript动态渲染的内容，兼容性是所有方案里最好的。

优势：

100%还原浏览器的布局效果，解决任何现代CSS兼容问题
支持打印样式、页面断点、颜色精确渲染（和你的-webkit-print-color-adjust: exact需求完美匹配）

实现方式：

你需要先在服务器上安装WKHTMLToPDF的二进制文件，然后通过Java的ProcessBuilder调用命令行，或者使用封装库（如wkhtmltopdf-wrapper）简化调用。

示例命令行参数（对应你的CSS配置）：

wkhtmltopdf \
  --page-size 80x80mm \
  --margin-top 0mm \
  --margin-right 1rem \
  --margin-bottom 0mm \
  --margin-left 0mm \
  --background \
  <(echo "$htmlTmpStr") \ # 传入HTML内容
  - # 输出到标准输出，Java读取为字节数组

Java中通过ProcessBuilder执行该命令，捕获输出流即可得到PDF字节数组，和你的现有返回逻辑一致。