如何配置PDFBox使用twelvemonkeys渲染JPEG2000规避专利风险

配置失效核心原因 #

配置未生效是因为引入了错误的TwelveMonkeys模块：你添加的imageio-jpeg是处理标准JPEG格式的组件，不包含JPEG2000格式解码器，PDFBox自然无法识别JPEG2000格式的内嵌图片。

正确配置步骤 #

• 第一步：彻底移除所有JAI相关依赖，包括jai-imageio-core、jai-imageio-jpeg2000，避免类冲突导致解码器加载异常。
• 第二步：引入TwelveMonkeys的JPEG2000专用模块。TwelveMonkeys基于Java SPI机制自动注册ImageIO解码器，不需要额外编写注册代码、也不需要修改PDFBox任何配置，PDFBox调用标准ImageIO接口时会自动识别可用的JPEG2000解码器。

正确的Maven依赖配置如下：

<dependency>
    <groupId>com.twelvemonkeys.imageio</groupId>
    <artifactId>imageio-jpeg2000</artifactId>
    <version>3.8.2</version>
</dependency>

注意事项 #

• 之前引入的imageio-jpeg模块和JPEG2000解码无关，无普通JPEG特殊处理需求的话不需要额外引入。
• 如果使用Spring Boot、Maven Shade等方式打可执行Fat Jar，需要确保打包插件没有过滤掉META-INF/services路径下的SPI配置文件，否则会出现本地运行正常、打包后依旧报JPEG2000解码器缺失的问题。
• TwelveMonkeys的JPEG2000实现基于开源OpenJPEG封装，不存在原JAI JPEG2000实现的专利授权风险，可以合规商用。
• 配置完成后可以通过执行javax.imageio.ImageIO.getReaderFormatNames()验证，打印结果中包含JPEG2000即说明解码器注册成功。

原问题背景 #

使用PDFBox 2.0.20（该问题无强版本绑定）打开内嵌JPEG2000格式图片的PDF时，初始触发报错：
Cannot read JPEG2000 image: Java Advanced Imaging (JAI) Image I/O Tools are not installed

最初通过引入JAI相关依赖解决了问题，依赖配置如下：

<dependency>
<groupId>com.github.jai-imageio</groupId>
<artifactId>jai-imageio-core</artifactId>
<version>1.4.0</version>
</dependency>

<dependency>
<groupId>com.github.jai-imageio</groupId>
<artifactId>jai-imageio-jpeg2000</artifactId>
<version>1.3.0</version>
</dependency> 

后续了解到未授权使用jai-imageio-jpeg2000存在专利侵权风险，计划替换为TwelveMonkeys实现，移除JAI依赖后错误引入了imageio-jpeg模块，配置未生效复现原报错，错误依赖如下：

<dependency>
<groupId>com.twelvemonkeys.imageio</groupId>
<artifactId>imageio-jpeg</artifactId>
<version>3.8.2</version>
</dependency>

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