基于PDFBox与POI的批量PDF转Excel工具设计与实现

1. 立项背景：被手工转换折磨过的人，才懂批量工具的价值

先说一个我自己的场景。去年年底帮业务部门处理一批供应商报价单，整整三百多份PDF，全是带表格的扫描合同和系统导出的报价明细。业务同事的诉求很简单：把每份PDF里的表格数据提取出来，汇总到一张Excel总表里，后续要做价格比对和审计留痕。

一开始想省事，直接用现有的在线转换工具。试了十几个平台，要么有文件数量限制，要么免费版只转前三页，要么转换出来的表格完全错位、合并单元格直接裂开。折腾了两天，三百个文件才转了一半，还频繁出现格式错乱。咬着牙手动一个个对，差点把手干废。

就是从那时候起，我决心自己写一个pdftoexcel批量转换工具。核心需求很明确：批量处理、保留表格结构、支持命令行和后台调用、转换结果可校验。整个项目大概花了一周时间，从方案设计到最终落地，期间踩了不少坑。这篇博文就把完整思路、核心实现、批量调优过程和踩坑记录都整理出来，给同样被PDF转换折磨的兄弟一个参考。

这套方案适合谁来用？如果你手头有几十上百份PDF需要转Excel，且对表格对齐和合并单元格有要求，又不想把文件上传到第三方平台泄露数据，那这篇文章正好对口。不管你是Java后端开发、数据分析工程师，还是偶尔处理大批量文档的运维人员，照着里面的思路和代码，都能很快搭出一套自己的批量转换工具。

2. 技术选型解析：为什么我选了PDFBox + POI这条组合

2.1 路线对比：写代码还是调API，得先想清楚

动手之前，我先盘了一下市面上主流的PDF转Excel路线，大致可以分成四类：

我的应用场景是要把批量转换能力嵌入到公司内部的资料处理系统中，数据不能外发，文件量级在几百到上千份，且后续还要做批量调优。综合下来，Java技术栈是最稳的选择。有人会说Python的camelot做表格识别不是更省事嘛？确实，如果单纯做离线处理，camelot表现不错。但一旦涉及到系统集成、任务调度、日志监控和后续扩展，Java这边的PDFBox+POI组合显然更顺手。

2.2 为什么不用iText，而选PDFBox

Java生态里处理PDF，绕不开两个库：iText和PDFBox。iText功能强大，对PDF规范的支持非常完整，生成和编辑PDF都很溜，商业使用需要购买AGPL授权，这对公司内部项目来说是个隐患。PDFBox是Apache基金会的开源项目，Apache 2.0协议，商用友好，提供PDF文本提取、内容流解析、坐标定位等底层能力，正好符合我们“读取PDF内容，按坐标重建表格”的需求。

有人可能会问：PDFBox没有现成的表格识别API啊？没错，这正是它"麻烦"的地方，也是它"灵活"的地方。PDF本身是个基于坐标的文档格式，它压根不知道什么叫"表格"，只知道自己有哪些文字、哪些线条、分别画在什么位置。想做好转换，就得自己从底层把这些元素捞出来，重新推断表格结构。PDFBox把读取PDF内部内容流的能力开放得够彻底，我们才能在坐标层面做文章。iText虽然也能做到，但授权问题和API设计上的复杂程度，让我最终放弃了它。

2.3 批量架构需要的其他部件

除了PDFBox和POI，批量场景下还引入了几个配套组件：

• 任务队列：用Java内置的BlockingQueue + 线程池做生产者消费者模型，把PDF解析、Excel写入两个环节解耦。
• SXSSFWorkbook：POI提供的事件模型工作簿，专门应对大数据量写入，避免内存溢出。
• JSON配置：每个转换任务的参数（页码范围、是否合并单元格、是否输出表头）用JSON配置化，方便批量调优时做不同策略的对比实验。

组件选型上我坚持一个原则：能用JDK自带能力和轻量开源库解决的，坚决不引入重框架。项目本身是个工具型服务，搞个Spring Cloud加一堆中间件纯属杀鸡用牛刀。现在这个方案，一个普通的Spring Boot工程或者干脆一个带main方法的jar包就能跑，部署成本极低。

3. 核心设计拆解：PDF表格识别和Excel写入的核心难点

3.1 PDF里根本没有"表格"，我们识别的是什么

很多人第一次接触PDF解析都会懵：PDF文档里有很清晰的表格，程序读出来的却是一堆零散的文本和线条。原因在于PDF格式存储的是"绘制指令"：在坐标(x1,y1)处显示文字"张三"，在坐标(x2,y2)到(x3,y3)之间画一条直线，这些指令按顺序堆叠，构成了视觉上的表格。

