本文介绍使用 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）结构，不渲染页面内容，因此内存占用极低（通常
✅ 推荐实现：封装健壮的流式页数统计工具类
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。如需支持，可改用带密码参数的重载方法：
document = PDDocument.load(inputStream, "user_password");
-
Maven 依赖（推荐最新稳定版）：
<dependency><groupid>org.apache.pdfbox</groupid><artifactid>pdfbox</artifactid><version>2.0.29</version><!-- 截至2026年4月最新稳定版 --></dependency>
性能对比：相比正则匹配 /Type\s*/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());
}
}</resource>
? 总结：PDDocument.load(InputStream).getNumberOfPages() 是 Java 生态中最可靠、最轻量、最标准化的流式 PDF 页数获取方案。它规避了内存瓶颈，兼容主流 PDF 规范（1.4–2.0），且 API 简洁无副作用。在构建文档预览、批量归档、合规校验等系统时，应作为首选技术路径。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
