Java 調用 wkhtmltox 實現 HTML 轉 PDF/圖片：跨平台安裝與踩坑指南

技術選型演進

項目需將 HTML 內容歸檔為 PDF 或圖片。初期採用 Flying Saucer（iText 渲染），雖解決中文與圖片路徑問題，但 CSS3 支持極弱（如無法渲染斜線）。嘗試 CSSBOX 生成圖片，同樣不支持 CSS3 進階特性。最終選擇 wkhtmltox（含 wkhtmltopdf、wkhtmltoimage），基於 WebKit 內核，對 HTML5/CSS3 支持優異，通過命令行調用，雖需安裝本地程序但效果最佳。

軟件獲取

• 官網：wkhtmltopdf.org
• 本文使用 0.12.2 穩定版：下載目錄

Windows 環境安裝

下載 wkhtmltox-0.12.2_msvc2013-win64.exe（32 位選對應版本），雙擊安裝。安裝目錄下將包含 wkhtmltopdf.exe、wkhtmltoimage.exe 兩個可執行文件，供後續調用。

Linux (CentOS 6.5 32位) 安裝實錄

1. 下載 RPM 包：
   wget https://download.gna.org/wkhtmltopdf/0.12/0.12.2/wkhtmltox-0.12.2_linux-centos6-i386.rpm
   或本地下載後 rz -be 上傳（大文件需 -be 參數，無 rz 先 yum -y install lrzsz）
2. 嘗試安裝：rpm -ivh wkhtmltox-0.12.2_linux-centos6-i386.rpm
   報錯缺少 xorg-x11-fonts-Type1、xorg-x11-fonts-75dpi 依賴
3. 安裝依賴：
   yum -y install xorg-x11-fonts-Type1
yum -y install xorg-x11-fonts-75dpi
4. 再次安裝 wkhtmltox，成功。
5. 驗證：wkhtmltoimage https://www.baidu.com 1.jpg 或 wkhtmltopdf https://www.baidu.com 1.pdf 生成文件即安裝成功。

Java 程式調用實現

無需額外 Jar 包，直接通用 Runtime.exec() 調用命令行：

public class CustomWKHtmlToPdfUtil {
    public String getCommand(String sourceFilePath, String targetFilePath) {
        String os = System.getProperty("os.name");
        if (os.contains("Windows")) {
            return "D:\\Program Files\\wkhtmltopdf\\wkhtmltoimage.exe " + sourceFilePath + " " + targetFilePath;
        } else if (os.contains("Linux")) {
            return "wkhtmltoimage " + sourceFilePath + " " + targetFilePath;
        }
        return "";
    }

    public static void main(String[] args) throws Exception {
        CustomWKHtmlToPdfUtil util = new CustomWKHtmlToPdfUtil();
        String cmd = util.getCommand("e:/html/result.html", "e:/html/result.jpg");
        Process process = Runtime.getRuntime().exec(cmd);
        process.waitFor(); // 關鍵：等待命令執行完成
        System.out.println("執行完成");
    }
}

跨平台關鍵點

• Windows 需指定可執行文件絕對路徑；
• Linux 安裝後命令已加入系統 PATH，直接調用命令名即可；
• process.waitFor() 必須調用，否則主線程繼續執行導致輸出文件不全或為空。

實戰建議與避坑

• 推薦優先生成 JPG 圖片（wkhtmltoimage），PDF 生成偶發排版異常；
• HTML 中圖片路徑建議使用絕對路徑或 file:// 協議，避免相對路徑解析失敗；
• 中文字體渲染需確保系統安裝中文字體（如文泉驛微米黑），否則出現方框亂碼；
• 大文件/複雜頁面轉換耗時較長，建議異步處理並設置超時機制。

總結

wkhtmltox 憑藉 WebKit 內核完美支持現代 HTML/CSS，是 Java 端 HTML 轉 PDF/圖片的最佳選擇。跨平台部署只需處理好依賴與路徑差異，調用方式簡單直接，生產環境穩定可靠。