现在很多业务系统里，都免不了要和 PDF 打交道。小到一张电子发票、一份订单回执，大到数据分析报表、月度账单，PDF 因为格式稳定、跨平台一致、不可随意篡改的特性，几乎成了正式文档的默认载体。而 Java 后端生成 PDF，绕不开的一个库就是 iText。

我最早接触 iText 是做一个客户账单系统，需要在后端根据订单数据动态生成一张带图表的月度报表：上半部分是一张汇总表，中间要插入一张柱状图展示近半年销售额，下面是明细列表。当时踩了不少坑，尤其是图表怎么画、图片怎么塞进 Document、中文字体怎么不变成方块。这些坑今天整理成一篇完整的实操笔记，从零到一带你把 iText 的 Document 模式彻底搞明白，最后附上一个可以直接照着改的完整示例。

这篇内容适合正在用 Java 做报表导出、PDF 下载功能的后端开发，也适合刚接触 iText、想在项目里快速落地 PDF 生成的同行。默认你熟悉 Java 基础语法和 Maven 项目结构，不需要你有任何 PDF 底层知识。

1. 生成 PDF 的方案选型与 iText 的角色定位

先用一句话交代背景：Java 生态生成 PDF 的方案其实不少，但绝大部分最终都绕不开 iText。常见的几条技术路线我简单对比下，你心里有个谱。

1.1 主流方案横向对比

如果你的需求是“动态生成数据报告、订单、合同”，主力方案我推荐 iText 的 Document 模式。Document 是 iText 提供的“文档对象模型”，思路特别像写 Word 文档：定好页面，往里塞段落、表格、图片，最后按顺序输出。相比直接用 PdfWriter + PdfContentByte 逐坐标绘制，Document 模式可以帮你省掉大量坐标计算，代码可读性也高得多。

1.2 为什么选择 Document 模式

iText 实际上提供两套操作 API。一套是最底层的 PdfWriter，直接在页面上用绝对坐标画线、写字、贴图；另一套就是 Document 模式，它基于事件监听机制，把段落、表格、图片当成“块”，一层层铺到页面上。

做业务报表选 Document 模式的原因很直白：

一句话：不想自己管换页、不想自己算坐标、不想在样式代码里淹死。Document 模式负责排版和分页，你只关心内容逻辑。

1.3 iText 版本的坑，先帮你排掉

iText 版本迭代非常影响学习成本。你在网上搜教程，可能看到 iText 5、7、8 各有写法，这里先明确一下：

• iText 5 是最广泛使用的经典版本，包名com.itextpdf，API 稳定，网上教程最多。但注意它已经是旧版，不再有新特性。
• iText 7 的包名变成了com.itextpdf.kernel、com.itextpdf.layout，架构焕然一新。写法上和 5 差别很大。
• iText 8 延续 7 的架构，核心 API 兼容 7，主要在授权和功能上做了调整。

我下面示例代码用 iText 7 语法（当前主流、后续维护友好），但会把 5 和 7 的关键差异在合适的地方点出来，免得你照着老教程抄的时候一脸懵。

注意：iText 的开源版本采用 AGPL 协议，如果你的项目是闭源商业软件，需要评估是否要购买商业授权。很多团队在这方面吃过亏，建议上线前就让法务或负责人确认好。

2. 环境准备与 Maven 依赖最小化配置

在写业务代码之前，先把环境准备好。用 Maven 是最省事的，我直接把最小可运行的依赖贴出来。

2.1 Maven 依赖（iText 7）

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

如果不想引入itext7-core整个聚合包，可以按需拆开引入。实际项目里我经常只用到 kernel 和 layout 两个模块，再加个字体模块：

<dependency> <groupId>com.itextpdf</groupId> <artifactId>kernel</artifactId> <version>7.2.5</version> </dependency> <dependency> <groupId>com.itextpdf</groupId> <artifactId>layout</artifactId> <version>7.2.5</version> </dependency> <dependency> <groupId>com.itextpdf</groupId> <artifactId>font-asian</artifactId> <version>7.2.5</version> </dependency>