所以我们要做的，本质上是从坐标层面还原表格的语义结构。大致分三步：

1. 提取文本块及其坐标（PDFBox的PDFTextStripper或自定义的TextStripper重写processTextPosition方法）。
2. 提取横向和纵向线段，确定表格的网格边界。
3. 把文本块按照行列网格做归类，填充到对应的单元格中。

这里最核心的难点在于：很多PDF表格并没有显式的框线，只是排版比较整齐的文本。这种情况下，只能通过文本块的坐标规律来推断列边界。我采用的做法是：先对每一行的文本Y坐标做聚类，把Y坐标相近的文本归为同一行；再统计所有文本块的X坐标区间，用聚类算法找到公共的列边界。这个方法对排版规整的PDF表格非常管用，但遇到无框线且文本错位的烂排版，还是会有误差，这部分在后面的"常见问题"里再细说。

3.2 坐标系统和文本提取的底层逻辑

PDFBox的坐标系原点在页面左上角，X轴向右，Y轴向下，单位是点（point，1英寸=72点）。页面上每个文本位置都对应一个TextPosition对象，包含getXDirAdj()、getYDirAdj()、getWidth()、getHeight()和getUnicode()等关键信息。

我的核心代码如下，重写writeString方法逐个捕获文本位置信息：

java复制public class CoordinateTextStripper extends PDFTextStripper {
    
    private List<TextBlock> textBlocks = new ArrayList<>();
    private int pageIndex = -1;
    
    public CoordinateTextStripper() throws IOException {
        super();
    }
    
    @Override
    protected void startPage(PDPage page) throws IOException {
        pageIndex++;
        textBlocks.clear();
    }
    
    @Override
    protected void writeString(String text, List<TextPosition> textPositions) throws IOException {
        for (TextPosition position : textPositions) {
            TextBlock block = new TextBlock();
            block.setText(position.getUnicode());
            block.setX(position.getXDirAdj());
            block.setY(position.getYDirAdj());
            block.setWidth(position.getWidthDirAdj());
            block.setHeight(position.getHeightDir());
            block.setPageIndex(pageIndex);
            textBlocks.add(block);
        }
    }
    
    public List<TextBlock> getTextBlocks() {
        return textBlocks;
    }
}

有了每个字的坐标，就可以把相邻的字按间距拼接成词，再按行Y坐标聚成一行文本。这里有个细节：PDF里"张三"两个字可能是两个独立的TextPosition，也可能是一个TextPosition直接包含完整字符串，需要根据实际输出做兼容判断。我在处理多个来源不同的PDF时发现，不同生成软件（WPS导出、浏览器打印、专业排版工具）导出的PDF在文本块粒度上差异很大，所以代码里需要同时兼容"按字拼接"和"按词提取"两种情况。

3.3 表格结构重建：列聚类和行对齐

表格重建是整个转换正确率的关键。我的实现思路分四步：

第一步，行聚类。 把所有文本块按照Y坐标排序，将Y坐标差值小于阈值（页面高度的0.5%，A4纸大约是4.2磅）的文本块归为同一行。阈值是调优出来的参数，后面在批量调优部分会详细讲。

第二步，列聚类。 对每一行内的文本块，按照X坐标排序，计算相邻文本块之间的水平间距。如果间距明显大于该行平均字符宽度的1.5倍，就认为存在列边界。

第三步，全局列对齐。 单行的列边界往往不齐，因为有些单元格内容长、有些内容短，文本块的实际坐标会偏左偏右。所以需要对所有行产生的列边界做一次全局聚类，找到覆盖大多数行的公共边界。这里我用了简单的贪心算法：按X坐标从小到大遍历所有列边界候选值，相邻边界差值小于阈值就合并取均值。

第四步，单元格内容填充。 根据重建出的行和列网格，把文本块按照坐标落到具体的单元格里。合并单元格的处理策略是：如果某个单元格在连续的几行都有文本，且这几行其他列都为空，则自动向上合并。注意，这个策略只对"纵向合并"有效，横向合并的判断更复杂，需要结合文本内容和格式一起推断，我在当前版本里处理得比较保守。

整个重建流程跑出来的效果，对规整的表格正确率能到95%以上。难点主要集中在复杂表头、跨行跨列严重、单元格内含多行文本这三类情况。如果有读者需要处理的是高度复杂的财务报表，建议在表格重建基础上再做一层基于语义的后处理规则，那就要根据具体业务字段来定制了。

