Java项目配置PDF生成：iText与PDFBox使用教程

本文深入剖析了Java项目中PDF生成与处理的核心选型难题，明确指出iText 7与PDFBox并非互补而是定位迥异的两大技术路线：iText 7专精于从零构建高定制化中文PDF（如带页眉页脚、表格、嵌入字体的合同），而PDFBox则更胜任解析、修改和操作已有PDF（如加水印、填表单）；文章直击落地痛点——从Maven依赖的BOM统一管理、slf4j冲突规避、fontbox显式引入，到中文字体加载必须禁用file://路径并强制指定Identity-H编码，再到生成性能优化（批量添加内容、内存流写入、日志关闭）与资源泄漏防范（PDDocument必须close），每一条都是踩过坑后凝练出的硬核经验，帮你避开线上雪崩陷阱，一次选对、一次配稳。

iText 7 和 PDFBox 的选型冲突怎么破

Java 项目里想生成 PDF，iText 和 PDFBox 常被同时搜到，但它们不是互补关系，而是不同设计哲学的方案——选错一个，后期改起来成本很高。

简单说：iText 7 是“主动构建型”，适合需要精细控制排版、表格、字体嵌入、数字签名等场景；PDFBox 更偏向“底层操作型”，擅长解析已有 PDF、加水印、填表单、提取文本，生成能力弱且 API 繁琐。

• 如果你要从零生成带中文表格+页眉页脚+自定义字体的合同 PDF，优先用 iText 7
• 如果你只是读取用户上传的 PDF、盖个章、再返回，PDFBox 更轻量、无商业许可风险
• iText 5 已停止维护，别用；iText 7 社区版（AGPL）要求开源你的代码，商用必须买授权；PDFBox 是 Apache 2.0，无限制

Maven 依赖怎么写才不踩类冲突坑

直接粘贴官网给的依赖，大概率在 Spring Boot 项目里报 NoClassDefFoundError 或字体渲染异常——根本原因是日志、字体、IO 库版本打架。

关键不是“加什么”，而是“加哪些 + 排除哪些”：

• iText 7 必须引入核心三件套：itext7-core（用 BOM 控制版本），否则 kernel、layout、pdfa 各自拉不同版本的 slf4j，Spring Boot 的 spring-boot-starter-logging 就会炸
• PDFBox 不要只加 pdfbox，还得显式加上 fontbox 和 jempbox（虽然文档说可选），否则中文字体加载失败、中文乱码成方块
• 如果项目已用 logback，iText 的 slf4j-simple 依赖必须 掉，否则启动时抢日志绑定

示例（iText 7.2.x）：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.itextpdf</groupId>
      <artifactId>itext7-core</artifactId>
      <version>7.2.5</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

中文显示不出来？八成是字体和编码没对上

不管是 iText 还是 PDFBox，只要 PDF 里中文变空白或方块，问题几乎都出在字体路径、加载方式、编码声明这三处。

• iText 7 中，FontProvider 加载的字体文件路径不能用 file:// 绝对路径（容器部署时必挂），要用 getClass().getResource("/fonts/simhei.ttf") 或 new PdfFontFactory().createFont(...)
• PDFBox 中，PDType0Font.load() 必须指定 Identity-H 编码，且字体文件本身得是支持 Unicode 的（如 NotoSansCJK、simhei.ttf），用宋体 .ttc 文件会失败
• iText 7 的 Document.add(new Paragraph("测试")) 默认用 Helvetica，不支持中文，必须显式传 new Paragraph("测试").setFont(PdfFontFactory.createFont(...))
• 别信“设置 BaseFont.IDENTITY_H 就行了”这种过时说法——iText 7 没有 BaseFont，那是 iText 5 的东西

生成速度慢、内存爆掉？检查 PDF 内容构造方式

生成几百页 PDF 时卡死、OOM，往往不是库本身的问题，而是调用姿势不对。

• iText 7 中，避免在循环里反复调用 document.add(new Paragraph(...)) ——每句都触发 layout 计算。改用 Div 或 Table 批量装内容，最后一次性 add()
• PDFBox 生成新 PDF 时，不要用 PDDocument.save() 直接写磁盘，先用 ByteArrayOutputStream 写入内存，再转 byte[] 返回给 Web 层；否则大文件会撑爆堆内存
• 两者都禁用调试日志：iText 设置 Logger.getLogger("com.itextpdf").setLevel(Level.OFF)；PDFBox 设置 System.setProperty("org.apache.pdfbox.rendering.LogLevel", "OFF")
• PDFBox 的 PDDocument 必须显式 close()，否则底层 RandomAccessFile 句柄泄漏，Linux 下跑几天就 Too many open files

字体加载、日志、资源关闭，这些点看着小，但线上一跑就是雪崩点——没人告诉你，但每个都得亲手踩一遍才信。

今天关于《Java项目配置PDF生成：iText与PDFBox使用教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！