font-asian模块里包含了对中文、日文、韩文字体的支持定义。如果你不确定自己缺哪些依赖，直接上itext7-core最稳妥，它会把核心模块都拽进来。

2.2 字体文件的准备，越早越好

中文 PDF 的乱码问题，绝大多数不是 PDF 编码没设置对，而是字体没配置对。iText 自带的标准字体（Helvetica、Times 等）不包含中文字形，直接往 PDF 里写中文，出来的注定是乱码或方框。

我的建议非常明确：项目里单独准备一个字体目录，放一套开源商用无版权风险的中文字体文件（比如思源黑体、文泉驿正黑，或你公司日常使用的授权字体），统一走字体文件路径加载。这样既保证服务器环境一致，也避免依赖操作系统字体库。

以思源黑体为例，字体文件放resources/fonts/SourceHanSansSC-Regular.otf，下面代码就能把它加载为 iText 的字体对象：

PdfFont chineseFont = PdfFontFactory.createFont( "src/main/resources/fonts/SourceHanSansSC-Regular.otf", PdfEncodings.IDENTITY_H, PdfFontFactory.EmbeddingStrategy.PREFER_EMBEDDED );

IDENTITY_H表示使用 Unicode 编码方式，PREFER_EMBEDDED代表优先将字体嵌入 PDF。嵌入字体文件会增大 PDF 体积，但保证了任何设备打开都是原样显示。对于对外分发的正式报表，建议保留嵌入；如果只是内部系统预览，可以用NO_EMBEDDING减小体积。

3. Document 核心流程：从创建到输出的完整骨架

Document 模式说白了就五步：创建 PdfWriter → 创建 PdfDocument → 创建 Document → 往里面塞元素 → 关闭。下面把这五步拆开讲，每一步背后的逻辑也说清楚。

3.1 创建输出流与 PDF 文档

String dest = "report.pdf"; PdfWriter writer = new PdfWriter(dest); PdfDocument pdf = new PdfDocument(writer); Document document = new Document(pdf);

这段代码里，PdfWriter负责把 PDF 内容写入文件流。PdfDocument是底层文档对象的抽象，负责页面的管理。而Document充当的是排版容器的角色，你往 Document 里加段落、表格时，它会自动决定这些元素在页面上的位置，空间不够时自动换页。

注意一个容易出错的地方：当你用new Document(pdf)创建对象后，iText 会默认创建一个 A4 页面。如果你在后续代码中自己又添加了一个新页面，又在旧页面写完内容后才发现尺寸不对，那排查成本就高了。所以页面设置一定要在最开始就定清楚。

3.2 页面大小、边距和元信息的设置

页面设置有两种常见方式。第一种，在创建 PdfWriter 前就设置好默认页面尺寸：

PdfDocument pdf = new PdfDocument(writer); Document document = new Document(pdf, PageSize.A4); document.setMargins(36f, 36f, 36f, 36f);

setMargins四个参数分别是上右下左，单位是 pt 点。1 pt 大约等于 0.035 厘米，A4 宽度是 595 pt，高度 842 pt。36 pt 大约 1.27 厘米，是一份文档比较常规的页边距。

第二种方式，如果你想在文档内部调整某几页的横向或纵向，可以在添加元素前先调用：

document.setPageSize(PageSize.A4.rotate());

rotate()方法返回横向的 A4 页面。这种中途切换页面尺寸的场景，在导出宽表格或大图时经常会用到。

元信息设置也不要忽略。PDF 的元信息相当于文档的身份证，设置后别人右键属性就能看到标题、作者、主题：

pdf.getDocumentInfo().setTitle("月度销售统计报表"); pdf.getDocumentInfo().setAuthor("某业务系统"); pdf.getDocumentInfo().setCreator("iText Demo"); pdf.getDocumentInfo().setSubject("月度销售统计");

