Java Word转PDF实战：LibreOffice+JODConverter方案完整指南-代码聚汇网

Java Word转PDF实战：LibreOffice+JODConverter方案完整指南

超级咨询师INFO·2026-09-06·阅读 21 GEO检测（免费）

JavaWord转PDFLibreOffice

|难度：普通|阅读约 38 分钟

先交代一下背景吧。Java做Word转PDF，这需求我前后折腾了不下十次，从最早用POI硬啃，到后来换Aspose试用版，再到老老实实上LibreOffice + JODConverter，每一步都踩过不少坑。网上搜“java word转pdf”出来的教程一大把，但大多数是复制粘贴的“hello world”，真要跑起来，不是环境没配好，就是转换出来排版直接稀烂。这篇我把自己实际在用的这套方案完整写出来，从环境安装、依赖引入、核心代码，到批量并发、生产部署，再到各种玄学问题的排查思路，尽量一次讲透。不管你是刚接触Java的新手，还是被这个需求折磨过的老手，按这篇文章的顺序走一遍，应该能少走很多弯路。

这个需求的本质，其实不是“把文件后缀名改掉”，而是要让文档在被转换和渲染之后，保持版式、字体、分页、图片这些细节不跑偏。选错工具，轻则文字错位，重则直接乱码，所以方案选型绝对值得花时间聊清楚。

1. 先理思路：Java做Word转PDF，到底该用哪条路

1.1 这个需求是从哪儿冒出来的

先说说为啥“Word转PDF”在Java后端里这么常见。我接手过的项目里，出现这个需求不外乎几种情况：合同和订单需要生成PDF给用户下载或打印；内部系统里的Word报告要转成PDF方便归档；不同终端查看文档时，Word文件格式兼容性差，统一转成PDF能保证所有人看到的版式一致；还有些场景压根不需要用户下载可编辑的Word，只需要预览，转PDF是成本最低的方案。

你会发现，这些场景几乎都在“服务端”，也就是说，转换动作不能依赖某个人的电脑，更不能让用户去装Office，必须由后端自己完成。这就引出一个关键问题：服务器上跑什么软件来做转换。

1.2 常见方案对比，为什么最后选了LibreOffice

我先把市面上常见的几条路挨个过一遍，纯粹从实操角度说说它们的坑。

第一种：直接把Word当文件流读出来，自己解析内容再拼PDF。 这是POI + iText的路线。POI负责读docx里的文字、表格、图片，iText负责生成PDF。听起来很灵活，但你一旦遇到带复杂样式、目录、页眉页脚、文本框、艺术字这些元素的文档，解析逻辑会膨胀到完全失控。更不用说doc格式是老式二进制结构，POI的HWPF模块对它的支持非常有限，稍微复杂一点的排版直接废掉。除非你的文档格式是自己系统生成的、非常规整，否则这条路基本是给项目埋雷。

第二种：服务器上装Microsoft Office，用Java调COM组件或者命令行让Word自己转。 Windows服务器上确实能看到有人这么干，但后果就是热搜词里那个“word转pdf office提示未响应”。Word的COM组件本就不是为高并发服务端调用设计的，多线程同时操作极易崩溃，而且服务器一旦装了Office，各种弹窗、更新、授权问题能让你维护到怀疑人生。这条路我强烈不建议。

第三种：Aspose.Words这类商业库。 说实话，Aspose.Words的转换质量确实不错，对复杂样式的支持比开源方案好，而且是纯Java实现，不依赖外部软件。但它有两点劝退我：一是License不便宜，商用要仔细留意授权；二是在一些特殊字体和复杂排版上，它的呈现效果和Office原生渲染仍有细微差异，对“必须和Word里一模一样”这种需求，还是会有讨价还价的空间。

