如何在 Rust 中将 HTML 转换为 PDF
将HTML文件或原始HTML字符串转换为PDF是发票、报告和收据的常见需求。Rust没有内置的渲染引擎来实现这一点,编写一个也不是一个现实的副项目。HTML解析是简单的部分。CSS解析、布局和分页是工作永无止境的地方,这使得浏览器成为在Rust中生成PDF的自然选择。本教程使用开源的headless_chrome crate在Rust中将HTML转换为PDF,它让Chrome进行渲染,并将完成的PDF返回给您的Rust程序。
Rust的无头Chrome Crate
headless_chrome 是一个MIT许可的Rust crate,通过Chrome DevTools协议控制Chrome或Chromium浏览器。它可以打开页面、点击元素、截取屏幕截图,并调用Chrome内置的打印为PDF功能。由于页面是由真实的浏览器渲染的,CSS布局、网络字体和JavaScript的工作方式与在Chrome中相同。
Chrome还可以通过--print-to-pdf直接从命令行打印页面。这只是一个CLI调用,因此字节落在磁盘上而不是在您的程序中,并且您可以访问的打印设置是有限的。相反,驱动DevTools协议可以将字节保留在您的程序中,并让整个网络平台进行布局。这是任何其他语言中的等效库所基于的相同协议。该crate由Rust社区维护,因此支持来自其GitHub问题跟踪器。
先决条件
要在Rust中创建一个HTML到PDF的转换器,请确保具备以下先决条件:
- Rust 1.85或更高版本。 使用rustup安装Rust工具链。在Windows上,MSVC工具链还需要安装Visual Studio,因为
rustc使用其链接器和库。 - 安装Google Chrome、Chromium或Microsoft Edge。
headless_chrome在PATH上、在CHROME环境变量中以及在Windows上的注册表中查找浏览器,并以Edge作为后备。 - 基本的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
步骤3使用urlencoding crate将HTML字符串作为数据URL传递给Chrome。

检查Cargo.toml
运行cargo add后,两个crate出现在[dependencies]下的Cargo.toml文件中:
[package]
name = "html_to_pdf"
version = "0.1.0"
edition = "2024"
[dependencies]
headless_chrome = "1.0.22"
urlencoding = "2.1.3"

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};
步骤 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()?;
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()?;
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()
};
边距和纸张尺寸以英寸为单位。没有 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))?;
步骤 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(())
}
步骤 7:清理
与 wkhtmltopdf C API 不同,没有需要调用的销毁或去初始化函数。当 browser 在 main 结束时超出范围时,其 Drop 实现关闭 Chrome 进程并删除其创建的临时配置文件夹。如果某个步骤失败并且 ? 提前返回,相同的清理仍会运行。
在长时间运行的服务中,保持一个 Browser 活动,并为每个文档打开一个新标签页,而不是为每个请求启动一个新的 Chrome 进程。
第 8 步:运行代码并生成 PDF 文件
从项目文件夹构建并运行项目:
cargo run
第一次构建编译了 143 个 crates,在这里使用的机器上耗时 45 秒。程序随后打印生成文件的大小:

output.pdf 文件保存在项目文件夹中。CSS 样式,包括标题颜色、表格边框和背景,都被保留:

这是生成的 output.pdf 本身:
在 Rust 中将 URL 或 HTML 文件转换为 PDF
相同的 navigate_to 和 print_to_pdf 调用适用于网页和本地 HTML 文件。对于本地文件,添加 url crate 和 cargo add url,以便您可以在每个操作系统上将文件路径转换为有效的 file:// URL。
下面的示例读取本地模板,因此将其保存到 Cargo.toml 旁边,命名为 invoice.html:
<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>
将下面的程序保存为 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(())
}
一个标签依次处理两个文档。URL 使用 Chrome 的默认设置打印,本地发票以横向打印,并保留其背景颜色:

