.NET幫助

如何在 Rust 中將 HTML 轉換為 PDF

Curtis Chau
Curtis Chau
已更新: 2026年10月18日

將 HTML 文件或原始 HTML 字串轉換為 PDF 是發票、報告和收據的常見需求。Rust 沒有內建的渲染引擎來實現這一點,編寫一個也不是一個現實的副專案。HTML 解析是簡單的部分。CSS 解析、佈局和分頁是工作永無止境的地方,這使得瀏覽器成為在 Rust 中生成 PDF 的自然選擇。本教程使用開源的 headless_chrome crate 在 Rust 中將 HTML 轉換為 PDF,該 crate 讓 Chrome 進行渲染,並將完成的 PDF 返回給您的 Rust 程式。

Rust 的 Headless Chrome Crate

headless_chrome 是一個 MIT 許可的 Rust crate,通過 Chrome DevTools Protocol 控制 Chrome 或 Chromium 瀏覽器。它可以打開頁面、點擊元素、截圖,並調用 Chrome 的內建列印為 PDF 功能。由於頁面是由真正的瀏覽器渲染的,CSS 佈局、網頁字體和 JavaScript 的工作方式與在 Chrome 中相同。

Chrome 也可以直接從命令行使用 --print-to-pdf 列印頁面。這只是一個 CLI 調用,因此位元組落在磁碟上而不是在您的程式中,您可以訪問的列印設置有限。驅動 DevTools Protocol 則將位元組保留在您的程式中,並讓整個網頁平台進行佈局。這是任何其他語言中的等效庫所基於的相同協議。該 crate 由 Rust 社群維護,因此支援來自其 GitHub 問題追蹤器。

先決條件

要在 Rust 中創建 HTML 到 PDF 的轉換器,請確保具備以下先決條件:

  1. Rust 1.85 或更高版本。 使用 rustup 安裝 Rust 工具鏈。在 Windows 上,MSVC 工具鏈還需要安裝 Visual Studio,因為 rustc 使用其鏈接器和庫。
  2. 已安裝 Google Chrome、Chromium 或 Microsoft Edge。 headless_chrome 在 PATH 上、CHROME 環境變數中以及在 Windows 上的註冊表中查找瀏覽器,Edge 作為後備。
  3. 基本的 Rust 和 Cargo 知識。

本教程在 Windows 11 上使用 Rust 1.98.1、headless_chrome 1.0.22 和 Chrome 153 測試。相同的代碼可以在 Linux 和 macOS 上運行。

使用 Cargo 創建 Rust HTML 到 PDF 專案

從終端創建二進制專案並添加兩個依賴項:

cargo new html_to_pdf
cd html_to_pdf
cargo add headless_chrome urlencoding
SHELL

步驟 3 使用 urlencoding crate 將 HTML 字串作為數據 URL 傳遞給 Chrome。

如何在 Rust 中將 HTML 轉換為 PDF:圖 1 - 創建專案並添加依賴項

檢查 Cargo.toml

運行 cargo add 後,兩個 crates 出現在 [dependencies] 下的 Cargo.toml 文件中:

[package]
name = "html_to_pdf"
version = "0.1.0"
edition = "2024"

[dependencies]
headless_chrome = "1.0.22"
urlencoding = "2.1.3"
Text

如何在 Rust 中將 HTML 轉換為 PDF:圖 2 - Cargo.toml 依賴項

crate 的默認 offline 功能使用已安裝的瀏覽器。如果目標機器沒有 Chrome,則啟用 fetch 功能 (cargo add headless_chrome --features fetch),crate 可以為您下載 Chromium 構建。

在 Rust 中將 HTML 轉換為 PDF 的步驟

步驟 1:導入 Crates

打開 src/main.rs 並用程式所需的導入替換其內容。Browser 和 LaunchOptions 啟動 Chrome,PrintToPdfOptions 控制 PDF 輸出:

use std::fs;

use headless_chrome::types::PrintToPdfOptions;
use headless_chrome::{Browser, LaunchOptions};
Rust

步驟 2:啟動無頭 Chrome

接下來,啟動一個無頭瀏覽器並打開一個標籤頁。main 返回一個 Result,因此每次調用都可以使用 ? 運算符而不是 unwrap:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Launch a headless Chrome instance
    let browser = Browser::new(LaunchOptions {
        headless: true,
        ..Default::default()
    })?;

    // Open a new tab to load the HTML into
    let tab = browser.new_tab()?;