第四种：LibreOffice + JODConverter，也是我最终在用的方案。 LibreOffice本身是免费开源的办公套件，它支持通过命令行无界面执行文档转换，JODConverter则是一个Java封装库，负责管理LibreOffice进程，让你能在Java里优雅地调用转换功能。这个方案的转换原理是：LibreOffice把Word文档按自己的排版引擎“打开并重新渲染”一遍，然后导出为PDF。因为它是完整的办公软件在做渲染，所以版式、字体、分页这些细节的还原度非常高，而且完全不需要Windows和Office。部署在Linux服务器上，几乎零成本。

1.3 为什么是LibreOffice而不是OpenOffice

很多人会问，JODConverter早期教程都是配合OpenOffice用的，是不是用OpenOffice也行。能跑，但我不推荐。LibreOffice更新频繁，对docx和微软格式的兼容性明显更好，转换出来的效果更接近原文档。OpenOffice的开发节奏慢，新格式支持跟不上，光这一点就够你排查很久的排版问题了。如果你的机器已经装了OpenOffice，也不是不能用，但我个人建议统一用LibreOffice，少踩坑。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 部署LibreOffice：环境才是第一个大坑

2.1 Windows本地环境安装LibreOffice

本地调试最省事的就是去LibreOffice官网下一个Windows安装包，装完之后打开命令行执行：

bash复制libreoffice --version

能输出版本号就行。注意安装时最好选“为所有用户安装”，否则路径带用户目录，后面Java进程启动LibreOffice时可能因为权限问题找不到程序。

如果命令行提示找不到libreoffice命令，大概率是安装目录没进PATH。Windows默认安装路径类似：

code复制C:\Program Files\LibreOffice\program

把这个目录手动加进系统环境变量PATH里就行。另外，JODConverter默认会去找安装目录下的soffice.exe，理论上它能自己探测，但个别版本探测失败时，你可以在代码里显式指定officeHome参数，这个后面讲代码的时候会提到。

2.2 Linux服务器部署命令和注意事项

部署到Linux服务器才是大多数Java后端的最终归宿。以Ubuntu/Debian系为例，安装命令是：

bash复制sudo apt update
sudo apt install libreoffice-writer libreoffice-core fonts-wqy-zenhei fonts-wqy-microhei

为什么我特意加了fonts-wqy-zenhei和fonts-wqy-microhei？这是文泉驿中文字体包。缺少中文字体是转换后出现乱码、方块字、甚至内容错位的头号元凶。很多教程只让你装libreoffice-writer，转头就问“为什么转出来中文全是方块”，就是没装字体包。CentOS/RHEL系则用：

bash复制sudo yum install libreoffice-writer libreoffice-core
sudo yum install wqy-zenhei-fonts wqy-microhei-fonts

安装完成后，在真实项目里我还会额外做一件事：把Windows上常用字体上传到服务器。因为很多业务文档用的字体是微软雅黑、宋体、楷体这类商业字体，LibreOffice默认没有，转换时它只能用替代字体渲染，结果就是行间距、页宽、分页位置全都不一样。具体做法是把Windows字体目录C:\Windows\Fonts下的msyh.ttc、simsun.ttc等文件上传到Linux服务器的/usr/share/fonts/truetype/custom/目录，然后执行：

bash复制fc-cache -fv

让字体缓存生效。这一步能解决80%“看起来差不多但总觉得哪里不对”的排版问题。

2.3 Docker方式部署，省心但要注意镜像体积

如果你的团队已经习惯用容器部署服务，也可以直接拉一个带LibreOffice的镜像。官方镜像比较精简，我一般用Dockerfile自己拼一个：

dockerfile复制FROM ubuntu:22.04
RUN apt update && apt install -y libreoffice-writer libreoffice-core fonts-wqy-zenhei fonts-wqy-microhei

这个镜像体积会比较大，因为LibreOffice依赖不少系统库，但换来的是和宿主机环境的完全隔离，不会污染已有环境，也不怕安装包和系统里其他软件冲突。构建好之后，启动容器时把Java应用也扔进同一个容器，或者用docker-compose把两个服务编排在一起都行。需要注意的一点是，如果容器只跑LibreOffice而不跑Java应用，那JODConverter连接LibreOffice时要把容器端口和宿主机端口映射对，否则Java进程访问不到。

