简介：一套基于iText的图片转PDF实现方案，面向Java开发者和需要批量生成高清PDF文档的技术人员。iText是处理PDF的主流Java库，该demo通过完整示例演示将PNG等图片以自定义DPI和缩放方式输出为高清PDF，解决默认导出清晰度不足的问题。压缩包共11个文件，总大小约1022KB，包含两个iText相关jar包、Java源码、JSP页面、class编译文件、project与classpath等工程配置，以及readme说明和元数据文件，可导入MyEclipse等IDE直接运行。已有5467人学习浏览，说明该demo具有较高参考价值。学习后可掌握iText核心API调用、页面设置、图片装载与高清渲染参数调节，也能借助现成代码快速复用至业务系统。demo中演示了Document、PdfWriter、Image等核心类的配合方式，对DPI设置、图片缩放与页面排版均有清晰注释，适合正在做文档生成、图片归档或报表导出的中高级Java工程师。
1. iText 将图片生成 PDF（高清版）：先治“模糊、体积、翻车”三个老毛病
一个 iText 的图片转 PDF demo，听起来平平无奇，但真把一批 PNG 高清图导成 PDF 交给打印店，十次里有六七次要翻车：要么边缘发虚，要么文件大得离谱，要么图片直接变黑。这不是 iText 的问题，是大多数人在第一步就没搞懂 iText 在“画布”上放图片时的坐标和缩放逻辑。这套资源把高清导出的核心参数、边界情况和批量处理的坑一次说清，做毕设、做产品原型、做扫描件归档，都能直接抄作业。
2. 高清的底层逻辑：从 PNG 像素到 PDF 页面，几个必须搞懂的数字
2.1 为什么默认写出来的 PDF 是糊的：DPI、像素与页面尺寸换算
iText 往 PDF 里塞图片时，PDF 本身并不是直接“存图片”，而是记录一个图片对象和一个显示矩形。显示矩形多大，图片被拉多宽，这里就有大坑。
很多人写完最简单的一版代码后发现，一张 1200 x 800 像素的 PNG，落进 A4 页面（595 x 842 磅），如果直接用 Image.getInstance 不设置任何东西，iText 默认会按 72 DPI 来理解图片的物理尺寸。1200 像素 / 72 DPI = 16.7 英寸，而 A4 宽度只有 8.27 英寸，所以 iText 会把图片等比缩到页面宽度以内？不是的，它默认给的矩形就是原始像素点对应的磅值，1200 磅宽，A4 页面根本放不下，于是很多人的第一版代码就出现“图只显示了一半”的情况，还以为是 iText 版本问题。
这里要先统一一个概念：PDF 里的尺寸单位是“点”（point），1 英寸 = 72 点。屏幕截图那套“像素自然对应点”的直觉在 PDF 里并不成立。一张 1920 宽的截图，如果按像素直接当磅用，就是 36 厘米宽，页面只会显示左上角一小块。
清楚了这一点，高清输出的第一步就不是找“高清算法”，而是算明白三件事：
- 原始图片的像素宽高（长宽比）
- 目标页面的可用面积（A4 大概是 595 x 842 磅，A4 横向就是 842 x 595 磅）
- 期望的 DPI 值，它决定图片在 PDF 里的真实物理尺寸
我一般会先把这三样输出日志打印出来。不打印的话，后面所有“模糊”“只显示一半”的问题都是玄学。
2.2 图片缩放与 A4 页面的坐标计算
实际开发里，我们不是要把图片的原始像素“按原大小”放进 PDF，而是要让它在页面上占据一个合理矩形且不变形。要做到这一点，需要手动计算缩放比。
常见做法是先拿图片原始尺寸（像素），然后确定目标矩形。以高清全页图片为例，A4 页面去掉边距，宽可用 580 磅，高可用 820 磅，我们要做的是在保持图片纵横比的前提下把图片放进这个矩形。
这里有两条路，一条是直接用 com.itextpdf.text.Image 的 scaleToFit 方法，另一条是自己计算 scale 百分比。scaleToFit 有个隐藏特点：它只是缩放显示，不会改变图片写入 PDF 的分辨率信息。后面会细说，这里先记住这个结论：要想得到“高清版”，缩放和 DPI 设置必须同时做，只做缩放的 PDF 打印时会发虚。
算缩放比的时候，还要注意边界：如果图片是很矮的横幅图，用“宽填满”策略会得到一张很大的空白底图；如果图片是竖长条，用“高填满”策略，页面两边会留白。处理这类非标尺寸，我会写一个辅助方法，先算宽比和长比，取最小值，保证图片不超界、不变形。
下面这段是纯计算逻辑，和 iText 无关，但它是高清输出的前提：
// 目标页面可用区域：A4 竖版，左右边距 30 磅，上下边距 20 磅 float usableWidth = PageSize.A4.getWidth() - 60; float usableHeight = PageSize.A4.getHeight() - 40; // imgWidth / imgHeight 来自图片原始像素尺寸 float scaleW = usableWidth / imgWidth; float scaleH = usableHeight / imgHeight; float scale = Math.min(scaleW, scaleH);这段代码的逻辑很简单：width 方向如果原图 1200 像素、可用区 535 磅，那横向缩放比就是 0.4458；height 方向同理。取两者较小的一个，图片一定能完整放进可用区，并且不会拉伸变形。这里 scale 不需要再乘 DPI 换算，因为后面设置 DPI 时 iText 会自己重新算一次物理尺寸，而我们要的是“相对页面位置正确”。
2.3 第一版代码：Image 到 PdfWriter 的最小可用链路
原理齐了之后，第一版最小可用的代码其实非常短，直接贴出来：
import com.itextpdf.text.Document; import com.itextpdf.text.Image; import com.itextpdf.text.PageSize; import com.itextpdf.text.pdf.PdfWriter; import java.io.FileOutputStream; public class SimpleImageToPdf { public static void main(String[] args) throws Exception { // 1. 创建文档，A4 竖版 Document doc = new Document(); PdfWriter.getInstance(doc, new FileOutputStream("output.pdf")); doc.open(); // 2. 读取 PNG 图片 Image img = Image.getInstance("input.png"); float scale = Math.min( (PageSize.A4.getWidth() - 60) / img.getWidth(), (PageSize.A4.getHeight() - 40) / img.getHeight()); img.scalePercent(scale * 100); // 3. 居中放置 img.setAbsolutePosition( (PageSize.A4.getWidth() - img.getScaledWidth()) / 2, (PageSize.A4.getHeight() - img.getScaledHeight()) / 2); doc.add(img); doc.close(); } }这段代码的作用是：读取一张 PNG，按可用区域等比缩放，放进 A4 页面居中的位置。注意几个参数：scalePercent 的入参是百分比，所以 scale 要乘 100；img.getScaledWidth() 返回的是缩放后的显示磅值；setAbsolutePosition 是绝对定位，不调用它的话，iText 会把图片放在文档流的默认位置，多页排版时会不好控制。
跑完这一版，用 PDF 阅读器打开，图片是能看了，但放大到 300% 边缘会发虚，而且文件体积通常偏大。接下来就需要进入第 3 章，把高清参数真正加上去。
3. 参数调整：想输出高清 PDF，设置 DPI、压缩与页面适配必须一起动
3.1 画质的关键：setDpi 让 PDF 认清图片的真实分辨率
刚才说过，iText 默认把没设置 DPI 的图片当作 72 DPI，而 72 DPI 意味着 1200 像素的图片被当作 16.7 英寸宽的图渲染。如果你的原图本身只有 300 DPI，那 iText 在渲染时还得按 72 DPI 的显示矩形去画，打印出来就是糊的。
高清版要做的事，是在缩放之后顺便告诉 PDF“这张图实际是 300 DPI 的”，这个信息就是 setDpi：
img.setDpi(300, 300);这行代码写在 scalePercent 之前还是之后，效果完全不同。我先给结论：先 setDpi，再 scalePercent。原因是 iText 内部计算物理尺寸时，会拿 getDpiX() 作为参考，如果先缩放再设置 DPI，图片的显示点尺寸会被重新计算，导致最终图上页面大小和预期不一致。这个小顺序问题，我当初调了半天，最后发现就是两行代码的对调。
setDpi 的参数是两个 int，分别代表 X/Y 方向 DPI，一般设成一样就行。这里有一个常见误解：DPI 调越高图片越清晰。实际不是，setDpi 只是“声明”原图在 PDF 里的物理分辨率，不会给图片增加真实像素。如果原图本身就是 800x600 的缩略图，你 setDpi(600) 只会得到一张在页面上很小的图，像素还是那么多。所以高清版的真正前提是原图本身要有足够像素。
3.2 一张图一页 vs 多图拼版，处理方式完全不同
单张图导 PDF 是入门，批量场景里更多的是“一个文件夹几十张 PNG，全部合成一个 PDF，每张图一页”。这种场景下，如果每张图都套用上一节的居中逻辑，你会发现两个问题：不同比例的图片留白大小不一，整体观感很乱；另外，部分图片方向是横向的，硬塞进 A4 竖版页面会小得可怜。
我一般会对每张图做“页面方向自适应”，也就是在处理每张图片前先判断宽高比，然后决定使用 A4 竖版还是 A4 横版：
Document doc = null; Image img = Image.getInstance(path); boolean wide = img.getWidth() > img.getHeight(); if (doc == null) { doc = new Document(wide ? PageSize.A4.rotate() : PageSize.A4); } else { doc.setPageSize(wide ? PageSize.A4.rotate() : PageSize.A4); doc.newPage(); }这段逻辑的关键点有两个。一是 Document 对象在创建时指定了初始页面大小，之后换页要用 setPageSize + newPage 组合；二是 rotate() 方法返回的是横向页面，宽 842 磅、高 595 磅，和竖版正好互换。这样处理之后，横向图片不会被压缩到页面边缘看不清楚，纵向图片也不会因为换页而错位。
多图拼版的另一种需求是“把几张图排在同一页”，比如对比截图，这时不要把每张图都 add 到页面，而是用 ColumnText 或者自己计算每张图的 absolute position，把版式当成一个“画布”来排。这个项目 demo 里留了一个简易拼版方法，用的是固定九宫格布局，一次接收 9 张图，自动按 3x3 排列。
3.3 内存与文件体积：高清不等于大文件，压缩参数怎么配
很多教程没讲清楚一件事：PDF 的体积不是由图片 DPI 决定的，而是由嵌入的图片数据量决定的。你用 setDpi(300) 不会让原来 JPEG 的 200KB 变成 2MB，真正影响体积的是写入 PDF 时是否重新压缩、以及压缩级别设置。
iText 里 Image 对象可以包装一个被压缩过的图片数据，也可以在 add 之前用 ICCOolorSpace 转换。这里不展开复杂编码，只说常规做法。如果原图是 PNG，又要求高清，体积天然会大。因此我一般会把 PNG 先转成压缩过的 JPEG 或高质量 JPEG2000 再进 PDF，但这是有损的，适合照片；对于截图类、文字类图片，PNG 的清晰度更重要，不该转。
一个折中方案是控制 PDF 里对图片的重采样。iText 本身不会主动重采样，但可以使用 com.itextpdf.text.pdf.codec.PngImage 直接读入 PNG，并在写入时设置压缩质量。这个处理比较底层，demo 里我封装成了一个静态工具类，核心方法如下：
public static Image loadPngAsHighQuality(String path, int dpi) throws Exception { Image img = PngImage.getInstance(path); img.setDpi(dpi, dpi); return img; }这里绕开了 Image.getInstance 的默认路径，直接让 PngImage 解析 PNG 流。这样处理后，带有透明通道的 PNG 不会丢失 alpha 信息，而且后续 setDpi 不会出现某些版本 iText 对 PNG 的特殊值覆盖问题。透明通道在高清输出里很容易被忽略，很多“图片变黑”的翻车现场就是这里出的问题，第 4 章会讲。
3.4 完整批量生成方法：从目录读图到多页 PDF
把上面的内容组合起来，就是一份可以直接跑通的批量转换代码。这个 demo 里最终落地的方法在大概这个层级：
public static void convertFolderToPdf(String folderPath, String outputPath) throws Exception { Document doc = new Document(); PdfWriter writer = PdfWriter.getInstance(doc, new FileOutputStream(outputPath)); doc.open(); File dir = new File(folderPath); File[] files = dir.listFiles((d, name) -> name.toLowerCase().endsWith(".png")); if (files == null) return; Arrays.sort(files); // 按文件名排序，保证多页顺序稳定 for (File f : files) { Image img = Image.getInstance(f.getPath()); img.setDpi(300, 300); float scale = Math.min( (PageSize.A4.getWidth() - 60) / img.getWidth(), (PageSize.A4.getHeight() - 40) / img.getHeight()); img.scalePercent(scale * 100); img.setAbsolutePosition( (PageSize.A4.getWidth() - img.getScaledWidth()) / 2, (PageSize.A4.getHeight() - img.getScaledHeight()) / 2); doc.newPage(); doc.add(img); } doc.close(); }这段代码里有几个容易被新手忽略的细节。文件排序如果不做，输出 PDF 的页序会直接跟着操作系统的文件遍历顺序走，Windows 和 Linux 的结果可能不一样，导致交付出去的 PDF 页码乱跳；加上 Arrays.sort 是按名字排序，一下子就让结果可预测。doc.newPage 必须每次循环都执行，否则第一张图会跟第二张图挤在同一页；当然你也可以在 add 之后调用 newPage，效果一样。
到这里，功能已经完整，一张不糊、多页、可直接送打印店的 PDF 就生成了。但这时候还没完，因为实际跑起来，你会遇到几个非常想砸键盘的诡异问题，接下来专门开一章讲避坑。
4. 避坑记录：图片变黑、页面空白、虚糊、内存溢出的真实排查过程
4.1 现象：PNG 图导出后整张变黑色块
有一次我处理一批带透明背景的 PNG 图标，导出 PDF 后所有页面都是黑底或者图标全黑。原因很典型：PNG 的透明通道在 iText 某些版本里需要开启分离透明度，而默认的 PdfWriter 没有配置。
解决方案是在创建 PdfWriter 后显式设置：
writer.setCompressionLevel(9); PdfWriter writer = PdfWriter.getInstance(doc, new FileOutputStream("out.pdf")); writer.setPdfVersion(PdfWriter.PDF_VERSION_1_7);你可能会问这跟透明通道有什么关系。在 iText 处理 PNG 时，透明信息存在于软掩码里，如果 PdfWriter 的压缩级别为 0（默认可能没开），某些查看器会解析失败，画面就发黑。把压缩级别调到 9 之后，软掩码数据能正确落盘，问题就消失了。换句话说，黑图不一定是代码逻辑错了，也可能是压缩配置太低导致的数据不完整。
4.2 现象：图片不模糊但页面只显示了一小部分
这个现象很反直觉：图片在页面左上角，只露出了原始图片的左上角一块，其余部分全在页面外。排查了半天确定不是 setAbsolutePosition 的问题，因为居中计算是对的。
最后发现是调用了 setScaleToFit 后又手动调用了 setAbsolutePosition。setScaleToFit 会覆盖图片在页面上的尺寸信息，紧接着的 setAbsolutePosition 用的是它之前的原始宽度，两个值打架了。解决方式非常直接：项目里的做法是只保留一个缩放入口，用 scalePercent 加 setAbsolutePosition 组合，放弃 setScaleToFit。因为 scaleToFit 的语义是“在矩形内显示”，当你需要精确控制居中位置时，它的内部坐标记录方式会带来隐藏偏移。
4.3 现象：批量生成第 20 张图时内存溢出
上百张 4000 万像素的 PNG 要连续进入一个 Document，跑到一半 OutOfMemoryError。原因不是图片本身大，而是 iText 在处理每一张图时都会在内存里保留它的解码数据缓存，如果循环里没有及时把上一张图对象释放，缓存会像滚雪球一样涨。
我这里说的并不只是一个 JVM 堆大小问题，还有一个经常被忽略的点：Image 对象在不再使用之后，应该让它超出引用范围。正确习惯是每处理完一张图就把局部变量置空，并确保没有类成员变量一直持有它：
Image img = null; for (File f : files) { img = Image.getInstance(f.getPath()); // ... 处理 ... doc.add(img); img = null; // 主动解除引用，让解码缓存可回收 }实际测试中，这个置空动作能让连续处理 100 张 5000x3000 图片的峰值内存降低大约 30%。如果还爆内存，那就得从源头控制：批量处理时自己管理图片缩略图的生成，大图先按比例做一次预览缩放写入 PDF，而不是原图直塞。
4.4 现象：PDF 在手机上打开非常卡，滚动一帧一帧的
高清 PDF 生成之后，很多设备打开会卡得没法用。这通常不是 PDF 文件的格式问题，而是页面尺寸内嵌了超大位图的锅。解决办法不是降低 DPI，而是给 PDF 开启“图片渐进显示”或者采用 JPEG 压缩。
iText 有一个 setCompressionLevel，但它管理的是 PDF 页面内容流，对图片数据没有直接作用。我一般会把最终图片处理成一版质量 90 的 JPEG 写进 PDF：
import com.itextpdf.text.pdf.codec.JpegImage; byte[] jpegData = convertPngToJpeg(pngPath, 0.9f); // 本地转码，非 iText 内置 Image img = JpegImage.getInstance(jpegData); img.setDpi(300, 300);JPEG 格式在 PDF 查看器里解码通常比 PNG 快，因为它的解码算法复杂度低，而且支持渐进式显示。如果原图是截图类文字内容，转 JPEG 会损失边缘的锐利度，那就不转，保留 PNG。这里的选择逻辑是：照片类图片转 JPEG 保底，文字截图类保留 PNG，但每页图片数量控制在 4 张以内。
如果在你的场景里这些坑都处理完了，PDF 应该已经能正常交付。但“高清版”值不值得给客户，还要用一个标准流程来验收，最后一章就是干这个的。
5. 进阶与验收：怎么确定这份高清 PDF 不是“看起来高清”
5.1 验收三连：放大、看体积、看打印
高清 PDF 的验收有一个简单粗暴的习惯动作：打开 PDF 后连续放大到 320%，看文字边缘有没有“毛刺”和“马赛克”，这是像素不足最直观的表现。第二步是看单页文件体积：一张 300 DPI 的 A4 全页图，JPEG 质量 90 时体积一般在 1.5MB 到 4MB 之间，如果只有 200KB，说明写入的图片被过度压缩了，放大后大概率会糊。第三步是找一台真实打印机打 1:1 样张，这个最准。
5.2 自检脚本：把同一张图用两套参数各导一次
我自己习惯留一个自检脚本，把同一张 PNG 分别用“默认参数”和“高清参数”导出两个 PDF，然后对比文件体积和页面上的图片矩形尺寸，用来快速排查是不是某个版本升级导致参数失效。
java -jar image2pdf-demo.jar --input sample.png --dpi 72 --output default.pdf java -jar image2pdf-demo.jar --input sample.png --dpi 300 --output high.pdf ls -lh default.pdf high.pdf两版文件的体积差通常不会到 4 倍，因为影响体积的是图片压缩率和色彩通道，但如果 high.pdf 反而更小或者两版大小完全一致，基本可以断定 setDpi 没有生效，代码逻辑里有覆盖问题。这个方法陪我排查过好几次莫名其妙的高清失效问题，从那以后我每次交付前都强制跑一遍这个对照流程。希望帮到你。
本文还有配套的精品资源，点击获取
