基于docx4j的SpringBoot文件转换：DOCX转PDF完整指南

上个月做内部文件服务时，接了一个很不新鲜的需求：把系统里生成的 Word 合同、验收报告转成 PDF，用在线预览和归档。调研了一圈，最终选了 docx4j 这套纯 Java 方案，在 SpringBoot 服务里做了完整封装。如果你也在做类似的 DOCX 转 PDF 功能，又不想让服务器额外安装办公软件，这篇文章应该能帮你少踩几个坑。

docx4j 的好处很多，但对后端团队来说最核心的一点是：它不依赖外部进程，不需要在服务器上装 Office 或办公套件，转换过程在 JVM 内直接完成。这意味着无论是物理机还是容器化部署，都不用额外操心系统依赖。我这次做的项目需要跑在一套资源受限的容器环境里，服务本身还要支持批量转换，docx4j 是当时综合评估下来最合适的开源路线。

1. 方案选型与设计思路：为什么是 docx4j

1.1 先把主流路线摆出来

DOCX 转 PDF 这件事，稍微有点经验的开发者都能想到几条路线，但每条都有明显的代价。我在动手之前把市面上的主流方案过了一遍，核心就四个方向。

第一种是调用本机办公套件的 headless 模式，比如用命令行参数直接做转换。这个路线转换质量确实高，因为渲染引擎就是本机的文字处理软件，但麻烦在于部署。容器里要额外安装整套办公软件，镜像体积暴涨，而且不同版本的命令行参数有差异，每次升级系统都得重新验证，维护成本不低。

第二种是商业文档处理库。这类库内部有完整的渲染引擎，转换还原度很高，文档处理细节也很完善，适合对输出效果有极致要求的场景。但代价也很直接：授权费用不便宜，而且公司采购时需要走许可证审查流程，周期长，很多小项目根本等不起这一轮评估。

第三种是 Apache POI 加 PDF 库的组合。POI 负责读取 Word 内容，然后想办法用 PDF 库自己画出来。这个方案看似灵活，实际上是个深坑。POI 的主要能力在于创建和修改 docx，并不是为 PDF 排版设计的。你读出来段落、表格、样式之后，还要自己实现一套排版引擎，处理分页、字体测量、行距换算，工作量完全是做轮子，而且复杂格式还原度很难保证。

最后就是 docx4j。它直接针对 OpenXML 规范做解析，能把 docx 的文档对象模型完整加载到内存里，然后通过内置的 PDF 转换链路渲染输出。纯 Java 实现，没有外部依赖，SpringBoot 项目引入依赖就能跑，部署模式和普通应用完全一致。它还自带文档对象树的修改能力，所以如果你还需要在转换前做一些处理，比如加页眉页脚、替换文本、清理修订记录，docx4j 都是顺手的事。

我把这几个方向整理成一张表，方便你根据自己项目情况做判断：

对大多数业务系统来说，docx4j 的还原度已经足够。它不能做到和 Word 里所见完全一致，但应付合同、报告、说明书这类程序生成的规范文档没有任何问题。

1.2 docx4j 的转换原理与轻量边界

如果你之前没有接触过 docx4j，先花两分钟理解一下它的原理，后面排查问题会非常有帮助。

docx 文件本质上是一个 ZIP 压缩包，里面按 OPC 规范组织了很多 XML 部件，最重要的就是 word/document.xml，它记录了正文内容，word/styles.xml 记录样式，word/media 下面放着图片。docx4j 用 JAXB 技术把这些 XML 映射成 Java 对象树，你操作的是一棵完整的文档对象树，而不是纯文本字符串。

转 PDF 的时候，docx4j 也不是像截图工具那样把 Word 页面“拍”下来。它的内部链路大致是：先解析文档对象树，生成一种中间排版描述，再交给 Apache FOP 渲染成 PDF。这个链路决定了它的能力边界：凡是能在 Word 文档对象树里表达清楚的内容，比如段落、表格、页眉页脚、分页、多级列表，都能转得比较稳定；但凡是依赖 Word 客户端做精密排版的内容，比如复杂的浮动文本框、域代码、交叉引用、嵌入对象，还原度就会打折扣。

这一点非常关键。我见过很多项目上线后出现纠纷，就是需求方默认“转出来的 PDF 应该和 Word 一模一样”，但技术方案根本做不到像素级还原。所以选 docx4j 之前，一定要先明确业务接受度。我这次的做法是拿三份真实业务文档做验收样本，先转出来给需求方看，确认 95% 以上的页面都能接受，再进入开发。

