首页 / 新闻资讯 / 使用 PDFBox 实现图片转 PDF：完整指南与代码示例

使用 PDFBox 实现图片转 PDF：完整指南与代码示例

发布时间：2026-06-22 作者：龚辉 阅读量：12

引言

在文档处理中，将图片转换为 PDF 格式是一种常见需求，例如扫描文档归档、图片批量导出等场景。Apache PDFBox 是一个强大的开源 Java 库，专门用于创建和操作 PDF 文档。它提供了丰富的 API 来处理图像、文本和元数据，使得图片转 PDF 变得简单高效。

为什么选择 PDFBox？

  • 开源免费：Apache 许可证，无需担心版权问题。
  • 跨平台：基于 Java，可在 Windows、Linux 和 macOS 上运行。
  • 功能全面：不仅支持图片转 PDF，还能提取文本、添加水印、合并文档等。
  • 性能稳定：适合处理大量图片，内存管理优化良好。

环境准备

在使用 PDFBox 前，需要设置开发环境。以下是步骤：

  1. 安装 Java SDK：确保已安装 JDK（建议版本 8 或以上）。
  2. 添加 PDFBox 依赖：在 Maven 项目的 pom.xml 文件中添加以下依赖：
    <dependency>
      <groupId>org.apache.pdfbox</groupId>
      <artifactId>pdfbox</artifactId>
      <version>2.0.29</version>
    </dependency>
    或者下载 JAR 文件手动导入项目。

核心实现：图片转 PDF 代码示例

以下是一个完整的 Java 示例，演示如何将单张或多张图片转换为一个 PDF 文件。代码注释详细，便于理解。

import org.apache.pdfbox.pdmodel.*;
import org.apache.pdfbox.pdmodel.common.PDRectangle;
import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
import java.io.File;
import java.io.IOException;

public class ImageToPDFConverter {
    public static void main(String[] args) {
        // 输入图片路径数组（支持 JPG、PNG 等格式）
        String[] imagePaths = {"image1.jpg", "image2.png", "image3.gif"};
        String outputPath = "output.pdf";

        try {
            // 创建 PDF 文档
            PDDocument document = new PDDocument();

            for (String imagePath : imagePaths) {
                // 加载图片
                PDImageXObject pdImage = PDImageXObject.createFromFile(imagePath, document);
                
                // 设置页面尺寸为图片原始尺寸（可自定义）
                PDRectangle rectangle = new PDRectangle(pdImage.getWidth(), pdImage.getHeight());
                PDPage page = new PDPage(rectangle);
                document.addPage(page);
                
                // 在页面上绘制图片
                PDPageContentStream contentStream = new PDPageContentStream(document, page);
                contentStream.drawImage(pdImage, 0, 0, pdImage.getWidth(), pdImage.getHeight());
                contentStream.close();
            }

            // 保存 PDF 文件
            document.save(outputPath);
            document.close();
            System.out.println("PDF 转换成功！文件保存至: " + outputPath);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

进阶技巧与优化

1. 调整页面尺寸

默认情况下，PDF 页面尺寸会匹配图片大小。但您可以通过 PDRectangle 自定义页面尺寸，例如设置为 A4 纸张（595x842 点）。

2. 处理大文件与内存管理

处理大量图片时，建议：

  • 使用流式处理，避免一次性加载所有图片。
  • 定期关闭文档和流，释放内存资源。
  • 在循环中分批处理图片，例如每 10 张图片生成一个 PDF。

3. 添加元数据与水印

PDFBox 允许为 PDF 文件添加标题、作者等元数据。此外，您可以使用 PDPageContentStream 的绘制方法添加水印文本或图像。

常见问题与解决方案

  • 问题：图片显示不完整或模糊。
    解决：确保使用正确的图像格式，并检查 DPI 设置。PDFBox 默认以 72 DPI 绘制，对于高分辨率图片，可能需要缩放。
  • 问题：中文文件名导致乱码。
    解决：在读取文件路径时，使用 UTF-8 编码。
  • 问题：合并图片时顺序错误。
    解决：按需对图片路径数组进行排序，例如使用 Collections.sort()。

总结

通过本文的介绍，您应该已经掌握了使用 PDFBox 将图片转换为 PDF 的基本方法和高级技巧。PDFBox 的灵活性和强大功能使其成为 Java 开发者处理 PDF 任务的理想选择。无论是简单的单张图片转换，还是复杂的批量处理，都可以通过定制代码实现。建议在实际项目中参考官方文档，并测试不同场景以优化性能。

相关文章