在 Java 中如何通过输入流高效获取 PDF 文件总页数

本文介绍使用 Apache PDFBox 库，从 InputStream（如网络响应流、文件流或内存流）中无需完全加载 PDF 到内存，即可准确、安全地获取其总页数的核心方法与最佳实践。

本文介绍使用 apache pdfbox 库，从 `inputstream`（如网络响应流、文件流或内存流）中无需完全加载 pdf 到内存，即可准确、安全地获取其总页数的核心方法与最佳实践。

在企业级文档处理场景中，常需对远程或大体积 PDF 文件（如合同、报表、扫描件）进行轻量元信息提取——其中「获取总页数」是最基础却高频的需求。若直接将整个 PDF 加载为字节数组（byte[]），极易触发 OutOfMemoryError，尤其面对上百 MB 的扫描版 PDF。理想方案是基于流式解析（stream-based parsing），仅读取 PDF 结构头部的关键信息（如 /Pages 对象及 /Count 条目），跳过内容流、图像、字体等冗余数据。

Apache PDFBox 2.x+ 完全支持此能力：其 PDDocument.load(InputStream) 方法底层采用延迟加载策略，仅解析文档目录（Catalog）和页面树（Page Tree）结构，不渲染页面内容，因此内存占用极低（通常 < 1MB），且执行迅速（毫秒级）。

✅ 推荐实现：封装健壮的流式页数统计工具类

import org.apache.pdfbox.pdmodel.PDDocument;import java.io.IOException;import java.io.InputStream;public class PdfStreamPageCounter {    /**     * 从输入流安全获取 PDF 总页数     * @param inputStream PDF 数据流（支持 FileInputStream, ByteArrayInputStream, HTTP 响应流等）     * @return 页数（成功返回 ≥ 1；失败返回 0）     */    public static int getPageCount(InputStream inputStream) {        if (inputStream == null) {            return 0;        }        PDDocument document = null;        try {            // 关键：PDFBox 自动识别流格式，无需 reset() 或 mark()            document = PDDocument.load(inputStream);            return document.getNumberOfPages();        } catch (IOException e) {            // 捕获常见异常：损坏文件、加密PDF、IO中断、不支持的PDF版本            System.err.println("Failed to read PDF page count: " + e.getMessage());            return 0;        } finally {            // 必须关闭，释放资源（即使流由外部管理，document 内部仍持有缓冲区）            if (document != null) {                try {                    document.close();                } catch (IOException ignored) {                    // close() 失败不影响主逻辑，静默忽略                }            }        }    }}

⚠️ 重要注意事项

• 流可读性要求：PDFBox 要求 InputStream 支持 mark()/reset()（如 BufferedInputStream）。若原始流不支持（如某些 HTTP 响应流），请先包装：

  InputStream safeStream = new BufferedInputStream(inputStream);int pages = PdfStreamPageCounter.getPageCount(safeStream);

• 加密 PDF 处理：若 PDF 含打开密码，PDDocument.load() 将抛出 InvalidPasswordException。如需支持，可改用带密码参数的重载方法：

  立即学习“Java免费学习笔记（深入）”；

  document = PDDocument.load(inputStream, "user_password");

• Maven 依赖（推荐最新稳定版）：

  <dependency>    <groupId>org.apache.pdfbox</groupId>    <artifactId>pdfbox</artifactId>    <version>2.0.29</version> <!-- 截至2026年4月最新稳定版 --></dependency>

• 性能对比：相比正则匹配 /Types*/Page 或手动解析 PDF 交叉引用表（XRef），PDFBox 方案具备语义正确性——它真实遍历页面树，能正确处理包含 Page、Pages、Kids 嵌套结构及间接对象引用的复杂 PDF，避免因 PDF 版本差异或生成器差异导致的误判。

? 使用示例：从 HTTP 流获取页数（Spring Boot 场景）

import org.springframework.web.client.RestTemplate;import java.io.InputStream;import java.net.URL;// 模拟从 URL 获取 PDF 流public void fetchAndCountPages(String pdfUrl) {    try {        URL url = new URL(pdfUrl);        InputStream stream = url.openStream(); // 或使用 RestTemplate + ResponseEntity<Resource>        int pageCount = PdfStreamPageCounter.getPageCount(stream);        System.out.printf("PDF '%s' contains %d page(s)%n", pdfUrl, pageCount);    } catch (Exception e) {        System.err.println("Cannot fetch or parse PDF: " + e.getMessage());    }}

? 总结：PDDocument.load(InputStream).getNumberOfPages() 是 Java 生态中最可靠、最轻量、最标准化的流式 PDF 页数获取方案。它规避了内存瓶颈，兼容主流 PDF 规范（1.4–2.0），且 API 简洁无副作用。在构建文档预览、批量归档、合规校验等系统时，应作为首选技术路径。