在正式项目中，标题、作者信息往往由业务模块动态传入，千万别写死在代码里，否则导出几百份文档全是同一个人，法务审计的时候会非常尴尬。

3.3 Document 的关闭时机与资源释放

iText 的 Document 对象在使用完毕后一定要关闭。关闭操作不只是释放内存，还会触发 PDF 文件完成尾部写入和交叉引用表更新。如果忘记关闭，生成的 PDF 文件很可能损坏，打开时提示错误。

推荐的关闭姿势：

try { // 添加各种元素 } catch (Exception e) { // 异常处理 } finally { document.close(); }

如果你用 Java 7 之后的 try-with-resources 语法，也可以把 Document 放进资源块，但要注意顺序：必须先关 Document，因为 Document 持有 PdfDocument 的状态。倒过来关会报错。

经验：在项目里别把 Document 声明成全局单例。PDF 生成本质是有状态的一次性流程，全局复用 Document 会导致页码错乱、内容残留。每次导出都新建一套 writer/doc 对象，用完即关，最稳。

4. 核心元素实操：段落、列表、表格、图片

Document 模式下，内容都由 Element 家族撑起来。最常用的几个：Paragraph（段落）、Table（表格）、Image（图片），还有偶尔会用到的 List（列表）。

4.1 段落和文字样式的控制

最简单的段落创建：

Paragraph title = new Paragraph("月度销售统计报表") .setFont(chineseFont) .setFontSize(18f) .setBold() .setTextAlignment(TextAlignment.CENTER);

Paragraph 可以链式调用样式方法，比 Html 的标签式书写还要直观。这里有几个容易忽略的细节：

第一，setFont方法不设置的话，iText 会使用默认字体，中文会乱码。凡是含中文的段落，一律先把字体对象塞进去。

第二，setFontSize的单位也是 pt。正文一般 10~12pt，标题 16~18pt，脚注或水印 8~9pt。这个比例关系跟 Word 里的字号是相通的。

第三，段落之间的间距用setMarginTop和setMarginBottom控制。如果不设置，多个段落会粘连在一起，视觉上分不清层级。

Paragraph subTitle = new Paragraph("统计周期：2024年01月 - 2024年06月") .setFont(chineseFont) .setFontSize(12f) .setMarginBottom(20f);

4.2 表格：iText 7 的 Table 到底怎么搭

iText 7 的 Table 设计比老版本要合理得多。它采用“先定义列宽，再往里灌单元格”的模型。

float[] columnWidths = {1, 2, 1, 2}; Table table = new Table(columnWidths); table.setWidth(UnitValue.createPercentValue(100));

这里的 columnWidths 数组，每一项表示一个相对宽度比例。上面定义了 4 列，比例 1:2:1:2，最终表格自动撑满整个可用宽度。

真正加内容的方式，是通过 Cell 对象：

Cell headerCell = new Cell() .add(new Paragraph("月份").setFont(chineseFont)) .setBackgroundColor(ColorConstants.LIGHT_GRAY) .setTextAlignment(TextAlignment.CENTER); table.addCell(headerCell);

iText 7 里，addCell是按顺序往表格里填单元格的。它会自动帮你换行、换列，你不需要自己维护行列指针。这个设计极大避免了老版本里“格子坐标算错导致内容重叠”的问题。

如果你需要合并单元格，iText 7 里要用setColspan和setRowspan：

Cell mergeCell = new Cell(1, 4) .add(new Paragraph("汇总区域").setFont(chineseFont)); table.addCell(mergeCell);

new Cell(1, 4)的第一个参数是行跨度，第二个参数是列跨度。上面这行代码表示这个单元格横跨 4 列，也就是整行。

单元格的样式设置和段落是同一套逻辑：背景色、文本对齐、边距，都是直接链式调用。表格是否会自动换页？答案是会，但默认表头不会在下一页重复。如果你想每一页都有表头，需要把表头那行的单元格单独建一个 Header 区，用Table的setHeaderRows指定头部行数，这种方法比较推荐。

4.3 图片插入与缩放参数详解

Document 模式插入图片非常“傻瓜式”，它是唯一也是全部直接用 Image 对象的场景。

Image dataImage = new Image(ImageDataFactory.create("chart.png")); float percentage = 70f; dataImage.scaleToPercent(percentage); document.add(dataImage);

scaleToPercent是等比例缩放，传 70 表示缩放为原始尺寸的 70%。这是最常用的缩略方式，但对于高分辨率图片，它有一个隐患：原图可能 4000 像素宽，缩放 20% 也远大于页面宽度，导致图片超出页面。

更严谨的用法是固定宽度缩放：

float scaledWidth = PageSize.A4.getWidth() - 72f; // 减去左右边距 float scaledHeight = dataImage.getImageScaledHeight() * (scaledWidth / dataImage.getImageScaledWidth()); dataImage.scaleAbsolute(scaledWidth, scaledHeight);

scaleAbsolute直接指定图片在 PDF 中占用的 pt 宽高。这里我先算好图片应该占多宽（A4 宽度 - 左右边距），再按原图比例算出高度。这样图片永远在页面的可用范围内，不会溢出。

图片过多时，Document会自动把溢出到下一页的图片推到新一页。但如果你是顺序插入多张图，且每张图片都已经接近页面高度，视觉上会显得一页一张图。想压缩空间，可以考虑把图片放进表格的单元格里，利用表格的排版约束。

注意：图片不要直接用本地路径的字面量写死，比如C:\xxx\chart.png。项目上线后部署在 Linux 服务器上，路径就废了。规范做法是读成 InputStream 或 byte[]，再传给ImageDataFactory.create(bytes)，或者用相对路径。我用得最多的方式是先生成图表数据到内存字节流，再直接转成 Image 对象插入，完全绕开临时文件。

5. 图像生成：不靠厂库也能输出报表配图

iText 本身并不擅长画统计图。想在你的 PDF 里带一张柱状图、折线图，常见做法是先让图表库生成图片文件（或字节流），再用前面说的 Image 把它塞进 Document。这一节我分享一条零额外系统依赖的配图路线。

5.1 用 Java 2D 绘制统计图

Java 自带的BufferedImage和Graphics2D完全可以画出足够用于报表的柱状图和折线图。好处是零第三方依赖、可控性强、部署简单。坏处是它只适合绘制相对直接的图表，要搞交互式图表或者复杂的坐标系网格就吃力了。

我给大家演示一个基础柱状图的绘制代码片段。下面是生成一组月度销售额柱状图并保存为 PNG 的示例：

int width = 600; int height = 300; BufferedImage image = new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB); Graphics2D g2d = image.createGraphics(); // 设置平滑抗锯齿 g2d.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON); // 绘制白色背景 g2d.setColor(Color.WHITE); g2d.fillRect(0, 0, width, height); // 设置坐标轴和柱子的颜色 g2d.setColor(Color.DARK_GRAY); // 在这里绘制坐标轴、柱子、文字标注等 // 具体柱状图的绘制逻辑可以根据自己的业务数据规模封装 g2d.dispose(); ImageIO.write(image, "png", new File("chart.png"));

