使用Apache Tika 2.6.0解析含图片内文字的PDF时遇空指针异常求助

问题背景 #

使用tika-core 2.6.0和tika-parsers-standard-package 2.6.0时，纯文字PDF、含图片的PDF、文本文件等解析正常，但解析包含图片内文字的PDF时触发运行时异常，核心错误为NullPointerException，堆栈指向AbstractPDF2XHTML.doOCROnCurrentPage(520)。

解决方案 #

1. 补充OCR依赖组件 #

触发该NPE的核心原因是解析图片内文字需要OCR（光学字符识别）支持，但tika-parsers-standard-package默认未包含完整的OCR依赖。需添加以下依赖到项目中：

Maven依赖：

<dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-parsers-ocr-standard</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>net.sourceforge.tess4j</groupId>
    <artifactId>tess4j</artifactId>
    <version>4.5.4</version>
</dependency>

Gradle依赖：

implementation 'org.apache.tika:tika-parsers-ocr-standard:2.6.0'
implementation 'net.sourceforge.tess4j:tess4j:4.5.4'

添加后确保项目能正确下载依赖，OCR组件会被自动初始化，避免空指针异常。

2. 升级Tika版本至最新稳定版 #

Tika 2.6.0存在OCR初始化时的空指针bug，后续版本（如2.7.0及以上）已修复该问题。直接升级依赖版本：

Maven：

<dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-core</artifactId>
    <version>2.9.1</version> <!-- 替换为最新稳定版 -->
</dependency>
<dependency>
    <groupId>org.apache.tika</groupId>
    <artifactId>tika-parsers-standard-package</artifactId>
    <version>2.9.1</version> <!-- 与core版本保持一致 -->
</dependency>

Gradle：

implementation 'org.apache.tika:tika-core:2.9.1'
implementation 'org.apache.tika:tika-parsers-standard-package:2.9.1'

3. 显式配置PDF解析的OCR参数 #

在代码中显式启用OCR并配置相关参数，确保解析器正确初始化OCR组件：

import org.apache.tika.parser.AutoDetectParser;
import org.apache.tika.parser.ParseContext;
import org.apache.tika.parser.pdf.PDFParserConfig;

// 初始化解析器
AutoDetectParser parser = new AutoDetectParser();
ParseContext context = new ParseContext();

// 配置PDF解析的OCR参数
PDFParserConfig pdfConfig = new PDFParserConfig();
pdfConfig.setExtractInlineImages(true);
pdfConfig.setOcrStrategy(PDFParserConfig.OCRStrategy.OCR_ONLY); // 按需选择策略
context.set(PDFParserConfig.class, pdfConfig);

// 使用配置后的context进行解析
parser.parse(inputStream, handler, metadata, context);

4. 临时异常捕获方案（仅应急使用） #

如果无法立即升级或添加依赖，可在解析时捕获该异常，跳过出错页面或进行降级处理：

try {
    parser.parse(inputStream, handler, metadata, context);
} catch (TikaException e) {
    if (e.getCause() instanceof NullPointerException && 
        e.getCause().getStackTrace()[0].getClassName().contains("AbstractPDF2XHTML")) {
        // 记录日志并跳过该文件/页面
        log.warn("OCR解析失败，跳过当前PDF文件", e);
    } else {
        throw e;
    }
}

内容的提问来源于stack exchange，提问作者DeadPool