2. SpringBoot 项目基础搭建与依赖版本选择

2.1 Maven 依赖版本选择：8.x 还是 11.x

依赖引入是整个项目里第一个容易翻车的地方。docx4j 版本差异比较大，网上很多教程用的旧代码拿过来直接会报错。

我现在这个服务是基于 SpringBoot 2.x 和 JDK 8 的，用的依赖坐标是这样的：

xml复制<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j</artifactId>
    <version>8.3.3</version>
</dependency>

<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-export-fo</artifactId>
    <version>8.3.3</version>
</dependency>

这里有个细节需要说明。docx4j 从 6.x 开始就拆分了多个模块，核心操作类在 docx4j 里，而 PDF 转换相关功能在 docx4j-export-fo 里。如果你只引了核心包，加载类的时候会报 NoClassDefFoundError，错误信息里能看到 viaXSLFO 之类很陌生的包名。所以 PDF 转换场景下，docx4j-export-fo 必须一起引入。

如果你的项目已经升级到 SpringBoot 3.x 和 JDK 17，我的建议是用 docx4j 11.x 系列，而不是强行让老版本兼容新环境。因为从某一个大版本开始，docx4j 把 JAXB 的命名空间从 javax.xml.bind 换成了 jakarta.xml.bind，不换版本的话会遇到典型的 JAXB 类找不到问题。我自己习惯上就是 SpringBoot 2 配 docx4j 8.3.3，SpringBoot 3 配 docx4j 11.x，不去折腾跨版本兼容。

依赖冲突也是要提前处理的。docx4j 传递依赖里带了 slf4j、commons-io 这些常用库，如果你的项目里已经引入了特定版本，直接用 Maven 的 exclusion 把传递依赖排掉就好，不用太过担心。真正需要关注的是 JAXB 相关包。JDK 8 没问题，但如果你在 JDK 11 以上跑老版本 docx4j，需要额外补 javax.xml.bind:jaxb-api 和相关实现，否则一加载就抛异常。

2.2 初始化配置与目录规划

转换服务因为要处理文件 IO，也涉及字体文件的位置，所以我在项目里单独抽出了一些配置项，放在 application.yml 里统一管理。

yaml复制file:
  upload-dir: ${TEMP_DIR:/tmp/docx-service/upload}
  output-dir: ${TEMP_DIR:/tmp/docx-service/output}
  font-dir: /usr/share/fonts

docx4j:
  pool-size: 4
  max-wait-seconds: 300

这里有个值得说的设计思路：file.upload-dir 和 file.output-dir 我建议都放在系统临时目录下，而不是项目根目录。因为生产环境跑容器的时候，项目目录往往是只读层，写不进去，而临时目录通常都挂载成了可写卷。同时，这两个目录一定要做定期清理，否则转换量一大，磁盘会被文件堆满。

file.font-dir 是给字体问题预留的。你后面会看到，Linux 环境下转中文 PDF 最容易翻车，原因就是字体找不到。把这个目录暴露成配置项，运维在部署时可以直接挂载字体目录，不用改代码。

配置类我用 Spring Boot 的 @ConfigurationProperties 来绑定，保持代码整洁。这些看起来很基础，但很多项目都是因为没做目录规划，上了生产才开始手忙脚乱地补环境。

3. 核心转换实现与字体处理

3.1 最小可用的转换服务代码

整个转换的核心代码其实非常短。先给你看一个最小可用的 Service 方法，这段代码我实测在 SpringBoot 2 + docx4j 8.3.3 环境下能直接跑通。

java复制import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.docx4j.convert.out.pdf.viaXSLFO.Conversion;

public byte[] convertDocxToPdf(byte[] docxBytes) throws Exception {
    try (ByteArrayInputStream in = new ByteArrayInputStream(docxBytes);
         ByteArrayOutputStream out = new ByteArrayOutputStream()) {

        WordprocessingMLPackage wordMLPackage =
            WordprocessingMLPackage.load(in);

        // 如果有自定义字体映射，在这里设置
        // wordMLPackage.setFontMapper(customFontMapper);

        Conversion.toPdf(wordMLPackage, out);
        return out.toByteArray();
    }
}

有几个操作要点需要说清楚。

第一，WordprocessingMLPackage.load 可以直接接收 InputStream，也可以接收 File。我的接口层拿到的往往是上传的字节数组，所以我选择直接用 ByteArrayInputStream 加载，避免先落盘再读取。但如果文件特别大，比如超过 20MB，建议先保存到临时文件再做转换，否则内存压力会很大。