3. 写代码：基于JODConverter的转换实现

3.1 Maven依赖引入，版本要统一

这部分直接给结论。我用的是JODConverter 4.x版本的依赖，Spring Boot项目的话引入：

xml复制<dependency>
    <groupId>org.jodconverter</groupId>
    <artifactId>jodconverter-local</artifactId>
    <version>4.4.6</version>
</dependency>
<dependency>
    <groupId>org.jodconverter</groupId>
    <artifactId>jodconverter-spring-boot-starter</artifactId>
    <version>4.4.6</version>
</dependency>

注意两个依赖的版本必须一致，否则运行时会出现类冲突。JODConverter 4.x重新划分了包结构，老教程里常见的org.jodconverter:jodconverter-spring-boot-starter 3.x版本和4.x版本在配置上差别不小，你搜资料时一定要看清版本。如果项目没用Spring Boot，只引入jodconverter-local就够了，然后用LocalOfficeManager自己管理。

3.2 几个核心类的职责，先弄明白再动手

JODConverter里几个关键类的关系，我花点时间讲清楚，避免你后面调试时一头雾水。

DocumentConverter：顶层转换接口，代码里直接调它来完成转换。
LocalOfficeManager：负责启动、管理、关闭LibreOffice进程。它是JODConverter的核心管家，拿它就像拿一个连接池。
OfficeManager可以配置启动多个LibreOffice进程，用来应对并发转换，这个后面细说。

实际编码时，Spring Boot项目只需要在配置文件里写好参数，就能自动注入一个DocumentConverter的Bean。老项目里用3.x版本时，Bean类型直接就是OfficeManager，不一定有DocumentConverter，这个差异是版本升级带来的，所以再次强调：版本认准4.x。

3.3 配置参数：端口、超时、进程数

在application.yml里我一般这样配置：

yaml复制jodconverter:
  local:
    enabled: true
    office-home: /usr/lib/libreoffice
    port-numbers: [2001, 2002, 2003]
    task-execution-timeout: 120000
    task-queue-timeout: 60000
    max-tasks-per-process: 200

逐项说明一下我的习惯：

office-home：LibreOffice的安装根目录。Linux上一般装完后路径是/usr/lib/libreoffice，可以执行which soffice或ls /usr/lib/libreoffice/program/soffice确认。Windows则是C:\Program Files\LibreOffice。如果你不写这个参数，JODConverter会尝试从系统PATH里找，大部分情况能找到，但显式指定更稳妥。

port-numbers：JODConverter通过UNO协议和LibreOffice通信，每个LibreOffice进程默认监听一个端口。如果你的并发转换量不小，可以配置多个端口，这样JODConverter会启动多个LibreOffice进程组成一个池，并行处理任务。注意这里的端口必须是不被占用的，否则启动失败。

task-execution-timeout：单个转换任务的最大执行时间。有的文档特别大，或者字体渲染很慢，超时设得太短（比如默认的30秒或60秒）会直接导致转换失败。我一般设置成120秒，如果文档经常超过这个时间，再往上调。

task-queue-timeout：任务在队列里等待的最大时间。当所有LibreOffice进程都在忙时，新任务会进入队列，超过这个时间还没轮到，就会抛超时异常。这个参数在高并发下很关键，合理值是60秒左右。

max-tasks-per-process：一个LibreOffice进程最多执行多少个转换任务后自动重启。LibreOffice跑久了会越来越慢，甚至内存膨胀，定期重启能保持稳定。我一般设200，效果不错。

3.4 核心转换代码，可以直接抄

大部分场景不需要写太多代码，核心就三行：

java复制@Autowired
private DocumentConverter documentConverter;

public void wordToPdf(String sourcePath, String targetPath) {
    File sourceFile = new File(sourcePath);
    File targetFile = new File(targetPath);
    documentConverter.convert(sourceFile).to(targetFile).execute();
}

