Java 集成 wkhtmltopdf 實現 HTML 轉 PDF：從命令行到工具類封裝

背景與選型

傳統 iText 需手寫模板，面對數百張表單導出極不靈活。wkhtmltopdf 基於 WebKit 渲染引擎，可直接將生成的 HTML 頁面高保真轉為 PDF，支援複雜 CSS/JS，是動態報表導出的理想選擇。

• 官網：wkhtmltopdf.org
• GitHub：wkhtmltopdf/wkhtmltopdf

核心原理

命令行調用：

wkhtmltopdf.exe https://www.cnblogs.com c:\cnblogs.pdf

Java 中通過 Runtime.getRuntime().exec() 執行命令實現轉換。

工具類封裝設計

1. 異步流讀取器（防止緩衝區阻塞）

public class HtmlToPdfInterceptor extends Thread {
    private InputStream is;
    public HtmlToPdfInterceptor(InputStream is) { this.is = is; }
    public void run() {
        try (InputStreamReader isr = new InputStreamReader(is, "utf-8");
             BufferedReader br = new BufferedReader(isr)) {
            String line;
            while ((line = br.readLine()) != null) {
                System.out.println(line); // 或寫入日誌
            }
        } catch (IOException e) { e.printStackTrace(); }
    }
}

2. 核心轉換類

public class HtmlToPdf {
    private static final String TO_PDF_TOOL = "D:\\wkhtmltopdf\\bin\\wkhtmltopdf.exe";

    public static boolean convert(String srcPath, String destPath) {
        File file = new File(destPath);
        File parent = file.getParentFile();
        if (!parent.exists()) parent.mkdirs();

        StringBuilder cmd = new StringBuilder();
        cmd.append(TO_PDF_TOOL).append(" ");
        cmd.append("--header-line ");                    // 頁眉分隔線
        cmd.append("--header-center \"頁眉內容\" ");      // 頁眉居中
        cmd.append("--header-spacing 10 ");              // 頁眉與內容間距
        // cmd.append("--margin-top 30mm ");             // 可選：上邊距
        cmd.append(srcPath).append(" ").append(destPath);

        try {
            Process proc = Runtime.getRuntime().exec(cmd.toString());
            new HtmlToPdfInterceptor(proc.getErrorStream()).start();
            new HtmlToPdfInterceptor(proc.getInputStream()).start();
            proc.waitFor();
            return true;
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    }

    public static void main(String[] args) {
        convert("https://www.cnblogs.com/xionggeclub/p/6144241.html", "d:/wkhtmltopdf.pdf");
    }
}

wkhtmltopdf 核心參數速查表

頁眉頁腳變量

• [page] 當前頁碼
• [topage] 總頁數
• [section] 當前章節標題
• [date]/[time] 日期/時間
• [webpage] 頁面 URL

生產環境建議

• 使用 ProcessBuilder 替代 Runtime.exec()，更靈活控制環境變量、工作目錄
• 超時控制：proc.waitFor(timeout, TimeUnit) 防止掛死
• 異常流/輸出流必須異步消費，避免管道阻塞導致進程卡死
• Linux 部署需安裝無頭模式依賴（libxrender、fontconfig 等）
• 考慮引入成熟封裝庫（如 wkhtmltopdf-java、pdfcrowd）減少維護成本