第二，Conversion.toPdf 这个类名在不同版本里可能会有差异。docx4j 8.x 里它在 org.docx4j.convert.out.pdf.viaXSLFO 包下，我看到一些旧教程里写的是别的路径。如果你用的版本不一样，建议用 IDE 的类搜索功能直接搜 toPdf 方法，确认导入路径，不要硬抄。

第三，也是很容易忽略的：WordprocessingMLPackage 对象不是线程安全的。同一个对象不能交给多个线程同时转 PDF，因为转换过程中可能会修改内部状态。看起来只是读操作，但底层解析和索引构建会有内部数据变化。批量场景下，每个任务必须独立加载一份新的对象，这个下面讲批量转换的时候还会再提。

第四，如果服务跑在无图形界面的服务器上，建议在启动脚本里加上 -Djava.awt.headless=true。docx4j 在解析字体和渲染时可能会触发 AWT 相关调用，headless 模式可以避免一些不必要的环境问题。

3.2 中文字体映射：最容易翻车的一环

说实话，我现在看网上关于 docx4j 的讨论，十有八九是关于中文方块字的。这个问题必须单独拉出来讲，因为它在 Windows 本地测试时根本发现不了，一部署到 Linux 服务器，转出来的 PDF 里所有中文都是一个个小方块，用户一看就炸。

先解释一下原因。docx 文件里记录的是字体名称，比如“宋体”“微软雅黑”，转换到 PDF 时，渲染引擎必须找到服务器上实际存在的物理字体文件来绘制字形。Windows 自带中文字体，所以本地测试没问题。但很多 Linux 精简版服务器一个中文字体都没装，渲染引擎找不到字体，就只能输出占位方块。

解决思路有两个方向，实际项目里可以一起用。

第一个方向，在服务器或容器镜像里安装中文字体。以常见的 Debian 系镜像为例，Dockerfile 里可以加这么一段：