sourceFile必须是已经存在的Word文件，targetFile是转换输出的PDF路径。JODConverter会根据文件扩展名自动判断文档类型，doc、docx、rtf、odt这些都能转，目标格式写.pdf就行。

实际业务中，源文件往往不是本地路径，而是上传的MultipartFile或远程下载的流。我封装过一个工具方法，核心思路是先把源文件保存到临时目录，再执行转换，最后删除临时文件：

java复制public String convertToPdf(MultipartFile multipartFile) throws IOException {
    String tempDir = System.getProperty("java.io.tmpdir");
    String originalFilename = multipartFile.getOriginalFilename();
    String baseName = originalFilename.substring(0, originalFilename.lastIndexOf("."));
    File sourceFile = new File(tempDir, System.currentTimeMillis() + "_" + originalFilename);
    File targetFile = new File(tempDir, System.currentTimeMillis() + "_" + baseName + ".pdf");
    
    multipartFile.transferTo(sourceFile);
    try {
        documentConverter.convert(sourceFile).to(targetFile).execute();
        // 转成字节数组返回，或者把targetFile拷到业务存储目录
        byte[] bytes = Files.readAllBytes(targetFile.toPath());
        return Base64.getEncoder().encodeToString(bytes);
    } catch (OfficeException e) {
        throw new BusinessException("文档转换失败", e);
    } finally {
        Files.deleteIfExists(sourceFile.toPath());
        Files.deleteIfExists(targetFile.toPath());
    }
}

这段代码没什么高深技巧，但有几个细节值得说：临时文件必须带正确扩展名，否则JODConverter无法识别格式；文件命名加时间戳，避免并发时文件名冲突；finally里清理临时文件，防止服务器磁盘被一堆转换半成品塞满。

3.5 常用格式的转换变体：word转pdf、pdf转word

顺带说一句，JODConverter是双向的。不仅是Word转PDF，你甚至可以反着来，把PDF转成Word。有的系统做文档预览时，用户上传的是PDF，但后续需要调格式，就希望转回可编辑的docx。代码几乎是一模一样的，只是源文件和目标文件扩展名对调：

java复制documentConverter.convert(sourcePdfFile).to(targetDocxFile).execute();

不过要有个心理预期：PDF转Word在格式还原上比Word转PDF差很多，尤其是多栏排版、图文混排的PDF，转出来经常面目全非。这是渲染原理决定的，不是JODConverter的锅。业务上遇到PDF要编辑，我更建议提醒用户重新上传Word版本，而不是硬靠转换。

4. 生产化：批量转换、并发控制与性能调优

4.1 批量转换的正确姿势

实际项目里很少只转一个文件，通常是一个列表要批量生成PDF。最粗暴的写法是for循环挨个转换，但这里有个陷阱：如果你的文档数量很大，每一个转换都要等LibreOffice冷启动，速度会很慢。JODConverter的OfficeManager在Spring Boot启动时就会把LibreOffice进程拉起来，所以单次转换的速度还行，但批量场景下仍要注意异常处理。

我的做法是分批+失败重试。比如一次提交10个文档，每个文档转换不隔离，一个失败不应该拖垮整个批次。可以用一个简单的循环：

java复制for (DocTask task : taskList) {
    try {
        documentConverter.convert(task.getSourceFile()).to(task.getTargetFile()).execute();
        task.setStatus(SUCCESS);
    } catch (OfficeException e) {
        task.setStatus(FAILED);
        log.error("转换失败，文件名：{}，原因：{}", task.getFileName(), e.getMessage());
        // 这里可以记录失败原因，或者把任务放入重试队列
    }
}

如果有几千个文件要转，我会把它们放进线程池，并发数量控制在和LibreOffice进程数一致或略低一点。这里一定要想清楚：JODConverter的并发上限是由OfficeManager配置的端口数决定的，你起3个端口，理论上最多3个LibreOffice进程并行处理。你用20个线程去调，最终任务还是会在队列里排队，反而增加线程切换开销。