4. 批量转换实现：从单文件功能到批量任务的完整落地

4.1 单文件转换的核心流程

先看单文件转换的主流程。整个转换过程封装成一个PdfToExcelConverter类，核心方法如下：

java复制public File convert(File pdfFile, File outputDir, ConvertOptions options) throws Exception {
    // 1. 加载PDF文档
    try (PDDocument document = PDDocument.load(pdfFile)) {
        // 2. 处理每一页，提取文本块和线段
        List<PageTableData> pageTables = new ArrayList<>();
        for (int pageIndex = 0; pageIndex < document.getNumberOfPages(); pageIndex++) {
            PageTableData tableData = extractTableFromPage(document, pageIndex, options);
            pageTables.add(tableData);
        }
        // 3. 写Excel
        File excelFile = new File(outputDir, getBaseName(pdfFile.getName()) + ".xlsx");
        writeToExcel(pageTables, excelFile, options);
        return excelFile;
    }
}

extractTableFromPage内部就是第三部分讲的四步重建逻辑。writeToExcel使用POI的SXSSFWorkbook，每页数据生成一个工作表，如果存在多页合并为同一张表的需求，也可以通过配置控制。

这部分逻辑比较直白，没什么特别的花活。真正的复杂度在于：不同来源的PDF格式差异极大，同样的代码处理一份PDF效果很好，换一份就崩了。所以我从设计初期就把转换参数全部配置化，比如行聚类阈值、列边界聚类阈值、是否需要检测框线、是否启用合并单元格识别等，这样后面做批量调优时，可以对不同批次的文件使用不同的参数组合。

4.2 Excel写入：POI的SXSSFWorkbook和样式控制

Excel写入层我直接用POI的SXSSFWorkbook（流式工作簿）。为什么不用普通的XSSFWorkbook？因为批量转换可能会把好几万行数据写到一个Sheet里，XSSFWorkbook在写入大量数据时会把整个工作表结构放在内存里，很容易触发OutOfMemoryError。SXSSFWorkbook的做法是：只保留最近N行在内存，更早的行会自动刷入磁盘临时文件，用空间换内存，写入大文件很稳。

java复制public void writeToExcel(List<PageTableData> pageTables, File outputFile, ConvertOptions options) throws IOException {
    try (SXSSFWorkbook workbook = new SXSSFWorkbook(200)) {
        workbook.setCompressTempFiles(true);
        for (int i = 0; i < pageTables.size(); i++) {
            PageTableData tableData = pageTables.get(i);
            SXSSFSheet sheet = workbook.createSheet(options.getSheetNamePrefix() + (i + 1));
            // 写表头
            if (tableData.getHeaderRow() != null) {
                SXSSFRow headerRow = sheet.createRow(0);
                for (int c = 0; c < tableData.getHeaderRow().size(); c++) {
                    headerRow.createCell(c).setCellValue(tableData.getHeaderRow().get(c));
                }
            }
            // 写数据行
            int rowIndex = tableData.getHeaderRow() != null ? 1 : 0;
            for (List<String> rowData : tableData.getRows()) {
                SXSSFRow row = sheet.createRow(rowIndex++);
                for (int c = 0; c < rowData.size(); c++) {
                    row.createCell(c).setCellValue(rowData.get(c));
                }
            }
            // 自适应列宽（仅对前几列，避免性能问题）
            for (int c = 0; c < Math.min(tableData.getMaxColumnCount(), 20); c++) {
                sheet.autoSizeColumn(c);
            }
        }
        try (FileOutputStream fos = new FileOutputStream(outputFile)) {
            workbook.write(fos);
        }
    } finally {
        // 清理SXSSF的临时文件
        SXSSFWorkbook.dispose();
    }
}

这里面有个坑：sheet.autoSizeColumn()对每一列都调用的话，大批量数据场景下性能非常差，因为它需要遍历所有行去测量文本宽度。我只对前20列做自适应宽度，剩余列用默认宽度，肉眼基本看不出差别，但性能能差出好几倍。另一个坑是SXSSFWorkbook在写完后必须调用dispose()清理临时文件，否则磁盘上会残留大量临时文件，跑完一个批量任务能清出好几个G的垃圾。

4.3 批量任务调度：线程池 + 队列 + 失败重试

单文件转换跑通后，做成批量就是水到渠成的事。批量场景下最重要的不是转换逻辑本身，而是任务调度和异常隔离。我的设计是生产者-消费者模型，主线程负责扫描目录下的PDF文件生成任务，放入有界阻塞队列，固定大小的线程池从队列取任务执行转换。