dockerfile复制RUN apt-get update && apt-get install -y \
    fonts-wqy-microhei \
    fonts-wqy-zenhei \
    && rm -rf /var/lib/apt/lists/*

文泉驿微米黑和文泉驿正黑都是开源中文字体，覆盖常用简体字，作为业务文档的兜底字体完全够用。装完之后可以用 fc-list | grep -i wqy 确认字体是否被系统识别。这里要注意，如果系统里有 Java 字体缓存机制，新装字体后可能需要重启 Java 进程才会生效。

第二个方向是在代码里做字体映射。docx4j 提供了 FontMapper 机制，可以把 docx 里声明的字体名，映射成服务器上真实存在的物理字体。这样即使 docx 里写的是“宋体”，渲染时也可以用思源宋体或者文泉驿正黑替代。

docx4j 的 FontMapper 接口在不同版本里方法签名有差异，我这里给一段设计思路的伪代码，你按自己引入的版本把方法签名调整一下就能用：

java复制// 思路：自定义 FontMapper，把缺失字体替换成系统存在的字体
FontMapper customFontMapper = new FontMapper() {
    @Override
    public Font map(String fontName) {
        // 优先按原名找
        Font font = PhysicalFonts.get(fontName);
        if (font == null) {
            // 找不到就替换成文泉驿正黑
            font = PhysicalFonts.get("WenQuanYi Zen Hei");
        }
        return font;
    }
};
wordMLPackage.setFontMapper(customFontMapper);

这段代码不是让你直接复制，而是让你理解处理思路。真实项目里我会直接采用第一种方案装字体，因为操作简单、见效快。代码映射毕竟是在做替换，中文字体不同字型的度量可能不一致，极端情况下会影响排版尺寸，所以能用系统字体解决的就不要额外做映射。

部署之后还有一个验证技巧：在启动日志里看一下 docx4j 初始化字体时打印的信息，它会显示发现了多少字体文件。如果数字很小，基本可以确认字体环境有问题。

3.3 复杂样式转换的边界与妥协

用 docx4j 时间长了，你就会摸清它的脾气。普通的段落、标题、表格、页眉页脚、页码这些基础能力，它处理得相当稳定。我这次处理的合同文件里有大量表格，转出来之后边框、合并单元格、行高基本都在可接受范围内，没有出现排版错乱。

真正容易出问题的是 Word 里那些“看起来没什么技术含量”的细节。比如页边距设置方式不标准、段落行距用了固定值、表格单元格里嵌套了多层浮动对象，还有比较复杂的交叉引用和域代码。这些内容在 Word 里打开很正常，但 docx4j 解析之后，渲染结果就会出现偏差。

我个人的经验是，不要把问题留到转换环节才解决。最好在业务模板源头上做规范：要求模板制作人员使用 Word 内置样式而不是手动微调格式，避免插入复杂浮动文本框，页脚内容的锚定方式统一用标准模式。同时，在转换前用代码做一些预处理，比如清除修订记录、删除评论、移除嵌入的旧版对象。docx4j 的文档对象树支持这些修改，比正面硬刚复杂的渲染问题省力得多。

另外，你可能会遇到某些工具生成的 docx 文件，在 docx4j 里加载时直接报异常。这类文件往往来自兼容性很差的第三方编辑工具，生成的文件结构不规范。遇到这种情况，不必死磕代码，先用 Word 本身打开另存为标准 docx，再重新转换，十有八九能解决。

4. 批量转换、异步化与性能优化

4.1 线程池配置与内存估算

单文档转换跑通不算完，生产环境一定会有批量转换需求。用户一次性上传几百份合同，如果同步逐份转换，接口响应时间会拉到分钟级，必须走异步任务。

批量转换首先要考虑线程池参数。docx4j 转换是个吃 CPU 和内存的活，它不是简单的 IO 操作，中间要解析 XML、构建对象树、渲染排版。线程数开太大会把服务器内存直接打爆，开太小则转换速度上不去。

我的配置经验是：4 核 8G 的容器，转换线程控制在 4 个左右，最多不超过 6 个。线程池代码大致这样：

java复制ThreadPoolExecutor executor = new ThreadPoolExecutor(
    4, 4,
    0L, TimeUnit.MILLISECONDS,
    new LinkedBlockingQueue<>(200),
    new ThreadPoolExecutor.CallerRunsPolicy()
);

这里有几个点要说一下。核心线程数和最大线程数我设为一样，避免线程数动态波动导致资源不稳定。拒绝策略用的 CallerRunsPolicy，意思是队列满了之后，提交任务的操作方自己来跑这个任务，相当于一种反向限流，不会把任务直接丢弃。

内存估算也要提前做好。docx4j 会把整个 docx 解析成 JAXB 对象树，我实测过一份 10MB 左右的 docx，加载进内存后 JVM 堆占用会膨胀到 200MB 上下。如果你同时跑 4 个转换线程，光是文档对象树就能吃掉接近 1G 内存，这还没算渲染过程和临时对象的开销。所以容器内存使用权不要设太大，堆内存建议至少给 2GB，并且要搭配线程数量控制。

4.2 批量任务编排与临时文件清理

批量转换的时候，我习惯用一个信号量来做更细粒度的并发控制。线程池只是限制了同时执行的任务数，但如果有多个业务同时触发批量转换，任务会大量涌入队列，还是可能把内存撑爆。信号量可以在更高的调用层次上限制同时处理的文档总量。

java复制Semaphore semaphore = new Semaphore(4);

CompletableFuture.runAsync(() -> {
    semaphore.acquire();
    try {
        byte[] pdf = conversionService.convertDocxToPdf(docxBytes);
        // 处理转换结果
    } finally {
        semaphore.release();
    }
}, executor);

这里 try/finally 必须写，否则任务一异常，信号量就永远不释放，整个服务慢慢就被堵死了。

临时文件的清理也是一个很容易被忽视的点。之前提到大文件建议落盘转换，但如果每个任务都往临时目录写文件又不清理，两三天时间磁盘就能堆满。我目前的做法是：上传文件保存在 file.upload-dir，转换完成后立即删除源文件；输出的 PDF 如果业务需要保留，则挪到对象存储或专门的持久化目录，临时输出目录里的中间文件在任务结束的 finally 块里删除。

还有一个实用建议：接口层如果只是需要把 PDF 字节流返回给前端，尽量用 byte[] 直接在内存里走，不要每次都写磁盘。只有文件确实大到内存扛不住，才考虑硬盘中转。我在项目里的判断标准是 20MB 为界，小于这个值的文档全部走字节流。

4.3 REST 接口封装：上传即下载

为了方便前端调用，我把转换能力封装成了一个简单的 REST 接口。上传 DOCX 文件，接口直接返回 PDF 流。

java复制@PostMapping(value = "/convert", produces = MediaType.APPLICATION_PDF_VALUE)
public ResponseEntity<byte[]> convert(
        @RequestParam("file") MultipartFile file) throws IOException {

    byte[] pdfBytes = conversionService.convertDocxToPdf(file.getBytes());

    return ResponseEntity.ok()
            .header("Content-Disposition",
                    "attachment; filename*=UTF-8''" + URLEncoder.encode("output.pdf", "UTF-8"))
            .body(pdfBytes);
}

接口同步还是异步，取决于文件大小和并发量。我这个场景单文件平均 5MB 左右，转换时间在 2 到 5 秒之间，用户能接受同步等待，所以接口直接返回字节流。如果文档非常大，或者单次提交几十个文件，建议改成异步任务模式：上传后立即返回任务 ID，前端轮询任务状态，转换完成后下载结果。

Content-Disposition 处理有个坑值得提醒：不要直接在响应头里写中文文件名，Excel、PDF 下载下来经常变成乱码。用 URLEncoder.encode 加 filename*=UTF-8'' 的写法，兼容性会好很多。这是我踩过一次坑之后学到的。

5. 常见问题与排查技巧实录

5.1 问题速查表

把这段时间遇到的典型问题整理成一张表，方便你快速定位：

5.2 几个亲身踩过的坑

第一个坑是字体缓存。我第一次在 Linux 上部署时，发现服务器其实已经装了文泉驿字体，但转出来的 PDF 依然全是方块。排查了很久才发现，docx4j 的 PhysicalFonts 在进程启动时会把系统字体加载进缓存，字体是后来装上的，进程运行期间根本不会去刷新。重启服务之后一切正常。所以容器镜像里装字体，一定要赶在 Java 进程启动之前完成，Dockerfile 里写在 RUN 阶段就是对的。

第二个坑是线程安全理解不到位。刚开始优化批量转换时，我以为加载一次文档对象，然后用它处理所有页面就行，结果多个任务同时跑，日志里出现了各种奇怪的并发错误，有的页面内容串了，有的直接抛数组越界。后来一查文档，WordprocessingMLPackage 确实不是线程安全的。解决方案很直接：每个任务独立加载文件，不共享对象，虽然多花一点加载时间，但能保证结果准确。

第三个坑是 SpringBoot 3 环境下使用老版本 docx4j。当时还没意识到 javax.xml.bind 和 jakarta.xml.bind 的区别，服务一起动就报类找不到。解决倒是简单，换到 docx4j 11.x 系列，并把 pom 里的相关依赖同步调整就好了。但这个错误很有迷惑性，因为报错信息不直接指向版本问题，而是指向 JAXB 底层类，不熟悉的人很容易去依赖冲突的方向排查很久。

第四个坑是文件名的中文编码。接口返回 PDF 时，如果直接在 Content-Disposition 里写死 attachment; filename=合同.pdf，前端下载默认存出来的文件名就是乱码。后来统一改成 filename*=UTF-8'' 加 URL 编码的方式，问题才解决。

5.3 排查思路与日志定位

最后分享一个排查思路。如果转换结果不对，不要急着怀疑代码逻辑，先把 docx 文件本身拆开看。docx 就是个 ZIP 包，你可以用下面的命令直接看它的正文内容：

bash复制unzip -p 测试文件.docx word/document.xml | head -c 2000

这能看到文档内部实际的 XML 结构。很多排版问题都能从这里找到端倪，比如字体声明是不是不标准、有没有奇怪的修订标签、段落属性是不是被内联样式覆盖了。

排查转换问题时，建议打开 docx4j 的 debug 日志。在 application.yml 里把 org.docx4j 的日志级别调到 DEBUG，运行时它会打印出关键的解析和转换信息，包括字体加载情况、对象树构建的耗时，这些数据对定位问题非常有帮助。

还有一个小技巧：转换服务的测试环境尽量模仿生产环境。如果你本地是 Windows，测试也只在 Windows 上跑，那么字体、路径、文件权限这些问题都发现不了。我现在的习惯是本地跑单元测试用内存文件流，但在部署前一定先打一个 Linux 基础镜像的容器，跑一遍完整的转换流程，确认没问题再上生产。

最后说一个我长期养成的习惯。这种转换服务上线前，一定准备一份包含中文、表格、页眉页脚、分页符、多级列表的样本文件，先把转换结果截图给需求方确认，再上量。字体问题只有在真实服务器环境才会暴露，本地 Windows 永远转得好看，部署到 Linux 立刻翻车。docx4j 方案整体上很轻量、很可靠，但它不是万能的转换引擎，提前管理好需求方的预期，开发过程会平稳很多。如果你后续还要做模板生成、加水印、批量导出这类功能，docx4j 的文档对象树模型都能继续复用，在这个基础上扩展并不费劲。