4.2 服务端转换必须做异步，不然接口必慢

Word转PDF不是毫秒级操作，一个十几页的文档通常要几百毫秒到几秒，大型文档几十秒也正常。如果你把它放在用户请求的同步链路里，前端会一直转圈等待，体验差不说，并发一上来请求线程容易被占满。

我一般在业务里加一层异步处理：用户提交转换请求后，立刻返回“任务已提交”，后台线程池执行转换，完成后通过WebSocket或者拉取状态的方式通知前端。这层设计不是JODConverter独有的，而是所有耗时型服务都应该有的思路。实现方式无非是：

用Spring的@Async注解，把转换方法丢到独立线程池
或者用消息队列，比如RabbitMQ、RocketMQ，把转换任务发给消费者
转换状态存数据库或Redis，前端轮询获取

4.3 内存与进程周期的调优心得

LibreOffice本身是用C++写的，启动后每个进程占用的内存大概在200MB到500MB之间，具体取决于打开的文档复杂度。如果你配置了3个端口（也就是3个LibreOffice进程），那光LibreOffice就会占用600MB到1.5GB内存。这在部署时就要提前规划好，别让Java应用和LibreOffice抢内存。

另外，务必配置max-tasks-per-process。曾经我在一个服务里不设这个参数，跑了一个月后，LibreOffice进程的内存占用从400MB涨到3GB，转换速度也肉眼可见地变慢。原因是LibreOffice进程长期运行会产生内存碎片，定期重启能有效解决。JODConverter会在达到指定任务数后自动重启该进程，代价是重启的瞬间会损失一点吞吐，但从长期稳定性看很划算。

还有一个实战坑：LibreOffice进程突然被系统杀掉导致没有释放端口，JODConverter会傻傻地以为进程还活着，连接的时候一直超时。遇到这种情况，我会在启动任务的机器上加一个定时脚本，定期检测端口连通性，异常时调用OfficeManager.stop()再start()重启。虽然有点暴力，但在生产环境很管用。

5. 问题排查：那些“玄学”Bug其实都有根源

5.1 为什么Word里看没问题，转PDF却有空白页

这是搜索热度非常高的一个问题，也是我初学时百思不得其解的问题。先说结论：空白页绝大多数情况下是字体缺失导致的。Word文档里如果用了某款字体，而服务器上的LibreOffice没有款字体，LibreOffice就会用它认为最接近的默认字体来替换。替换之后的字体度量（字宽、行高、字间距）不同，文本内容就会重新排版。

用“微软雅黑”这个典型例子：Word里一行能放30个字，LibreOffice用文泉驿微米黑替代后，恐怕一行只能放28个字，那每个段落的行数就会变多，最后可能多出一页或两页内容。如果文档末尾正好有个分页符，或者有个空白段落，转成PDF就可能看到一个多出来的全空白页。很多人以为是代码的问题，其实是把排版引擎渲染差异当成了Bug。

解决思路分三步：第一步，把业务文档用到的字体尽量全部装到服务器上，最直接的效果就是让LibreOffice不需要做任何字体替换；第二步，如果字体确实无法安装（比如某款收费字体），就在Word侧尽量用常见字体，系统默认字体最省事；第三步，检查文档里是否存在多余的分页符和空段落，把这些手动清掉。关于分节符还要多说一句，Word的“下一页分节符”在转PDF时如果遇上内容刚好填到页面末尾，本来就容易产生多页。

5.2 “Word转PDF提示未响应”是怎么踩出来的

前面提过，用Office COM组件在服务器上跑转换就有这个毛病，这里展开说说。很多人刚开始做这个需求时，一搜教程看到最简单的方案是“调用Word另存为”，于是就在服务器上装了Office，再用Java调“命令行宏”或者“jscom”这类东西去操作Word。Word本身是图形界面程序，在服务器无人值守状态下，弹个“文档被占用”的提示框，或者等到某个“恢复文档”弹窗，进程就卡死在那里了，表现就是未响应。

