1. 项目整体思路拆解需求到底是什么先说一个容易被低估的事实把多张图片合并成PDF看起来只是调个接口、写个循环的事但实际落地时你会发现真正的问题全藏在细节里——图片尺寸不一、内存占用、PDF文件体积失控、图片方向错乱、透明通道变黑底……哪一个都能让你本来半小时能跑完的活儿变成一整天的返工。这个项目的核心需求可以拆成三层第一层最基本的输入输出。给定一组图片可能是JPG、PNG也可能混合按指定顺序合并成一个PDF文件每一张图片占用PDF的一页。这是所有方案的共同底线。第二层工程化约束。图片数量可能是几张也可能是几千张图片来源可能是本地文件、Base64字符串、远程URL输出的PDF需要控制体积不能一张高分辨率照片直接变成几十MB的怪兽文件内存占用要可控不能在处理百张以上的图片时直接把堆内存吃满。第三层体验与扩展。最终使用者可能希望每页图片自适应铺满页面、希望在图片之间插入空白页或自定义页眉页脚、希望图片按指定尺寸摆放比如证件扫描件要保证物理尺寸一致。这些需求会直接影响技术选型。从技术方案上看Java生态里能实现图片转PDF的主流路径有三个iText系列iText 5、iText 7、Apache PDFBox、以及OpenPDF。我在实际项目里三个都试过简单说下取舍逻辑。iText功能最强对图片压缩、页面布局、字体嵌入的控制粒度最细但iText的AGPL授权对很多公司来说是个绕不开的坎——除非你愿意把项目开源或者购买商业授权。OpenPDF是iText 4的社区分支授权相对宽松但功能停留在比较老的形态遇到特殊需求时文档少、扩展也麻烦。PDFBox是Apache基金会的项目Apache 2.0许可完全不用操心授权问题对图片PDF这种基础需求支持得很稳唯一的缺点是API没有iText那么高冷好用但胜在逻辑清晰、调试容易。这个项目我用的是PDFBox理由很简单图片转PDF本身就是PDFBox的看家功能之一它把创建文档—添加图片页—写入文件的过程封装得足够干净同时没有授权风险。如果你的项目只是把图片合并成PDF没有太多花哨的排版需求PDFBox是性价比最高的选择。也许你会问为什么不用更简单的方案比如直接用命令行工具如果你在服务器上手动执行一次用工具确实快但如果这个能力要被集成到Web应用里、被不同的用户以不同的参数反复调用就必须有一个程序化的实现。这才是这个项目的题中之义——把能力沉淀成代码而不是依赖人工操作。2. 核心细节解析从图片读取到PDF生成的每一步2.1 图片读取策略按需加载别一口气全塞进内存最容易踩的坑就是写代码的时候图省事先把所有图片全部读进BufferedImage列表再遍历生成PDF。图片少比如十张以内一点问题没有但一旦超过三五十张每张又是三四MB的手机照片原图内存直接就爆了。我见过一个真实案例某开发者在Windows本地测得好好的一上Linux服务器处理两百张图片就OOM就是吃了这个亏。正确策略是边读边写一次只处理一张图片写完一页就释放引用。try (PDDocument document new PDDocument()) { for (File imageFile : imageFiles) { BufferedImage image ImageIO.read(imageFile); PDPage page new PDPage(PDRectangle.A4); document.addPage(page); PDImageXObject pdImage LosslessFactory.createFromImage(document, image); try (PDPageContentStream contentStream new PDPageContentStream(document, page)) { contentStream.drawImage(pdImage, 0, 0, pageWidth, pageHeight); } // 关键主动释放当前图片引用让GC尽快回收 image.flush(); } document.save(outputPath); }image.flush()这一行很多人会忽略。BufferedImage的像素数据存在Java堆外或者说由ImageIO内部管理flush之后可以释放内部缓冲区虽然不保证立刻回收但至少给了GC明确信号。处理大批量文件时这行代码能让内存曲线平稳不少。2.2 页面尺寸与图片适配图片铺满页面但不裁切每张图片都要单独建一个PDPage。这里有个设计决策页面尺寸怎么定两种常见策略。第一种固定页面大小A4、Letter等图片等比缩放后居中绘制页面统一、适合打印场景。第二种每页的尺寸跟随图片自身的宽高比生成画册式PDF文件打开时每页大小不一。实际项目中绝大多数需求都是第一种——尤其是要做成电子档案或打印输出时统一的页面尺寸更符合预期。但直接在drawImage时把图片拉伸到整个页面会改变图片比例人脸会变形表格线会歪。正确做法是按比例缩放计算出图片在页面内的实际绘制区域。假设页面尺寸为宽pageW、高pageH图片原始尺寸为宽imgW、高imgH缩放比例取Math.min(pageW / imgW, pageH / imgH)这样图片在保持比例的前提下至少在一个维度上铺满页面然后居中绘制。float scale Math.min(pageW / imgW, pageH / imgH); float drawW imgW * scale; float drawH imgH * scale; float x (pageW - drawW) / 2; float y (pageH - drawH) / 2; contentStream.drawImage(pdImage, x, y, drawW, drawH);再补一个更贴合真实需求的设计如果希望图片在页面上留一点边距可以把pageW和pageH先扣除两侧边距再参与计算。比如左右各留20磅那么实际可用宽度就是pageW - 40。这种细节在实际产出中很能体现差异。2.3 图片格式与色彩模式透明底、CMYK这些坑怎么填ImageIO在读取JPEG和PNG上基本没问题但有两个高频问题需要特别注意。第一PNG透明背景。PDFBox在LosslessFactory.createFromImage转换带Alpha通道的BufferedImage时透明部分有可能变成黑色。这是因为PDF本身支持透明但绘制方式和渲染器的兼容性参差不齐。稳妥的做法是先把带透明的图片绘制到一张白色底的RGB画布上再做转换。BufferedImage rgb new BufferedImage(src.getWidth(), src.getHeight(), BufferedImage.TYPE_INT_RGB); Graphics2D g rgb.createGraphics(); g.setColor(Color.WHITE); g.fillRect(0, 0, src.getWidth(), src.getHeight()); g.drawImage(src, 0, 0, null); g.dispose();第二某些JPEG是CMYK色彩模式。ImageIO在部分JDK版本下读取这种图片会直接抛异常甚至导致整个进程异常退出。如果业务中无法避免上传这种图片一个可靠的兜底方案是用工具库做色彩空间转换。建议在读取图片时使用ImageReader并设置ImageReadParam或者干脆对异常图片做二次处理先通过Toolkit.createImage或者第三方库解析成RGB再继续。2.4 图片方向问题为什么手机拍出来的照片是歪的这是我在实际项目中踩过最深的一个坑。手机拍摄的照片尤其是iPhone和一些Android机型JPEG文件里会写入EXIF信息其中Orientation字段标识了拍摄时的设备方向。但ImageIO.read()返回的BufferedImage已经丢掉了EXIF信息直接把这张图写进PDF出来的效果就是竖着拍的图在PDF里横躺着。解决思路有两种。简单粗暴的读取EXIF中的Orientation值如果是旋转过的比如6表示顺时针旋转90度就先用AffineTransform把图片旋转回正确方向再交给PDFBox。// 用 ImageIO 的 ImageReader 提取 EXIF ImageReader reader ImageIO.getImageReadersByFormatName(jpeg).next(); reader.setInput(ImageIO.createImageInputStream(imageFile)); IIOMetadata metadata reader.getImageMetadata(0); // 从 metadata 中解析 Orientation 字段标准 Exif TIFF tag 0x0112 // 6: 旋转90度3: 旋转180度8: 旋转270度图片方向处理逻辑不复杂但它属于那种不遇到就永远不知道存在的问题。如果你的项目涉及手机图片上传这步必须提前设计好。3. 实操过程完整代码实现与参数选择3.1 工程结构与依赖配置以Maven项目为例只需要一个核心依赖dependency groupIdorg.apache.pdfbox/groupId artifactIdpdfbox/artifactId version2.0.27/version /dependency2.0.27是目前基于2.x系列的稳定版本。PDFBox 3.x也发布了但包结构和部分API有变动如果你是从老项目升级建议先在测试环境验证兼容性再切换。另外PDFBox在处理图片压缩时会依赖commons-logging一般情况下Maven会帮我帮你带入不需要单独配置。3.2 完整实现支持本地图片目录转PDF我把核心代码完整贴出来这个版本支持目录下所有图片按文件名顺序合并、自适应页面等比缩放、透明通道处理、以及基础的内存优化。import org.apache.pdfbox.pdmodel.PDDocument; import org.apache.pdfbox.pdmodel.PDPage; import org.apache.pdfbox.pdmodel.PDPageContentStream; import org.apache.pdfbox.pdmodel.common.PDRectangle; import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject; import org.apache.pdfbox.pdmodel.graphics.image.LosslessFactory; import javax.imageio.ImageIO; import java.awt.Color; import java.awt.Graphics2D; import java.awt.image.BufferedImage; import java.io.File; import java.io.IOException; import java.util.Arrays; import java.util.Comparator; public class ImageToPdfConverter { public static void convert(File imageDir, File outputPdf, float margin) throws IOException { File[] images imageDir.listFiles((dir, name) - { String lower name.toLowerCase(); return lower.endsWith(.jpg) || lower.endsWith(.jpeg) || lower.endsWith(.png); }); if (images null || images.length 0) { throw new IllegalArgumentException(目录下没有找到图片文件: imageDir.getAbsolutePath()); } // 按文件名排序保证合并顺序稳定 Arrays.sort(images, Comparator.comparing(File::getName)); try (PDDocument document new PDDocument()) { for (File imageFile : images) { BufferedImage image ImageIO.read(imageFile); if (image null) { System.err.println(跳过无法读取的图片: imageFile.getName()); continue; } // 透明PNG转白底RGB避免黑底问题 if (image.getColorModel().hasAlpha()) { BufferedImage rgb new BufferedImage(image.getWidth(), image.getHeight(), BufferedImage.TYPE_INT_RGB); Graphics2D g rgb.createGraphics(); g.setColor(Color.WHITE); g.fillRect(0, 0, image.getWidth(), image.getHeight()); g.drawImage(image, 0, 0, null); g.dispose(); image.flush(); image rgb; } // 页面大小默认A4减去边距 float pageW PDRectangle.A4.getWidth() - 2 * margin; float pageH PDRectangle.A4.getHeight() - 2 * margin; float imgW image.getWidth(); float imgH image.getHeight(); float scale Math.min(pageW / imgW, pageH / imgH); float drawW imgW * scale; float drawH imgH * scale; float x (PDRectangle.A4.getWidth() - drawW) / 2; float y (PDRectangle.A4.getHeight() - drawH) / 2; PDPage page new PDPage(PDRectangle.A4); document.addPage(page); PDImageXObject pdImage LosslessFactory.createFromImage(document, image); try (PDPageContentStream cs new PDPageContentStream(document, page)) { cs.drawImage(pdImage, x, y, drawW, drawH); } image.flush(); } document.save(outputPdf); } System.out.println(PDF生成成功: outputPdf.getAbsolutePath()); } public static void main(String[] args) throws IOException { File imageDir new File(args.length 0 ? args[0] : ./images); File outputPdf new File(args.length 1 ? args[1] : ./output.pdf); convert(imageDir, outputPdf, 20f); } }几个参数解释PDRectangle.A4是PDFBox内置的A4尺寸常量宽595磅、高842磅。1磅等于1/72英寸A4纸的物理尺寸是210mm x 297mm换算过来正是这个数值。margin控制页边距我这里默认20磅约7mm实际打印场景建议不小于10磅。排序用了Comparator.comparing(File::getName)字符串排序。如果要按拍摄时间或自定义序号排序需要自行扩展比较器。3.3 图片压缩控制PDF体积的关键把多张高分辨率图片直接塞进PDF生成的文件会大得离谱。一张4000x3000的JPEG照片不处理直接嵌入PDF体积可能在8~12MB。如果有一百张这种照片PDF就是1GB级别的怪物。PDFBox提供了一个简单有效的压缩方式用JPEGFactory替代LosslessFactory。前者会让PDFBox对图片重新编码你可以用JPEGFactory.createFromImage(document, image, quality)指定质量参数0.0f ~ 1.0f之间0.75f通常是一个视觉质量和体积的平衡点。// 替换上一版代码中的 LosslessFactory 调用 PDImageXObject pdImage JPEGFactory.createFromImage(document, image, 0.75f);压缩后单张4000x3000照片的体积能压到1.5MB以内一百张图片的PDF大约在150MB左右已经相对可接受了。但要注意JPEG是有损压缩如果业务要求图片必须无损保存比如合同扫描件、医疗影像那就不能用这个方案老老实实用LosslessFactory。还有一个可以优化的点如果图片尺寸本身远远超过页面能显示的尺寸可以在建立BufferedImage时就做缩放。比如A4纸页面满幅显示大约需要1500x2100像素的清晰度超过这个数值的图片在打印和屏幕上已经看不出区别了提前降采样能显著控制内存和PDF体积。private BufferedImage scaleToFit(BufferedImage src, int maxWidth, int maxHeight) { int w src.getWidth(); int h src.getHeight(); if (w maxWidth h maxHeight) { return src; } double scale Math.min((double) maxWidth / w, (double) maxHeight / h); int newW (int) (w * scale); int newH (int) (h * scale); BufferedImage resized new BufferedImage(newW, newH, BufferedImage.TYPE_INT_RGB); Graphics2D g resized.createGraphics(); g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BICUBIC); g.drawImage(src, 0, 0, newW, newH, null); g.dispose(); src.flush(); return resized; }实测经验在图片压缩上花费的功夫比整个PDF生成逻辑都要多。因为PDF文件的体积直接关系到后续的存储成本和传输时间这个环节省不得。3.4 目标生成一个可复用的工具类上面三段代码可以组合成一个完整的工具类。注意我把文件读取、图片预处理、缩放、压缩、PDF写入分成了独立步骤这样每个环节都能单独测试出问题时容易定位。真实项目中不建议把所有逻辑都堆在一个main方法里我之前为了赶工这么干过后续维护加需求时非常痛苦。4. 常见问题与排查技巧实录4.1 生成PDF时内存溢出OOM这是排行榜第一的问题。原因基本集中在一次性读取全部图片到内存、未释放BufferedImage、以及没有对超大图片做降采样。排查手段很简单在JVM启动参数里加-Xmx512m甚至更小复现问题看异常堆栈指向哪一行。如果是createFromImage附近基本就是图片太大或者积累太多。处理顺序是先做降采样再做单张处理最后加flush()。三个都做了几百张图片跑下来应该很稳。4.2 生成的PDF里图片模糊模糊的根源通常是两种情况一是缩放比例算错了把图片画到了比原始尺寸更大的区域二是drawImage传入的宽度高度参数用了整型截断导致比例轻微变形。检查点确认drawW和drawH与原始图片的宽高比一致确认PDF页面尺寸没有设置成过大的大尺寸。另外如果是用JPEGFactory压缩质量参数低于0.5会明显看到压缩噪点。4.3 图片旋转90度问题定位方法打开原始图片文件如果图片在系统自带查看器里正常但在生成的PDF里横过来了99%是EXIF方向信息没处理。解决方案就是前面提到的解析Orientation字段并执行对应旋转。常见Orientation值对照1为正常3为旋转180度6为顺时针旋转90度即需要逆时针旋转90度来修正8为逆时针旋转90度需要顺时针旋转90度修正。4.4 页面出现黑色或异常色块基本是Alpha通道问题。解决方式就是转白底RGB代码里已经有了。如果是CMYK的JPEG现象是颜色明显偏色或者抛异常需要引入额外的色彩转换逻辑。4.5 大文件PDF打开很慢原因通常是图片未做压缩PDF整体体积太大。上面给的JPEGFactory压缩方案可以直接缓解。另外PDFBox还支持设置document.setAllSecurityToBeRemoved()这类参数优化打开速度不过对图片型PDF帮助有限。问题可能原因解决方案OOM一次性读取过多图片、未释放资源单张处理 flush 降采样图片模糊缩放比例错误、压缩质量低检查宽高比、提高quality参数图片横向EXIF方向未处理解析Orientation字段并旋转黑色背景Alpha通道未处理绘制到白色RGB画布文件过大图片未压缩使用JPEGFactory 降采样5. 场景扩展单图片多页面、自定义排版与批量处理能力5.1 单张图片跨多页输出有些场景下一张图片非常大比如一张超长截图聊天记录、网页全页截图需要切成多页输出。思路是把图片按固定高度切片每一片生成一个PDF页面。int sliceHeight 1200; // 每页显示1200像素高度 int totalSlices (image.getHeight() sliceHeight - 1) / sliceHeight; for (int i 0; i totalSlices; i) { BufferedImage subImage image.getSubimage(0, i * sliceHeight, image.getWidth(), Math.min(sliceHeight, image.getHeight() - i * sliceHeight)); // 将 subImage 添加到新页面 }这种方式生成的PDF每一页显示图片的一个连续片段上下衔接屏幕阅读很自然。注意getSubimage返回的图片与原始图片共享数据缓冲区如果原始图片在循环中被flush()会影响子图——所以切片完成后立即处理每片或者用BufferedImage复制一份。5.2 图片与文字混排如果PDF里需要章节标题、页码或者页眉页脚可以在PDPageContentStream里同时画图片和文字PDFBox本身支持showText配合字体配置就能实现图文混排。cs.beginText(); cs.setFont(PDType1Font.HELVETICA_BOLD, 16); cs.newLineAtOffset(margin, pageHeight - 30); cs.showText(业务文件 - index); cs.endText();对于中文内容需要加载中文字体文件通常是TTF否则中文会变成乱码。这个坑不建议躲直接在资源目录放一个字体文件用PDType0Font.load(document, fontFile)加载即可。5.3 批量任务并行化当图片数量特别多例如上千张单线程处理时间可能达到几十秒甚至数分钟。可以把图片列表分片用固定线程池并行处理每个线程生成独立的PDDocument最后再用PDFBox的PDFMergerUtility合并。PDFMergerUtility merger new PDFMergerUtility(); merger.setDestinationFileName(outputPath); for (File tempPdf : tempFiles) { merger.addSource(tempPdf); } merger.mergeDocuments(null);实测下来四核机器上并行处理的加速比大约在2.5~3倍之间内存占用会比单线程高需要根据图片大小调整分片数和每个线程处理的图片数量上限。并行化的前提是每张图片的处理相互独立这个场景天然满足。6. 实操总结与避坑指南项目做到后面我自己的体会是图片转PDF不难难的是在真实业务约束下把内存、体积、清晰度、顺序、方向这些因素同时控制住。几个值得沉淀的经验第一图片处理链路中每一个BufferedImage都是资源不是在用完之后马上flush()就是在计算完尺寸后立刻降采样不要让大图在内存里停留超过必要的时间。第二PDFBox的LosslessFactory与JPEGFactory不是随便选的。业务要求无损就选前者业务强调体积可控就选后者两者切换非常容易所以建议把压缩开关做成一个可配置参数而不是写死在代码里。第三图片排序逻辑一定要显式设计。按文件名排序看起来简单但如果文件名是1.jpg、2.jpg、10.jpg字符串排序会得到1、10、2的顺序这种问题不跑到实际数据上很难发现。需要自然排序时可以用Comparator自行比较数字部分。第四保留原始图片。PDF生成只是导出动作不意味着原始素材可以被删除。很多项目上线后才发现用户需要的是PDF的同时还需要保留原图做编辑这个需求往往等到开发完成后才会提出来。这些经验不是一两次就能总结全的好在这个方案本身足够简单后续维护起来压力不大。如果在实际使用中遇到新的问题回到这几个关键环节排查大概率能找到答案。