Rust

Browser::default() 用更少的代碼給出相同的結果。這裡顯示 LaunchOptions,因為這是您需要設置窗口大小、Chrome 路徑或沙盒標誌的地方。

步驟 3:設置 HTML 內容

現在提供應轉換為 PDF 的 HTML。Rust 原始字符串語法 r#"..."# 保持 HTML 中的引號可讀:

    let html = r#"
        <html>
        <head>
            <style>
                body { font-family: Arial, sans-serif; margin: 40px; }
                h1 { color: #2a5db0; }
                table { border-collapse: collapse; width: 100%; }
                th, td { border: 1px solid #ccc; padding: 8px; text-align: left; }
                th { background-color: #f0f4fa; }
            </style>
        </head>
        <body>
            <h1>Hello, World!</h1>
            <p>This PDF was generated from an HTML string in Rust.</p>
            <table>
                <tr><th>Item</th><th>Quantity</th><th>Price</th></tr>
                <tr><td>Widget</td><td>2</td><td>$10.00</td></tr>
                <tr><td>Gadget</td><td>1</td><td>$25.00</td></tr>
            </table>
        </body>
        </html>
    "#;

    // Load the HTML string as a data URL and wait for the page to finish loading
    let data_url = format!("data:text/html;charset=utf-8,{}", urlencoding::encode(html));
    tab.navigate_to(&data_url)?.wait_until_navigated()?;
Rust

print_to_pdf 沒有 HTML 選項。它打印標籤頁顯示的內容,並且該 crate 沒有直接設置頁面內容的方法,因此 HTML 字符串被百分比編碼為 data: URL,然後標籤頁導航到該 URL。

wait_until_navigated 然後阻塞直到頁面準備就緒,它不會在加載事件時停止。該 crate 開啟了 Chrome 的生命週期事件,並在 networkAlmostIdle 清除其導航標誌,這是頁面獲取的請求(網絡空閒)減少後到達的瀏覽器生命週期里程碑。當標籤頁報告導航完成時,通常晚期的網頁字體和圖像已經就位。

步驟 4:將 HTML 轉換為 PDF

頁面加載完成後,調用 print_to_pdf。PrintToPdfOptions 映射到 Chrome 的打印設置,每個字段都是可選的:

    // Print the page to PDF with background colors and 0.4 inch margins
    let options = PrintToPdfOptions {
        print_background: Some(true),
        margin_top: Some(0.4),
        margin_bottom: Some(0.4),
        margin_left: Some(0.4),
        margin_right: Some(0.4),
        ..Default::default()
    };
Rust

邊距和紙張尺寸以英寸為單位。沒有 paper_width 和 paper_height,Chrome 使用美國信紙(8.5 x 11 英寸)。除非您要求,否則 Chrome 不會打印背景顏色或圖像。print_background 默認為關閉,沒有它,表格標題的陰影將從 PDF 中刪除。

頁面設置字段(landscape、scale、page_ranges 和頁眉和頁腳模板)在本教程的後面部分將獲得自己的部分。

步驟 5:將輸出作為字節向量獲取

print_to_pdf 返回完成的文檔作為存儲在內存中的 Vec<u8>。尚未寫入磁盤,因此字節可以發送到文件、HTTP 響應正文或雲存儲:

    let pdf_data: Vec<u8> = tab.print_to_pdf(Some(options))?;
Rust

步驟 6:保存 PDF 文件

要保存 PDF,使用 std::fs::write 將字節向量寫入文件,該操作會創建文件、寫入所有字節並在一次調用中關閉它:

    // Write the PDF bytes to disk
    fs::write("output.pdf", &pdf_data)?;
    println!("PDF saved successfully ({} bytes).", pdf_data.len());

    Ok(())
}
Rust

步驟 7:清理

與 wkhtmltopdf C API 不同,沒有需要調用的銷毀或去初始化函數。當 browser 在 main 結束時超出範圍時,其 Drop 實現會關閉 Chrome 進程並刪除其創建的臨時配置文件夾。如果某個步驟失敗並且 ? 提前返回,則仍會運行相同的清理。

在長期運行的服務中,保持一個 Browser 存活,並為每個文檔打開一個新標籤頁,而不是為每個請求啟動一個新的 Chrome 進程。

步驟 8:運行程式碼並生成 PDF 文件

從專案資料夾構建並運行專案:

cargo run
SHELL

第一次構建編譯了 143 個 crates,在這裡使用的機器上花費了 45 秒。然後程式會列印生成文件的大小:

如何在 Rust 中將 HTML 轉換為 PDF:圖 3 - cargo run 輸出

output.pdf 文件保存在專案資料夾中。CSS 樣式,包括標題顏色和表格邊框及背景,都被保留:

如何在 Rust 中將 HTML 轉換為 PDF:圖 4 - PDF 輸出

這是生成的 output.pdf 本身:

在 Rust 中將 URL 或 HTML 文件轉換為 PDF

相同的 navigate_to 和 print_to_pdf 調用適用於網頁和本地 HTML 文件。對於本地文件,使用 cargo add url 添加 url crate,以便您可以在每個操作系統上將文件路徑轉換為有效的 file:// URL。

下面的範例讀取本地模板,因此將其保存為 invoice.html,與 Cargo.toml 放在一起:

<html>
<head>
    <style>
        body { font-family: Arial, sans-serif; margin: 30px; }
        .box { background: #2a5db0; color: #fff; padding: 16px; }
    </style>
</head>
<body>
    <div class="box"><h2>Invoice #1024</h2></div>
    <p>Loaded from a local HTML file.</p>
</body>
</html>
HTML

將下面的程式保存為 examples/url_and_file.rs,並使用 cargo run --example url_and_file 運行它:

use std::fs;

use headless_chrome::types::PrintToPdfOptions;
use headless_chrome::Browser;
use url::Url;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let browser = Browser::default()?;
    let tab = browser.new_tab()?;

    // Convert a live web page to PDF
    tab.navigate_to("https://doc.rust-lang.org/book/")?
        .wait_until_navigated()?;
    let url_pdf = tab.print_to_pdf(None)?;
    fs::write("url.pdf", url_pdf)?;

    // Convert a local HTML file to PDF
    let path = fs::canonicalize("invoice.html")?;
    let file_url = Url::from_file_path(&path).map_err(|_| "invalid file path")?;
    tab.navigate_to(file_url.as_str())?.wait_until_navigated()?;

    let options = PrintToPdfOptions {
        landscape: Some(true),
        print_background: Some(true),
        ..Default::default()
    };
    fs::write("invoice.pdf", tab.print_to_pdf(Some(options))?)?;

    println!("Saved url.pdf and invoice.pdf");
    Ok(())
}
Rust

一個標籤依次處理兩個文件。URL 使用 Chrome 的預設值列印,本地發票以橫向列印,並保留其背景顏色:

如何在 Rust 中將 HTML 轉換為 PDF:圖 5 - URL 和 HTML 文件轉換為 PDF

網頁捕獲到 url.pdf:

本地 HTML 文件以橫向列印到 invoice.pdf:

使用 .html 名稱保存模板,因為 Chrome 決定如何從輸入擴展名處理本地文件。相同的標記保存為 .txt 時,會以可見標籤而不是渲染頁面列印。

頁面大小、頁碼和分頁符

PrintToPdfOptions 反映了 Chrome 的列印對話框,其支援的值是對話框本身提供的值。landscape: Some(true) 切換到橫向模式,scale 接受一個縮放因子,其中 1.0 為全尺寸,page_ranges 接受一個基於 1 的字串,例如 "1-5, 8, 11-13"。

頁碼可以來自任一側。給 Chrome 一個頁腳模板,它會在每頁替換 pageNumber 和 totalPages:

let options = PrintToPdfOptions {
    display_header_footer: Some(true),
    header_template: Some("<span></span>".into()),
    footer_template: Some(
        "<div style='font-size:10px;width:100%;text-align:center'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>".into()),
    margin_bottom: Some(0.6),
    ..Default::default()
};
Rust

CSS 路徑也有效。Chrome 平台狀態將 @page 邊距框列為里程碑 131,因此在此之前編寫的指南是歷史行為。在 Chrome 153 上,僅此頁面計數器規則就為四頁文件的每一頁編號:

@page { @bottom-center { content: "Page " counter(page); } }
CSS

控制分頁符位置也是普通的 CSS。一個六張卡片的測試文件顯示了差異。沒有該屬性,第一頁在第三張卡片的一半結束,其餘部分繼續在第二頁。添加 CSS break-inside 屬性將每張卡片整體移到下一頁,每頁兩張,沒有分開:

.card { break-inside: avoid; }
CSS

Chrome 在 PDF 中的內容

有兩個選項會改變文件的結構,而不是頁面的外觀:

let options = PrintToPdfOptions {
    generate_document_outline: Some(true),
    generate_tagged_pdf: Some(true),
    ..Default::default()
};
Rust

generate_document_outline 將您的標題轉換為 PDF 書籤。一份包含一個 h1 和兩個 h2 標題的報告在選項開啟時會產生一個三條目的文件大綱,而在關閉時則完全沒有大綱。

generate_tagged_pdf 要求生成標記的 PDF,這是螢幕閱讀器和 PDF/UA 檢查器所讀取的結構。DevTools Protocol 將其默認記錄為“embedder choice”而不是關閉,這裡的測試也符合這一點。在兩個選項都關閉的情況下,輸出仍然包含結構樹,並從 <html lang="en"> 中攜帶文件語言。無論如何,請在您的模板上設置該屬性,並在依賴該標誌之前檢查您自己的輸出。

字體是通過字體子集嵌入的,因此使用 Georgia 設置的頁面產生了 AAAAAA+Georgia-Bold 和 BAAAAA+Georgia,而不是整個字體系列。一張 JPEG 照片被存儲為 JPEG,而不是重新編碼。

在 Rust 服務中使用 Headless Chrome

該 crate 是阻塞的,這就是為什麼上面的代碼沒有寫成 async fn main。如果您的服務已經有一個異步運行時,例如 Tokio,請在 tokio::task::spawn_blocking 中調用它以保持瀏覽器不在反應器上,這樣一個緩慢的渲染就不會阻塞執行器。

沒有任何操作會永遠輪詢。每個標籤操作都會在超時後運行並返回錯誤,而不是掛起,因此一個永遠不穩定的頁面無法佔用工作者。

Chrome 啟動和關閉行會出現在任何安裝了記錄器的服務中,因為該 crate 通過 log crate 報告。要從瀏覽器層移除日誌而不靜音您自己的日誌,請按目標過濾,例如 RUST_LOG=info,headless_chrome=warn。

在 Rust 中將 HTML 轉換為 PDF 的常見問題

這些是在生產中出現的故障模式:

  • JavaScript 渲染的內容: wait_until_navigated 在網絡安靜下來後返回,這與圖表完成繪製不同。當頁面完成時,對頁面添加的元素調用 tab.wait_for_element("#report-ready"),然後打印。
  • 超時: 標籤操作默認在 20 秒後超時。對於緩慢的頁面,使用 tab.set_default_timeout(std::time::Duration::from_secs(60)) 提高限制。
  • 大型 HTML 字串: Chrome 將 URL 限制為 2 MB,這包括 data: URL。對於更大的文檔,將 HTML 寫入臨時文件並使用 file:// URL 加載,如上所示。
  • Docker 和 Linux 容器: 當進程以 root 身份運行時,Chrome 的沙箱無法啟動,而 Puppeteer 的故障排除指南強烈不建議在沒有沙箱的情況下運行。將一個非特權用戶添加到映像中並保持沙箱開啟,只有在沒有其他選擇時才在 LaunchOptions 中設置 sandbox: false。無論哪種方式,映像都需要 Chrome 的系統庫。
  • 部署: 每個運行該程序的服務器都需要一個兼容的瀏覽器,因此即使 Rust 代碼編譯為單個二進制文件,Chrome 也成為您部署的一部分。

在 Rust 中將 HTML 轉換為 PDF 的其他方法

headless_chrome 不是唯一的路徑。哪一個適合取決於您的文檔是否需要 JavaScript 以及您一次渲染多少個。

基於Chromium,如本教程

html2pdf 自稱只是 headless_chrome crate 的一個CLI,並且它也作為一個庫提供,其API是異步的並在tokio上運行,這樣就省去了自己編寫 spawn_blocking 包裝器的麻煩。

Gotenberg 完全將瀏覽器移出了你的進程。它是一個基於Docker的API,用於將文檔轉換為PDF:Chromium處理URL、HTML和Markdown,LibreOffice處理辦公格式,而你的Rust服務通過HTTP發送文件並獲得PDF返回。這樣可以將Chrome排除在你的二進制部署之外,但需要在旁邊運行一個服務。

無瀏覽器的Rust引擎

無頭Chrome對於並發PDF生成來說可能資源密集,因為每次轉換都需要一個瀏覽器進程及其附帶的內存。兩個Rust項目直接針對這一點。

htmltopdf 是一個MIT許可的引擎,它在一個線程中渲染,沒有子進程,其README描述它是為高並發和低RAM使用而構建的。README報告在一個1.8 MB的文檔上,約92 MB的峰值RAM對比Chromium主進程的約846 MB。對於20個並發轉換,它報告在Apple Silicon上使用 /usr/bin/time -l 測量的情況下,1.25 GiB下12.75 PDF/s對比Chromium的9.35 GiB下1.18 PDF/s。這些是項目在其自身夾具上的基準,並未為本文重現。該crate不在crates.io上,因此你需要從存儲庫安裝它,其JavaScript處理是一個選擇性、有限的預佈局階段,而不是一個完整的引擎。

Fulgur 是另一個在Rust中跳過瀏覽器的HTML到PDF引擎。它是Apache-2.0許可的,並集成了Blitz進行HTML解析、樣式解析和佈局,與Krilla進行PDF生成。Fulgur支持一個精選的HTML和CSS子集,在其CSS支持文檔中逐個屬性跟蹤,其功能列表中不包含JavaScript引擎。它涵蓋的是分頁方面,包括頁面計數器、運行標題、邊距框、break-inside、標記PDF和字體子集化。Fulgur的渲染管道包括一個2次渲染以提高準確性,因此在PDF寫入之前解決了交叉引用如 target-counter()。

商業引擎

Prince 支持CSS Paged Media進行複雜的PDF創建,包括 @page 規則、頁面邊距框和運行標題和頁腳的預定義頁面計數器。Prince是你需要許可的商業軟件,而不是你用Cargo添加的crate。

哪一個適合

多年來的經驗法則是,Rust原生的HTML到PDF選項在CSS和JavaScript支持上有限,因此純Rust引擎僅適合簡單文檔。CSS這一半已經過時。htmltopdf列出了flexbox、grid、帶有rowspans的表格和 @font-face,而Fulgur涵蓋了從頭到尾的分頁媒體。JavaScript仍然是差距所在。

決定選擇的是你的文檔的繪製方式。如果服務器渲染HTML且樣式是CSS,無瀏覽器引擎可以將Chrome及其內存從你的部署中移除。如果你的頁面在瀏覽器中繪製圖表或依賴於Web應用程序自己的腳本,則在管道中保留一個瀏覽器,這正是本教程所做的。

IronPDF for Rust(即將推出)

IronPDF for Rust 正在開發中。計劃中的庫將從 Rust 代碼中創建 PDF 並操作現有的 PDF。

加入 IronPDF for Rust 測試計劃以獲得早期訪問權限並幫助塑造 API。

將 HTML 文件轉換為 PDF 文件(C#)

IronPDF

IronPDF HTML-to-PDF 轉換庫 是一個 .NET 和 .NET Core C# 庫,用於從 HTML 內容生成 PDF 文檔。它自帶 Chrome 渲染引擎,因此無需安裝、啟動或關閉單獨的瀏覽器。

IronPDF 處理的不僅僅是簡單的 HTML 文檔。它可以渲染帶有 CSS 樣式和 JavaScript 的複雜網頁,並且在創建後還可以編輯、合併、簽署和保護 PDF。

使用 IronPDF 完成相同的工作,將 HTML 字符串轉換為 PDF(C#):

using IronPdf;

// Instantiate Renderer
var renderer = new ChromePdfRenderer();

// Create PDF content from an HTML string using C#
var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export to a file or Stream
pdf.SaveAs("output.pdf");

PDF 輸出:

如何在 Rust 中將 HTML 轉換為 PDF:圖 6 - IronPDF 輸出

此 Rust 教程中的步驟對應於單個 IronPDF 設置。頁面設置涵蓋在自定義邊距和自定義紙張大小中,JavaScript 等待問題由 WaitFor 渲染延遲處理。將 URL 轉換為 PDF 或將 HTML 文件轉換為 PDF 每次只需一個方法調用,帶有頁碼的頁眉和頁腳不需要 HTML 模板。欲了解完整的操作過程,請參閱 HTML to PDF 教程,或閱讀相同任務在 HTML to PDF in C++ 中的工作方式。

您可以通過 IronPDF 的完整功能免費試用來嘗試所有這些功能。它運行 30 天,不需要信用卡,並且在您評估時可以在實時服務器上運行而不帶水印。之後的許可是永久性的,沒有經常性費用,按開發人員、項目和位置計算,並提供 30 天退款保證。要開始使用,請下載 IronPDF。

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

閱讀更多

相關文章