这个问题的根源是Word的COM接口不是为并发服务端连续调用设计的。而LibreOffice则不同，它支持headless模式，也就是完全无界面的情况下运行，专门为这种服务器文档转换场景而生。所以遇到“未响应”，最省心的解法就是把方案从“Office + COM”换成“LibreOffice + JODConverter”。这不是技术调优能解决的，而是选型就需要纠偏。

5.3 中文乱码、转换后格式错乱、转换失败等高频问题速查

我把这几年被问得最多的问题整理成一张表，方便你直接对照排查：

现象	大概率原因	解决方案
中文变成方块或“?”	服务器缺少中文字体	安装fonts-wqy-zenhei、fonts-wqy-microhei等中文字体包，或上传业务需要的字体
转换后版式偏移，多页空白	字体缺失导致重新分页	补齐所有业务字体，清理源文档多余分页符/分节符
转换非常慢	文档过大，或LibreOffice进程内存膨胀	上调task-execution-timeout，设置max-tasks-per-process定期重启进程
转换偶发失败，报超时异常	同一时间任务并发超过进程处理能力	调大端口数（进程数），或调大queue-timeout
转换报“office home not found”	JODConverter没找到LibreOffice安装目录	在配置里显式指定office-home
图片或图形元素丢失	docx里的嵌入对象或特殊图形LibreOffice不兼容	确认文件的完整性和格式版本，复杂OLE对象很难完美转换
Linux下转换报错，权限不足	Java进程没有LibreOffice安装路径和临时目录的读写权限	调整目录权限，或让Java进程使用独立用户并赋予必要权限

5.4 排查思路：日志、临时目录、命令行三板斧

代码写完之后，最忌讳的就是不看日志瞎猜。JODConverter启动时会扫描LibreOffice安装信息，这些日志在排查问题时很有用。Spring Boot配置里把日志级别调成DEBUG一次，能看清楚JODConverter到底有没有成功连接某个端口，或者在找office-home时到底探测到了哪里。

第二个排查突破口是临时目录。JODConverter处理文档时会在工作目录（默认是java.io.tmpdir）生成中间文件，很多转换失败其实在中间步骤就出错了，你只要去临时目录看一眼有没有生成异常文件，就能大致判断是读取阶段挂的还是渲染阶段挂的。

第三个办法最直接：完全绕过Java，先用命令行手工测一下LibreOffice能不能转。在服务器上执行：

bash复制soffice --headless --convert-to pdf --outdir /tmp/test /tmp/test.docx

同样的文件，命令行能转，Java调不通，那就是JODConverter连接或配置问题；命令行也转不好，那就是LibreOffice环境问题，跟Java半毛钱关系没有。这个板斧能帮你把问题快速切到正确的排查方向。

6. 最后分享点个人经验

做这个功能几年下来，我的整体感受是：Java做Word转PDF真的不难，难的是你愿不愿意在环境上下足功夫。很多人一上来就搜代码，代码贴进去跑不通，又怀疑是库的问题，兜兜转转好几天，最后发现是服务器少装了一个字体包，这种感觉我太熟悉了。所以再啰嗦一句：先装LibreOffice，再装齐字体，最后才是写代码。顺序不要乱。

JODConverter也提供了一些进阶能力，比如把转换任务包装成独立的远程服务，通过Spring Boot的starter部署成微服务，供多个业务方调用。如果你的公司里有很多系统都需要文档转换，把转换能力抽成一个独立的service会是很划算的事，避免每个项目都去装一遍LibreOffice。

最后再分享一个实用小技巧，调试排错时可以拿着源文件在服务器上用LibreOffice直接转一次对比结果，这是最接近Java实际运行环境的验证方式。毕竟代码只是调用方，真正干活的始终是LibreOffice这个“引擎”。引擎没问题，代码就是问题；引擎有问题，改代码也白搭。新手尤其要养成这个思维习惯，能省下大把时间。