有人会问：为什么不直接用 JFreeChart 之类的专业图表库？答案是可以，但要看需求。如果是项目里偶尔画几张配图，Graphics2D 手绘完全够用；如果是报表系统每天批量生成大量图表，建议用专业图表库封装，效率和美观度都更好。两种路线的原理都是把图表渲染成一张位图，再交给 iText 排版。

5.2 把生成的图片直接写入 PDF

图片既然已经能生成字节流，就别再落盘了。落盘意味着要处理临时目录的创建、清理、并发文件名冲突，全是麻烦。直接把图片拼成 PDF 更优雅：

ByteArrayOutputStream baos = new ByteArrayOutputStream(); ImageIO.write(image, "png", baos); Image chartImage = new Image(ImageDataFactory.create(baos.toByteArray())); chartImage.scaleToFit(500f, 200f); document.add(chartImage);

scaleToFit和scaleToPercent区别在于：scaleToFit保证图片在给定宽度和高度范围内完整显示，同时保持宽高比；scaleToPercent则是相对原图的缩放。对于图表这种有固定宽高比的内容，用scaleToFit更省心，你不用担心图形被压扁或拉伸。

5.3 第三方图表库替换方案

如果觉得手绘图表太原始，也可以在项目里集成 JFreeChart。它的用法套路是固定的：

