PDFBox 3.0.3渲染大PDF页面为图片触发capacity<0异常求助

是否为PDFBox的Bug？ #

是，这属于PDFBox 3.0.3版本的Bug。问题根源在于Filter类的解码逻辑中，对大尺寸缓冲区的容量计算使用了32位int类型，当待处理字节长度处于524,288,000（约500MB）至1,048,576,000（约1GB）区间时，部分计算操作会触发整数溢出，导致传入RandomAccessReadWriteBuffer的容量参数变为负数，最终抛出IllegalArgumentException: capacity < 0。

解决办法 #

• 升级PDFBox版本：PDFBox后续发布的版本（如3.0.4及以上）已修复大内存缓冲区的整数溢出问题，优先将依赖升级到最新稳定版，这是最直接有效的解决方案。
• 调整缓存策略：替换当前的纯临时文件缓存，改用内存+临时文件的混合缓存，限制内存中缓存的最大容量，避免创建超大内存缓冲区。示例代码：

  // 设置内存缓存上限为256MB，超出部分自动写入临时文件
  StreamCache cache = IOUtils.createMemoryAndTempFileStreamCache(256 * 1024 * 1024);
  PDDocument document = Loader.loadPDF(pdfFile, cache);
  PDFRenderer pdfRenderer = new PDFRenderer(document);
  pdfRenderer.setSubsamplingAllowed(true);
  BufferedImage image = pdfRenderer.renderImage(0, scale, ImageType.RGB);
  ImageIO.write(image, "png", imageFile);
  

• 降低渲染负载：如果业务允许，降低渲染时的scale参数值，减少单页渲染所需的内存占用；或者分块处理页面内容，避免一次性加载过大的资源到内存中。
• 自定义缓冲区修复（进阶）：若无法升级版本，可通过自定义Filter实现或反射修改缓冲区创建逻辑，强制使用long类型计算缓冲区容量，避免整数溢出。此方法需要对PDFBox源码有一定了解，仅作为临时应急方案。

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