java复制public void batchConvert(File inputDir, File outputDir, ConvertOptions options) throws Exception {
    // 生产者：扫描文件，放入队列
    BlockingQueue<File> taskQueue = new ArrayBlockingQueue<>(1000);
    List<File> allFiles = FileUtils.listFiles(inputDir, new String[]{"pdf"}, true);
    new Thread(() -> {
        for (File file : allFiles) {
            try {
                taskQueue.put(file);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                break;
            }
        }
        taskQueue.put(FilePollMarker.END); // 结束标记
    }).start();

    // 消费者：线程池处理
    ExecutorService executor = Executors.newFixedThreadPool(options.getThreadCount());
    CountDownLatch latch = new CountDownLatch(allFiles.size() + 1);
    for (int i = 0; i < options.getThreadCount(); i++) {
        executor.submit(() -> {
            try {
                while (true) {
                    File pdfFile = taskQueue.take();
                    if (pdfFile == FilePollMarker.END) {
                        latch.countDown();
                        break;
                    }
                    try {
                        convertWithLog(pdfFile, outputDir, options);
                    } catch (Exception e) {
                        FailureRecorder.record(pdfFile, e.getMessage());
                    } finally {
                        latch.countDown();
                    }
                }
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        });
    }
    latch.await();
    executor.shutdown();
}

线程数不是越多越好，我实测下来，CPU密集型解析任务和内存占用并存，线程数=CPU核数+1是比较稳的配置。太多线程同时解析PDF会导致垃圾回收频繁，反而拖慢整体速度。另外这里有一个关键设计：单个文件转换失败不能中断整个批次。每个文件的异常都单独捕获，记录到失败清单里，整个批次跑完后统一排查。

批量的Excel合并策略也要提前规划好：我支持两种模式，一种是每个PDF对应一个Excel文件，另一种是把所有PDF的所有表格汇总到一个Excel工作簿、每个PDF一个Sheet。两种模式应对不同业务场景，前者适合文件对文件的一一对应，后者适合做汇总报表。代码里通过ConvertOptions的一个枚举字段控制。

5. 性能调优记录：批量跑千份PDF的实战调参过程

5.1 内存优化：PDF加载和Excel写入的平衡

批量场景下最怕的就是内存溢出。我这里做了三层防护：第一层，PDF解析用PDDocument.load的随机访问模式，不要用load的只读内存模式，这样大PDF不会一次性把所有内容读进内存。第二层，Excel写入用SXSSFWorkbook，内存中只保留最近200行。第三层，限制并发数，避免多个大文件同时加载导致堆内存爆掉。

实际调整时，我先把JVM堆设成4G，然后用100份平均50页的PDF做压测。初始版本跑完大概消耗了3.2G内存，GC频繁。经过三轮优化：

1. 把每个文件转换完成后立即PDDocument.close()，显式释放PDF相关内存。
2. 使用Runtime.getRuntime().gc()前先判断内存峰值，不主动触发GC。
3. 线程数从8降到6，内存占用直接降到2.1G，总耗时反而缩短了15%。

原因很简单：线程太多导致频繁的上下文切换和GC，真正干活的时间被压缩了。这个经验让我深刻体会到，批量调优不能只看并行度，要看CPU、内存、GC三者的综合表现。

5.2 阈值参数调优：一次对比实验的结果

表格识别算法里的行聚类阈值和列边界聚类阈值，对最终效果影响巨大。太小会把属于同一行的文本切碎，太大又会把不同行的文本混在一起。我拿三十份不同来源的测试PDF做了一轮参数对比实验，结果如下：

最终选择了行聚类4.2pt、列聚类5.0pt这组参数。4.2pt正好是页面高度的0.5%，对不同大小的PDF页面有自适应能力；5.0pt的列边界阈值能容忍单元格文本的左右留白，又不会跨列合并。当然这不是通用最优解，如果处理的PDF有特殊排版，还是需要针对性地调。

我还做了一个小功能：支持在转换日志里输出每份PDF单独使用的参数。这样复盘某个文件为什么转换错乱时，可以直接看日志里记录的参数组合，复现问题。这个功能帮了大忙，排查问题的时候再也不用靠猜了。

5.3 批量和单文件性能差距的根源

单文件转换速度再快，做成批量后整体吞吐不一定理想。原因在于：批量任务启动、线程池调度、磁盘IO争用、临时文件清理这些开销在单文件场景下可以忽略不计，到了批量场景就成了主要瓶颈。

我统计过一批500份PDF的总耗时构成：PDF解析占42%，Excel写入占31%，任务调度和队列等待占15%，文件IO占12%。解析和写入本身占了七成多，所以优化重点还是集中在算法层面和写入策略上。另外，输入文件和输出文件放在不同磁盘上，能明显降低磁盘IO竞争，这个优化方式简单粗暴但非常有效。

5.4 结合批量写入经验谈POI性能要点

顺带聊聊Excel写入方面的性能优化心得。Java操作Excel写入大量数据，我踩过不少坑，总结成几个要点：

• 批量插入时不要每条数据都创建一个CellStyle。CellStyle对象是共享的，创建太多会消耗大量内存，我复用同一个样式对象。
• 合并单元格操作非常昂贵。如果每个Sheet有几百个合并区域，写入速度会指数级下降，尽量在最后统一处理合并区域。
• 避免频繁调用autoSizeColumn，前面说过，改成只对前20列生效。
• 大数据写入优先用SXSSFWorkbook而不是XSSFWorkbook，这是内存问题，不是性能问题，但最后的耗时也会体现在性能上。

这些经验其实和数据库批量插入的道理是相通的：都是尽量复用资源、减少频繁切换、控制事务粒度，batched和高频操作之间的取舍，本质上是同一套逻辑。

有人可能会问，为什么不直接在代码里用EasyExcel之类的封装库？EasyExcel确实是个好选择，尤其它的流式写入做得非常成熟。我这边因为项目里已经有POI依赖，且工作簿需要做一些动态样式控制，所以继续用POI。如果从零开始做，我建议优先考虑EasyExcel，省心不少。

6. 实际使用效果与常见问题排查实录

6.1 一轮实测数据：转换成功率与耗时表现

工具做完后在真实业务数据上跑了一轮，效果还是比较满意的。测试集是某供应商系统导出的268份PDF，包含设备报价、维保合同、验收单三种类型，单份文件页数在1页到47页之间。

成功率98.1%，完全正确率92.2%。5个失败文件里有3个是扫描件（图片型PDF），没有文本层，需要先做OCR，这个工具目前处理不了。另外2个是加密PDF，需要先解密才能解析。16个部分错位的文件，基本都是表格线不完整、文本排版错乱导致的。整体来说，对规整的系统导出PDF效果很好，对纸质扫描件需要另配OCR方案。

6.2 高频问题对照排查表

把这段时间遇到的高频问题整理成一张表，方便大家直接照着排查：

6.3 OCR和后续扩展方向

前面提到扫描件无法处理的问题，实际上是有解的。可以用PDFBox把PDF页面渲染成图片，再交给Tesseract或PaddleOCR识别文字，然后把识别结果和坐标输出为文本块，重新走表格重建流程。这个扩展方向我已经在验证中，效果取决于OCR的识别精度，对清晰的印刷体扫描件，准确率还是不错的。

另一个扩展方向是保留样式。网上有人问"Java excel转pdf保留样式"，其实反向也是一样的诉求：PDF转换到Excel时能否保留背景色、字体、边框等样式。目前这个工具只保留单元格文字和基本合并结构，样式信息会丢失。原因是PDF的样式信息往往封装在内容流指令里，提取难度比文本坐标高一个数量级。如果有预算，可以考虑接入商用OCR服务的表格还原接口，但按量计费的成本需要评估。

最后是预览和校验机制。批量转换完几百个文件后，人工逐个打开Excel核对格式显然不现实。我加了个简单但实用的功能：转换完成后生成一份Excel摘要，列出每份PDF的转换状态、表格数量、行列数、耗时，再对有异常的记录输出警告标签。业务同事拿到这份摘要，只需要重点检查打了警告标签的文件，省了大量核对时间。这个设计给我一个启发：工具类项目的价值，一半在核心转换能力，另一半在流程的可观测性和可校验性。

7. 关于这个项目的一点个人心得

回看这个批量PDF转Excel工具的开发过程，最深的体会是：很多技术难点不是靠某个库或者某段代码解决的，而是靠对底层格式的理解和对异常情况的持续兜底。PDFBox给的是底层能力，怎么把"文本+坐标"重建成"表格+结构"，考验的是工程实现和算法设计。批量场景下的性能和稳定性，又考验的是并发控制和资源管理。这些能力没有现成的库可以替代，只能靠一次次踩坑、一轮轮调优堆出来。

如果看完这篇，你也想自己动手做一个，我建议先别追求功能和性能，就把单文件转换跑通，拿10份不同来源的PDF测一下识别率。然后在这个基础上一层层加批量、加调优、加异常处理。踩坑是不可避免的，但踩过之后，你对PDF和Excel这两个格式的理解，绝对会上一个台阶。