// 创建数据集 DefaultCategoryDataset dataset = new DefaultCategoryDataset(); dataset.addValue(125000, "销售额", "1月"); // 创建图表 JFreeChart chart = ChartFactory.createBarChart( "月度销售趋势", "月份", "销售额(元)", dataset); // 输出为 BufferedImage BufferedImage chartImage = chart.createBufferedImage(600, 300);

看到没，最终还是 OutputStream 的场景。所以我对配图的建议是：报表系统初期先用 Java 2D 手绘保证不出错，后续产品设计升级了再换 JFreeChart 或者更现代的方案，不影响 PDF 构建部分的结构。

6. 完整实战：生成一份带汇总表格和统计图的销售报表

理论说了一堆，直接上一个完整的可运行示例。这个示例结合了前面所有知识点：中文段落、表格、图表、图片插入。业务场景模拟的是某销售系统导出月度销售报表。

6.1 业务需求与设计思路

需求背景：某公司销售运营每个月需要一份 PDF 报表，包含三个部分：顶部标题和统计周期的说明；中间一张汇总表，展示每月销售额和目标完成率；下半部分插入一张销售额柱状图，直观展示趋势。

我的设计思路：

• 用一个Document走完整个导出流程。
• 字体对象在方法入口处创建一次，全局复用。
• 汇总表用Table的列宽比例配置，表头单独上色。
• 柱状图用BufferedImage手工画，然后转字节流插入。
• 所有输出通过ByteArrayOutputStream返回，方便 Web 接口直接下载。

6.2 完整代码示例

