Java SpringBoot將Word文檔轉為PDF的全流程解析

更新時間：2025年05月30日 09:40:30 作者：天天摸魚的java工程師

在 Java 里,能把 Word 轉 PDF 的工具還真不少,本文主要來和大家聊聊Java如何整合SpringBoot實現(xiàn)將Word文檔轉為PDF的全流程,有需要的可以了解下

一、需求分析

首先，用戶說的 “Word 文檔” 其實挺寬泛的。Word 文檔有.doc和.docx兩種常見格式，.doc是老版本的二進制格式，.docx是基于 XML 的壓縮格式，處理方式完全不一樣。另外，文檔里可能有圖片、表格、公式、超鏈接，甚至還會有頁眉頁腳，這些內容在轉換過程中都得保證原樣顯示，不能丟東西、亂排版。

還有，從系統(tǒng)角度看，得考慮轉換效率和穩(wěn)定性。要是用戶上傳個幾十 MB 的大文檔，轉換半天沒反應，或者直接把服務器搞崩了，那肯定不行。最后，還得做好異常處理，比如文檔格式不對、文件損壞，這些情況都得給用戶友好的提示。

二、技術選型

明確需求后，就得找趁手的工具了。在 Java 里，能把 Word 轉 PDF 的工具還真不少。

第一個想到的是 Apache POI，它能讀寫 Word 文檔，但是它主要側重于文檔內容的操作，直接轉 PDF 還得配合其他庫，有點麻煩，而且對復雜格式支持不太好，就先 pass 掉。

然后是 Aspose.Words，這個庫功能超強大，幾乎能完美支持所有 Word 格式和元素，轉換效果也很好。但它是收費的，要是公司預算充足，其實是個不錯的選擇。

最后，我盯上了 Docx4j。它是開源的，對.docx格式支持特別好，轉換 PDF 也很方便，社區(qū)資料也多，遇到問題能找到不少解決方案。雖然對老版本.doc支持差點，但現(xiàn)在主流都是.docx，權衡之下，就它了！

三、Spring Boot 整合

確定用 Docx4j 后，就開始把它集成到 Spring Boot 項目里。

先打開pom.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 的核心庫，第二個是用來把 Word 文檔轉成 PDF 的模塊。加完依賴，Maven 會自動把需要的 jar 包下載下來。

四、代碼實現(xiàn)

接下來就是寫代碼了，咱們新建一個工具類WordToPdfConverter：

import org.docx4j.Docx4J;
import org.docx4j.fonts.IdentityPlusMapper;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.docx4j.openpackaging.parts.WordprocessingML.MainDocumentPart;
import org.docx4j.pdf2HTMLEx.PdfSettings;
import org.docx4j.utils.fonts.FontUtils;
import java.io.File;
import java.io.FileOutputStream;
import java.io.OutputStream;
public class WordToPdfConverter {
    public static void convert(String inputFilePath, String outputFilePath) {
        try {
            // 加載Word文檔
            WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(new java.io.File(inputFilePath));
            // 處理字體，解決中文亂碼問題
            FontUtils.setFontInfo(wordMLPackage);
            IdentityPlusMapper fontMapper = new IdentityPlusMapper();
            fontMapper.put("隸書", "LiSu");
            fontMapper.put("宋體", "SimSun");
            fontMapper.put("黑體", "SimHei");
            fontMapper.put("楷體", "KaiTi");
            wordMLPackage.setFontMapper(fontMapper);
            // 獲取文檔的主部分
            MainDocumentPart documentPart = wordMLPackage.getMainDocumentPart();
            // 創(chuàng)建PDF設置
            PdfSettings pdfSettings = new PdfSettings();
            // 設置字體嵌入，防止在其他設備上顯示異常
            pdfSettings.setFontEmbeddingEnabled(true);
            // 執(zhí)行轉換
            OutputStream os = new FileOutputStream(new File(outputFilePath));
            Docx4J.toPDF(wordMLPackage, os, pdfSettings);
            os.close();
            System.out.println("轉換成功！");
        } catch (Exception e) {
            e.printStackTrace();
            System.out.println("轉換失?。? + e.getMessage());
        }
    }
}

代碼解釋：

WordprocessingMLPackage.load方法加載指定路徑的 Word 文檔。
處理字體部分，因為默認可能會出現(xiàn)中文亂碼，通過IdentityPlusMapper指定常用中文字體的映射關系。
PdfSettings用來配置 PDF 轉換的參數(shù)，這里開啟了字體嵌入，這樣生成的 PDF 在其他設備上打開，字體也不會錯亂。
最后用Docx4J.toPDF方法執(zhí)行轉換，把轉換后的內容輸出到指定的文件路徑。

在 Spring Boot 的 Controller 里調用這個方法，就能提供轉換接口了：

import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.io.File;
import java.io.IOException;
import java.util.UUID;
@RestController
@RequestMapping("/convert")
public class WordToPdfController {
    @PostMapping
    public String convertWordToPdf(@RequestParam("file") MultipartFile file) {
        try {
            // 生成臨時文件路徑
            String originalFilename = file.getOriginalFilename();
            String tempFilePath = System.getProperty("java.io.tmpdir") + File.separator + UUID.randomUUID() + "_" + originalFilename;
            file.transferTo(new File(tempFilePath));
            // 生成輸出PDF文件路徑
            String outputFilePath = System.getProperty("java.io.tmpdir") + File.separator + UUID.randomUUID() + ".pdf";
            // 執(zhí)行轉換
            WordToPdfConverter.convert(tempFilePath, outputFilePath);
            // 返回下載鏈接或者處理邏輯
            return "轉換成功，PDF路徑：" + outputFilePath;
        } catch (IOException e) {
            e.printStackTrace();
            return "文件處理失?。? + e.getMessage();
        }
    }
}

在這個 Controller 里，@PostMapping定義了一個接收文件上傳的接口。先把上傳的文件保存到臨時目錄，再調用WordToPdfConverter.convert方法進行轉換，最后可以根據實際需求，把生成的 PDF 返回給用戶下載，或者存到指定位置。