网页捕获到 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()
};
CSS 路径也有效。Chrome Platform Status 列出了 @page 边距框,针对里程碑 131,因此在此之前编写的指南是历史行为。在 Chrome 153 上,这个页面计数器规则单独为四页文档的每一页编号:
@page { @bottom-center { content: "Page " counter(page); } }
控制分页符位置也是普通的 CSS。一个六卡测试文档展示了差异。没有该属性,第一页在第三张卡片中途结束,其余部分继续在第二页。添加 CSS break-inside 属性将每张卡片完整地移到下一页,每页两张,没有任何卡片被拆分:
.card { break-inside: avoid; }
Chrome 在 PDF 中的内容
有两个选项会改变文件的结构,而不是页面的外观:
let options = PrintToPdfOptions {
generate_document_outline: Some(true),
generate_tagged_pdf: Some(true),
..Default::default()
};
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 服务中使用无头 Chrome
该 crate 是阻塞的,这就是为什么上面的代码没有写成异步函数 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的文档上,Chromium主进程的峰值RAM约为846 MB,而它约为92 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-pass渲染以提高准确性,因此在PDF写入之前解决了诸如 target-counter() 之类的交叉引用。
商业引擎
Prince 支持CSS分页媒体用于复杂的PDF创建,包括 @page 规则、页面边距框和用于运行标题和页脚的预定义页码计数器。Prince是商业软件,你需要购买许可证,而不是通过Cargo添加的crate。
哪一个适合
多年来的经验法则是,Rust原生的HTML到PDF选项在CSS和JavaScript支持方面有限,因此纯Rust引擎仅适用于简单文档。CSS方面的限制已经过时。htmltopdf列出了flexbox、grid、带有行跨度的表格和 @font-face,而Fulgur涵盖了分页媒体的始终。JavaScript仍然是差距所在。
决定选择的是你的文档的渲染方式。如果服务器渲染HTML并且样式是CSS,无浏览器引擎可以将Chrome及其内存从你的部署中移除。如果你的页面在浏览器中绘制图表或依赖于Web应用程序自身的脚本,则需要在流程中保留一个浏览器,这正是本教程所做的。
IronPDF for Rust(即将推出)
IronPDF for Rust 正在开发中。计划中的库将从 HTML 创建 PDF 并操作现有的 PDF,所有这些都可以通过 Rust 代码完成。
加入 IronPDF for Rust 测试计划以获得抢先体验并帮助塑造 API。
HTML 文件到 PDF 文件在 C# 中
IronPDF
IronPDF HTML-to-PDF 转换库 是一个 .NET 和 .NET Core C# 库,用于从 HTML 内容生成 PDF 文档。它自带 Chrome 渲染引擎,因此无需安装、启动或关闭单独的浏览器。
IronPDF 处理的不仅仅是简单的 HTML 文档。它可以渲染带有 CSS 样式和 JavaScript 的复杂网页,并且在创建 PDF 后还可以编辑、合并、签名和保护 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");Imports IronPdf
' Instantiate Renderer
Private renderer = New ChromePdfRenderer()
' Create PDF content from an HTML string using C#
Private pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>")
' Export to a file or Stream
pdf.SaveAs("output.pdf")Imports IronPdf
' Instantiate Renderer
Private renderer = New ChromePdfRenderer()
' Create PDF content from an HTML string using C#
Private pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>")
' Export to a file or Stream
pdf.SaveAs("output.pdf")PDF 输出:

此 Rust 教程中的步骤对应于单个 IronPDF 设置。页面设置在自定义边距和自定义纸张大小中介绍,JavaScript 等待问题由WaitFor 渲染延迟处理。将 URL 转换为 PDF 或将 HTML 文件转换为 PDF 每个只需一个方法调用,带页码的页眉和页脚不需要 HTML 模板。有关完整的演练,请参阅 HTML 到 PDF 教程,或阅读相同任务在 HTML 到 PDF 在 C++ 中的工作原理。
您可以通过 IronPDF 的完整功能免费试用来尝试所有这些。它运行 30 天,无需信用卡,并且在您评估时可以在实时服务器上运行而不会有水印。许可 之后是永久性的,没有经常性费用,按开发人员、项目和位置定价,并提供 30 天退款保证。要开始,请下载 IronPDF。
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。