import com.itextpdf.kernel.colors.ColorConstants; import com.itextpdf.kernel.font.PdfFont; import com.itextpdf.kernel.font.PdfFontFactory; import com.itextpdf.kernel.geom.PageSize; import com.itextpdf.kernel.pdf.PdfDocument; import com.itextpdf.kernel.pdf.PdfWriter; import com.itextpdf.kernel.pdf.PdfEncodings; import com.itextpdf.layout.Document; import com.itextpdf.layout.element.Cell; import com.itextpdf.layout.element.Image; import com.itextpdf.layout.element.Paragraph; import com.itextpdf.layout.element.Table; import com.itextpdf.layout.property.TextAlignment; import com.itextpdf.layout.property.UnitValue; import com.itextpdf.io.image.ImageDataFactory; import javax.imageio.ImageIO; import java.awt.Color; import java.awt.Graphics2D; import java.awt.RenderingHints; import java.awt.image.BufferedImage; import java.io.ByteArrayOutputStream; import java.io.FileOutputStream; public class ReportPdfGenerator { private static final String FONT_PATH = "src/main/resources/fonts/SourceHanSansSC-Regular.otf"; public static void main(String[] args) throws Exception { ByteArrayOutputStream baos = generateSalesReport(); try (FileOutputStream fos = new FileOutputStream("sales_report.pdf")) { fos.write(baos.toByteArray()); } System.out.println("PDF 生成完毕：sales_report.pdf"); } public static ByteArrayOutputStream generateSalesReport() throws Exception { PdfFont chineseFont = PdfFontFactory.createFont( FONT_PATH, PdfEncodings.IDENTITY_H, PdfFontFactory.EmbeddingStrategy.PREFER_EMBEDDED); ByteArrayOutputStream output = new ByteArrayOutputStream(); PdfWriter writer = new PdfWriter(output); PdfDocument pdf = new PdfDocument(writer); Document document = new Document(pdf, PageSize.A4); document.setMargins(36f, 36f, 36f, 36f); pdf.getDocumentInfo().setTitle("月度销售统计报表"); pdf.getDocumentInfo().setAuthor("销售运营系统"); pdf.getDocumentInfo().setCreator("ReportPdfGenerator"); pdf.getDocumentInfo().setSubject("月度销售统计"); // 1. 标题 Paragraph title = new Paragraph("月度销售统计报表") .setFont(chineseFont) .setFontSize(18f) .setBold() .setTextAlignment(TextAlignment.CENTER) .setMarginBottom(8f); document.add(title); // 2. 统计周期说明 Paragraph period = new Paragraph("统计周期：2024年01月 - 2024年06月") .setFont(chineseFont) .setFontSize(11f) .setTextAlignment(TextAlignment.CENTER) .setMarginBottom(20f); document.add(period); // 3. 汇总表 float[] columnWidths = {2, 2, 2, 2}; Table table = new Table(columnWidths); table.setWidth(UnitValue.createPercentValue(100)); String[] headers = {"月份", "销售额(万元)", "目标完成率", "备注"}; for (String header : headers) { Cell headerCell = new Cell() .add(new Paragraph(header).setFont(chineseFont)) .setBackgroundColor(ColorConstants.LIGHT_GRAY) .setTextAlignment(TextAlignment.CENTER); table.addCell(headerCell); } String[][] data = { {"1月", "85.2", "96%", "正常"}, {"2月", "92.6", "105%", "春节促销"}, {"3月", "88.4", "100%", "正常"}, {"4月", "97.1", "110%", "新品上市"}, {"5月", "76.8", "87%", "促销空档期"}, {"6月", "102.3", "116%", "年中冲刺"} }; for (String[] row : data) { for (String cellText : row) { Cell cell = new Cell() .add(new Paragraph(cellText).setFont(chineseFont)) .setTextAlignment(TextAlignment.CENTER); table.addCell(cell); } } document.add(table); // 4. 图表配图 document.add(new Paragraph("销售额趋势图") .setFont(chineseFont) .setFontSize(14f) .setBold() .setMarginTop(20f) .setMarginBottom(10f)); Image chartImage = createSalesChartImage(chineseFont); chartImage.scaleToFit(460f, 200f); document.add(chartImage); // 5. 尾部脚注 document.add(new Paragraph("统计口径：实际回款金额，不含税。") .setFont(chineseFont) .setFontSize(9f) .setMarginTop(16f) .setFontColor(ColorConstants.GRAY)); document.close(); return output; } private static Image createSalesChartImage(PdfFont font) throws Exception { int width = 600; int height = 300; BufferedImage bufferedImage = new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB); Graphics2D g2d = bufferedImage.createGraphics(); g2d.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON); g2d.setColor(Color.WHITE); g2d.fillRect(0, 0, width, height); int[] sales = {85, 92, 88, 97, 77, 102}; String[] labels = {"1月", "2月", "3月", "4月", "5月", "6月"}; int barWidth = 60; int gap = 25; int baseY = 240; int maxHeight = 160; int maxSale = 120; for (int i = 0; i < sales.length; i++) { int barHeight = (int) ((float) sales[i] / maxSale * maxHeight); int x = 60 + i * (barWidth + gap); g2d.setColor(new Color(70, 110, 180)); g2d.fillRect(x, baseY - barHeight, barWidth, barHeight); g2d.setColor(Color.BLACK); g2d.drawString(String.valueOf(sales[i]), x + 10, baseY - barHeight - 5); g2d.drawString(labels[i], x + 10, baseY + 20); } g2d.drawLine(45, 240, 540, 240); g2d.dispose(); ByteArrayOutputStream chartBytes = new ByteArrayOutputStream(); ImageIO.write(bufferedImage, "png", chartBytes); return new Image(ImageDataFactory.create(chartBytes.toByteArray())); } }

这段代码直接跑，就能生成一份包含标题、汇总表、柱状图和脚注的 A4 报表。我在测试环境跑过完整的生成流程，输出文件用系统自带 PDF 阅读器打开，显示正常，中文没有乱码，图表位置也正好落在表格下方。

6.3 关键代码逻辑解读

有人可能注意到我画柱状图时用到了drawString，这是在图片上直接写字。图片上的字体渲染用的是 Java 2D，它默认从系统字体里解析字形，所以我们在 iText 里配的中文字体文件不会影响图片上的文字。这一点是两种体系，别混在一起。

代码里柱状图绘制的几个关键坐标：

• baseY = 240是柱子的基线（即横向坐标轴的 y 坐标）
• maxHeight = 160是最高柱子的像素数
• x = 60 + i * (barWidth + gap)代表第 i 根柱子的左上角 x 坐标
• 柱子高度通过sales[i] / maxSale * maxHeight换算为像素

如果你后续要画折线图、饼图，思路完全一样：通过 Graphics2D 画形状、画连线、写标签，最后输出成图片即可。这套思路能覆盖 80% 的报表配图需求。

7. 中文字体导致的乱码排查与处理方案

中文字体问题，是 iText 所有问题里的“一哥”。这篇既然是实战向，我就干脆把我在真实项目里遇到过的每一条乱码根因和对应的处理结果整理成一张表，省得你排查半天。

7.1 中文字体乱码的根因速查表

7.2 字体加载的两种路径，推荐 classpath

我看到很多同事把字体路径写成绝对路径C:/fonts/xx.ttf，本地测试好好的，一上 Linux 服务器就崩。原因很简单：服务器上没有这个文件。

规避方式有两种。一种是把字体文件放在src/main/resources/fonts下，用 classpath 加载：

ClassPathResource resource = new ClassPathResource("fonts/SourceHanSansSC-Regular.otf"); PdfFont chineseFont = PdfFontFactory.createFont( resource.getInputStream().readAllBytes(), PdfEncodings.IDENTITY_H, PdfFontFactory.EmbeddingStrategy.PREFER_EMBEDDED );

看到readAllBytes()了没？iText 7 的createFont支持直接接收 byte[] 字体数据。这个方法最省心，因为字体文件已经被打包进 jar 包里，永远不会丢失。

另一种是在配置文件里维护字体路径，不同环境用不同配置文件。这种灵活度高，但增加了运维成本，中小项目没必要。

7.3 字体子集的优化技巧

嵌入中文字体完整的 OTF/TTF 文件会导致 PDF 非常大，一份几页的报告可能涨到十几 MB。iText 支持字体的子集化，即只嵌入文档中实际用到的那些字形，可以显著压缩体积。

在 iText 7 里，PdfFontFactory创建字体时支持传入一个FontProgram参数，然后通过fontProgram.setFontSpecificities做子集控制。更常用的做法是使用 iText 的PdfFontFactory.createFont之后不做额外设置，让 iText 默认按需子集化。

我实测过一份带图表且包含两三百个不同汉字的报表，不设子集化时 PDF 约 8 MB，开启子集化后降到约 400 KB。如果你们的系统导出的 PDF 数量大，这绝对值得关注。

8. 常见问题与排查技巧实录

最后这部分，是把我在项目里真实踩过、帮别人排查过的典型问题集中整理出来。不少问题藏得比较深，网上也很难搜到现成答案。

8.1 PDF 打不开或提示文件损坏

在没调用document.close()的情况下，程序异常退出，生成的 PDF 是不完整的。这是最常见的原因。排查思路：

用文本编辑器直接打开 PDF 文件，看末尾是否有关键的%%EOF标记。如果文件末尾没有%%EOF，说明写入流程没有正常结束。

解决方法是确保 close 放在 finally 或 try-with-resources 中。同时，代码逻辑不要过于复杂以至于在写文件时抛出未知异常。

8.2 图片插入后变形

如果你用scaleAbsolute手写了宽高，又刚好写死了和原图不成比例的尺寸，那图必然被拉变形。变形问题的根源是宽高比失衡。

处理方式：使用scaleToFit而非scaleAbsolute；如果一定要固定宽度，那就根据原始比例算高度，像我在第 4.3 节做的那样。

8.3 表格跨页时表头不重复

报表只有第一页有表头，后面的页没有，阅读体验很差。iText Table 对象提供了setHeaderRows方法：

table.setHeaderRows(1);

这一行代码会让表格第一行在每一页顶部自动重复显示。注意：至少要在添加完表头行的单元格后再调用这个方法，否则 iText 不知道哪一行算表头。

8.4 单元格内容溢出或换行异常

Cell 默认会自适应高度，但当你设置过固定高度setHeight后，内容超出时不会自动撑高，而是溢出或裁切。多数情况建议不要给 Cell 设置固定高度，宁可让它自然撑开。如果必须限制高度，用setMaxHeight配合自动换行，效果更好。

8.5 并发导出时的线程安全问题

iText 的 Document、PdfWriter 都不是线程安全的。如果你的系统用线程池批量生成 PDF，切记每个线程创建自己独立的 Document 实例，不要在多个线程间共享同一个 PdfFont 对象或表头 Template。PdfFont 理论上是只读的，可以复用，但保守起见，复杂度高的场景还是每次生成 PDF 时创建新字体实例。

8.6 iText 5 与 iText 7 的思维换挡

如果你之前用的是 iText 5，换到 7 时，最需要改变的习惯有两个。

第一，包路径变了。5 的类都在com.itextpdf.text.*下，7 的类按模块分散在com.itextpdf.kernel、com.itextpdf.layout、com.itextpdf.io等包下。

第二，对象模型变了。5 的Paragraph和Chunk体系被 7 的Paragraph+Text体系取代了一些用法。比如 5 里给某几个字单独设置颜色，要拆 Chunk；7 里直接new Text("文字").setFontColor(...)然后paragraph.add(text)。

如果是新项目，我建议直接学 7（或者 8）。老项目的维护，继续看 5 也没有问题，但不要用 5 的思维写 7 的代码，那些com.itextpdf.text.*的 import 在 7 里根本不存在。

9. 这段实操最值得记住的三个经验

如果你时间紧只能记住三件事，那就是这三件。

第一，中文不乱的铁律是“字体文件 + IDENTITY_H”。两者缺一不可，路径别写绝对路径，字体文件放 classpath。这是 iText 中文稳定性的基石。

第二，生成 PDF 用的所有图片、图表，最终都以字节流喂给ImageDataFactory.create。图片不落盘，过程更安全，逻辑更简洁，也方便将来接入对象存储或消息队列。

第三，Document 模式把“排版”这件繁琐的事情封装得非常好，你只管准备内容顺序和样式参数，不用管坐标、换页、缩进。但不要因此就不理解它底层的 PdfWriter 与 PdfDocument 是怎么工作的。当你需要自定义页眉页脚、水印、加密时，底层知识就是你唯一的武器。

我在构建这套代码时，开发阶段花在调中文乱码和图片变形上的时间，远比写业务逻辑的时间多。而这些问题一旦理解透，之后所有 PDF 导出需求基本都能顺手完成。

这份示例代码你拿来改改就能用。后续如果想继续深入，可以按这个顺序进阶：给 PDF 加页眉页脚和页码，给 PDF 设置访问密码和权限，用 iText 在已有 PDF 上做表单填充。每个方向都有很多可以展开的细节，但底层思路始终是统一的：内容分块，排版交给 Document，特殊能力靠底层 API。