该页面可以包含自动翻译的文本。

.NET 的 HTML 转 PDF

由 Bit Miracle 翻译。原文作者：Sergey Bobrovsky

更新于 2026年1月27日

您可以使用 Docotic.Pdf 库将 HTML 转换为 PDF。该库的免费插件 HtmlToPdf 可以将 HTML、SVG、WEBP 和其他网页格式转换为 PDF。

本指南概述了该插件提供的 HTML 转 PDF 功能，并包含指向相关页面的链接，以便您更详细地了解所讨论的主题。

图示 HTML 转 PDF 库内部的处理流程。HTML 文档进入库中，然后库生成 PDF 输出。

C# 中 HTML 转 PDF 的基础知识

您需要 HtmlToPdf 插件、转换代码片段和许可证密钥。您可以先使用免费试用密钥。

从 NuGet 安装该插件

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

这是推荐的方法，因为它能自动处理依赖项和更新。您也可以从包含 Docotic.Pdf 二进制文件的压缩包中手动安装插件，尽管这种方法更复杂且更容易出错。

获取许可证密钥

要试用该库，请从 Docotic.Pdf 的下载页面获取免费的限时许可密钥。如果您已购买许可，请使用购买后收到的代码。

所有 Docotic.Pdf 许可均包含 HTML 转 PDF 功能。使用此附加功能无需购买额外许可。

添加转换代码

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

using var converter = await HtmlConverter.CreateAsync();
var html = "<h1>Hello, World<h1>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

在代码中，将 AddLicenseData 方法调用中的占位符值替换为有效的许可证密钥。

运行代码

转换代码会根据字符串中的 HTML 代码生成 PDF 文件。使用默认转换选项，输出结果为一张 A4 纸大小的文档。

该库提供了丰富的转换自定义选项。您可以更改输出尺寸，或为生成的页面添加页眉和页脚。此外，它还可以转换需要身份验证的资源。

请阅读专门的文章，了解将 HTML 转换为 PDF 的各种方法，文章中详细解释了每种方法。

为什么 Docotic.Pdf 是合适的 HTML 转 PDF 转换器？

Docotic.Pdf 能够在转换过程中保留样式和布局，因此是生成 HTML 报告、发票和其他文档 PDF 文件的理想选择。该库可以从 HTML 和其他 Web 格式（例如 SVG）生成像素级精确的 PDF 文档。使用该库可以轻松重用现有的 HTML 内容。

转换器使用 Google Chrome 渲染引擎。这意味着它与顶级 Web 浏览器之一具有相同的 Web 标准兼容性。

您可以使用 Docotic.Pdf 从包含现代 CSS、JavaScript 和图像的复杂布局生成 PDF 文件。它也对响应式 Web 设计提供了良好的支持。

API架构概述

HTML 转 PDF API 仅在将 Docotic.Pdf 与免费的 HtmlToPdf 插件配合使用时可用。

该插件提供了一个仅支持异步操作的 API。我们将其设计为与异步事件处理程序和异步方法协同工作。这种设计能够优雅地处理耗时较长的任务，而媒体转换正是此类任务的理想示例。

.NET 版本和平台支持

该库和插件面向 .NET Standard 2.0。这意味着它们都兼容 .NET 5 到 .NET 10。此外，它们还支持 .NET Core 2.0+ 和 .NET Framework 4.6.1+。

您可以在 Windows Forms、WPF、ASP.NET 和控制台应用程序中使用 HTML 转 PDF 功能。该插件可以在云环境和 Docker 容器中运行。

借助该插件，您可以在 Windows、macOS 和 Linux 环境中从 HTML 生成 PDF。

转换过程中会发生什么？

默认情况下，转换过程包含以下几个阶段：

您的代码调用 HtmlConverter 类的 CreateAsync 方法。
该插件检查当前工作目录下的 .local-chromium 文件夹中是否存在兼容的 Google Chrome 版本。
如果没有兼容的版本，该插件会下载一个并将其解压到 .local-chromium 文件夹中。
当您的代码调用 CreatePdfAsync 或 CreatePdfFromStringAsync 方法时，该插件会使用 Google Chrome 加载提供的 HTML。
内容准备好转换后，该插件会指示浏览器生成 PDF。
Google Chrome 使用 Chromium 的渲染功能生成 PDF。
该插件会将生成的 PDF 文件返回给你的代码 PdfDocument。

云平台和 Docker 镜像

HtmlToPdf 插件支持 Azure 和 AWS 云平台，包括无服务器环境。您还可以在 Docker 容器中使用 HTML 转 PDF API。以下是支持的环境列表：

Azure： Azure Functions、Azure 应用服务、Azure VPS
Amazon Web Services： AWS ECS、Amazon EC2
Docker： Windows 和 Linux 容器。

该库和插件完全支持动态硬件变更、自动扩缩容和其他云原生运行时特性。

有关更多信息，请参阅关于在云端和 Docker 镜像中运行该插件的文章。

云应用支持哪些许可证类型？

大多数情况下，您需要一个非绑定许可证（Ultimate 或 Ultimate+）。如果硬件 ID 不变，服务器许可证也可能适用。

服务器许可证与服务器的硬件 ID 绑定。如果在运行或重启之间硬件发生变化，服务器许可证将失效。此外，在服务器数量可能动态变化的环境中，服务器许可证也无法使用，因为每个生产服务器都需要一个唯一的许可证。

为确保服务器的硬件 ID 保持一致，您可以检查 LicenseManager.Uid 属性的值。或者，您可以使用我们的 UID 生成器应用程序获取相同的 ID。

如何从 HTML 模板生成 PDF

请按照以下简单步骤操作：

获取模板数据。
将数据填充到模板中，生成完整的 HTML 代码。
使用 Docotic.Pdf 将完整的 HTML 代码转换为 PDF 文件。

图示说明如何从 HTML 模板生成 PDF。占位符数据用于在将模板转换为 PDF 之前填充模板内容。

模板数据通常来自数据库或 API 响应。对于数据库，它可以是一条记录或一组记录。对于 API，它通常是一个描述一个或多个实体的 JSON 对象。

以下示例将使用这位虚构人物：

var person = new
{
    Name = "Alice Johnson",
    Age = 27,
    Email = "alicej@example.com",
    Occupation = "Truck driver"
};

现在我已经有了数据，接下来我将介绍三种准备和填充 HTML 模板的方法。这三种方法生成的最终 HTML 代码完全相同，即使对应的模板不同。

要转换完整的 HTML 代码，请使用我已提供的代码。

命名占位符

命名占位符是指用双分隔符括起来的标记，分隔符使用非字母数字符号。%% 是最不容易发生冲突的分隔符之一。

以下是一个包含命名占位符的模板，以及从中生成完整 HTML 的代码：

var template = @"<head><title>%%NAME%%'s Profile</title></head>
<body>
    <h1>%%NAME%%</h1>
    <p><strong>Age:</strong> %%AGE%%</p>
    <p><strong>Email:</strong> %%EMAIL%%</p>
    <p><strong>Occupation:</strong> %%OCCUPATION%%</p>
</body></html>";

var completeHtml = template
    .Replace("%%NAME%%", person.Name)
    .Replace("%%AGE%%", person.Age.ToString())
    .Replace("%%EMAIL%%", person.Email)
    .Replace("%%OCCUPATION%%", person.Occupation);

大多数情况下，建议使用命名占位符。但是，请记住，如果您插入的值替换了占位符，则需要对其进行转义。

模板引擎

当您的模板非常复杂和/或需要可重用部分时，命名占位符可能不太方便。不妨尝试使用 Handlebars.Net 等模板引擎。

以下示例使用了不同的模板和代码，但生成了相同的 HTML：

var template = @"<head><title>{{name}}'s Profile</title></head>
<body>
    <h1>{{name}}</h1>
    <p><strong>Age:</strong> {{age}}</p>
    <p><strong>Email:</strong> {{email}}</p>
    <p><strong>Occupation:</strong> {{occupation}}</p>
</body></html>";

var compiledTemplate = Handlebars.Compile(template);
var completeHtml = compiledTemplate(person);

Handlebars.Net 模板不包含逻辑。如果您觉得这过于局限，可以试试 Scriban。它提供了条件语句、循环语句、表达式、函数调用等更多功能。

位置占位符

这些与命名占位符非常相似，但它们使用位置编号而不是名称。您可能在 string.Format 方法调用中见过它们。

var template = @"<head><title>{0}'s Profile</title></head>
<body>
    <h1>{1}</h1>
    <p><strong>Age:</strong> {2}</p>
    <p><strong>Email:</strong> {3}</p>
    <p><strong>Occupation:</strong> {4}</p>
</body></html>";

var completeHtml = string.Format(
    template, person.Name, person.Name,
    person.Age, person.Email, person.Occupation);

我建议您除了最简单的情况外，不要使用位置占位符。原因如下：

当模板多次使用某个值时，您必须在调用中多次提供该值。
很容易在模板中更改顺序，但忘记更新代码。

将 ASPX 转换为 PDF

使用 Docotic.Pdf 和免费的 HtmlToPdf 插件，即可将 ASPX 转换为 PDF。流程非常简单：

提供一个 Render 方法的实现，用于收集生成的 HTML。
让 ASP.NET 引擎通过执行服务器端代码和控件来生成 ASPX 页面的 HTML。
将收集到的 HTML 转换为 PDF，并在更新后的响应中返回该 PDF。

请查看示例代码，了解如何在 ASP.NET Web Forms 应用程序中从 ASPX 页面生成 PDF。该示例应用程序演示了上述过程，并生成了 HTML 或 PDF 格式的发票。您可以使用相同的方法生成报告、报表和其他文档的高保真 PDF 版本。

将 SVG 转换为 PDF

使用 Docotic.Pdf 库的 HtmlToPdf 插件，可以将 SVG 转换为矢量 PDF。您可以使用 HtmlConverter 类作为 SVG 到 PDF 的转换器。以下 C# 代码展示了一种转换方法：

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/team.svg");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("output.pdf");

上述代码的运行结果是一个高质量的矢量 PDF 文件。HtmlToPdf 插件提供的转换器会根据 SVG 文件中指定的宽度和高度来确定宽高比。根据 SVG 文件的大小，转换器可能会按比例缩放 SVG 文件以适应 PDF 页面。

影响输出大小的选项

要生成不同尺寸的 PDF，请设置页面大小和/或边距。转换后的 SVG 仍可能按比例缩放。

另一种方法是在 HTML 代码中指定 SVG 的宽度和/或高度，然后转换该 HTML 代码。输出结果中，图像将具有指定的大小。如果尺寸大于 PDF 页面，则图像的某些部分将不可见。

using var converter = await HtmlConverter.CreateAsync();
var html = $"<img src='https://bitmiracle.com/images/team.svg' width='200' />";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

SVG 文件转 PDF

要将 SVG 文件转换为 PDF，请创建一个名为 Uri 的文件，并将其传递给 CreatePdfAsync 方法。另一种方法是创建一个包含 img 标签的 HTML 代码片段，并将其与 CreatePdfFromStringAsync 方法一起使用。如果在 HTML 代码中使用相对路径，请通过转换选项提供基本 URL。

要将多个 SVG 文件转换为 PDF，请创建一个包含多个 img 标签的 HTML 代码片段，并将其与 CreatePdfFromStringAsync 方法一起使用。如果所有文件都位于同一文件夹中，建议在 HTML 代码中使用相对路径并提供基本 URL。

在 PDF 中添加 SVG

首先使用 HtmlConverter 方法之一将 SVG 转换为 PDF。

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/quote.svg");
using var svgPdf = await converter.CreatePdfAsync(uri);

然后，您可以将生成的 PDF 内容叠加到另一个文档之上，或者将该文档与另一个 PDF 合并。

要将 SVG 叠加到 PDF 上，请从转换后的文档的第一页创建一个 XObject，并将该 XObject 绘制到另一个文档的 PDF 页面上。如下所示：

using var pdf = new PdfDocument("some-other.pdf");
var xObj = pdf.CreateXObject(svgPdf.Pages[0]);

pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("output.pdf");

要将 SVG 合并到 PDF 中，请使用可用的合并方法之一将转换后的 PDF 文档与另一个 PDF 合并。

将 WEBP 转换为 PDF

WebP 是一种网页格式，因此您可以使用 Docotic.Pdf 及其 HtmlToPdf 插件将其转换为 PDF。以下 C# 代码演示了如何高质量地将 WebP 转换为 PDF：

using var converter = await HtmlConverter.CreateAsync();
var html = $"<img src='https://bitmiracle.com/pdf-library/images/edit/reorder-pages.webp'/>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

上面的代码没有为 img 标签指定 width 或 height 属性，但最好还是加上。请注意，如果您指定的图像尺寸大于 PDF 页面，则图像的某些部分将无法显示。

由于 WebP 是光栅格式，因此无法很好地缩放。我建议您使用预期所需的最大尺寸和分辨率的图像。

要将 WebP 文件转换为 PDF，请使用相同的代码。如果您的 HTML 使用相对路径，请通过加载选项提供基本 URL。转换本地图像时，请使用文件 Uri 作为基本 URL。

使用 XSLT 将 XML 转换为 PDF

要将 XML 转换为 PDF，首先使用 XSLT 转换将 XML 转换为 HTML。然后使用 Docotic.Pdf 及其 HtmlToPdf 插件将生成的 HTML 转换为 PDF。

以下是 C# XML 转 PDF 转换代码：

var transform = CreateTransform("invoice.xsl");
var html = TransformToHtml("invoice.xml", transform);

using var converter = await HtmlConverter.CreateAsync();
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("invoice.pdf");

代码如下：

第一行创建一个 XSLT 转换对象。
第二行将 XML 文件转换为 HTML 文档。
其余各行将转换结果（HTML 字符串）转换为 PDF。

让我们仔细看看前两点。第三点在本节中有详细介绍。

创建 XSLT 转换

转换过程的第一步是创建 XSLT 转换对象。以下代码演示了如何创建这样的对象：

public static XslCompiledTransform CreateTransform(string xsltFileName)
{
    var transform = new XslCompiledTransform();
    transform.Load(xsltFileName);
    return transform;
}

顾名思义，XslCompiledTransform 会编译提供的样式表并从中生成 IL 代码。如果您的代码需要批量将 XML 转换为 PDF，请重用同一个转换对象以提高性能。

将 XML 转换为 HTML

第二步是使用上一步创建的 XSLT 转换对象从 XML 生成 HTML。

public static string TransformToHtml(string xmlFileName, XslCompiledTransform transform)
{
    using var xmlReader = XmlReader.Create(xmlFileName);
    using var sw = new StringWriter();
    using var writer = XmlWriter.Create(sw, transform.OutputSettings);
    transform.Transform(xmlReader, null, writer);
    return sw.ToString();
}

该代码使用 XmlReader 和 XmlWriter，因为它们非常适合处理大型 XML 文件，并且有助于保持较低的内存使用量。

XML 转 PDF 的示例代码

我们的示例库包含一个示例应用程序的 C# 和 VB.NET 版本，该应用程序可以将 XML 发票转换为 PDF。示例应用程序包含一个 XML 发票示例和相应的 XSLT 样式表。

当您在现代浏览器中访问返回 XML 的 URL 时，浏览器可以自动应用关联的 XSLT（如果存在）来生成并显示可读的 HTML。这仅在 XML 文件和 XSLT 文件托管在同一服务器上时才有效。为了防止跨域请求，当您直接从本地文件系统打开 XML 文件时，浏览器将不会加载或应用样式表。

创建 PDF 的权衡取舍和替代方法

HTML 转 PDF API 并非使用 Docotic.Pdf 生成 PDF 的唯一方法，而且也并非总是最有效的。本节概述了其他方法，以帮助您根据具体情况选择合适的方案。

创建 PDF 的方法示例：使用 HTML 转 PDF、Canvas API、基于模板的生成、Layout API 和组合。

何时选择 HTML 转 PDF

如果您的团队已经使用 HTML/CSS 创建文档，请选择 HTML 转 PDF 的方法。尤其当您的文档类似于网页时，例如发票、采购订单、证书、收据等。

HtmlToPdf 插件允许团队重用现有的 HTML/CSS 模板，并受益于高保真布局和渲染功能。使用此插件，您可以以最快的速度获得高质量的 PDF 输出。

需要注意的局限性

HTML 转 PDF API 使用 Google Chrome 的 HTML 渲染引擎。该引擎功能强大，但会带来一定的开销。例如，典型的 HTML 转 PDF 转换会比直接在 PDF 页面画布上绘制消耗更多的 CPU 和内存。这种开销会降低大批量生成的速度。

此外，浏览器引擎还会增加运行时占用空间，这在资源受限的 Docker 镜像或资源占用极低的环境中可能并不理想。例如，在对内存消耗和执行时间有严格限制的无服务器环境中，该 API 可能无法正常工作。

在 Docotic.Pdf 中生成 PDF 的其他方法

Docotic.Pdf 库还提供了其他几种生成文档的方法，每种方法都适合不同的需求：

通过 Canvas API 直接生成 PDF
非常适合用于结构化、可预测的布局，例如票据、标签或表单。提供卓越的性能，并可完全控制坐标、字体和内容位置。
基于模板的PDF生成
在处理已批准且符合合规性要求的模板时，这通常是最佳选择。您可以从现有的 PDF 文件入手，填写字段、替换占位符，并根据需要附加相关文档。
使用布局 API 生成 PDF
提供页面、容器、图像、文本段落和其他布局元素等构建模块。您可以使用流畅的 API 完全以代码形式描述 PDF 布局，库会根据您的布局生成 PDF。
由其他 PDF 和图像合成
提供一种轻量级的方法，可将现有 PDF 和图像组装成报表、报告、文档包和其他文档。您可以将图像转换为 PDF 页面、合并多个 PDF、追加页面或重复使用片段。

与其他 HTML 转 PDF 解决方案的比较

为了帮助您选择合适的 .NET HTML 转 PDF 库，以下信息介绍了带有 HtmlToPdf 插件的 Docotic.Pdf 与其他流行的 HTML 转 PDF 解决方案的比较情况。

主要对比要点

大多数基于浏览器的解决方案都能提供高质量的渲染效果，并完全支持现代的HTML、CSS和JavaScript。然而，它们之间也存在一些重要的差异。

解决方案	何时使用	最适合
使用 HtmlToPdf 插件的 Docotic.Pdf	以像素级完美的视觉保真度转换报告、发票和收据	需要同时具备 HTML 转 PDF 和 PDF 编辑功能的专业级软件，并提供专业技术支持
Puppeteer	当需要使用浏览器级别的保真度进行现代 HTML/CSS/JS 渲染，并且只需要 HTML 转 PDF 输出时	以像素级精度生成 HTML 到 PDF 文件，并要求免费或开源
IronPDF	当您的团队拥有 Iron Suite 许可证或之前使用过 IronPDF 时	依赖多个 Iron Software 组件的团队
wkhtmltopdf	当需要相对轻量级的资源占用，且您的 HTML/CSS 代码简洁，不包含外部或不受信任的引用时	与已使用 wkhtmltopdf 的系统保持兼容性

详细比较

请查看表格中的信息，以了解全貌并得出自己的结论。

	使用 HtmlToPdf 处理 Docot.Pdf	Puppeteer	IronPDF	wkhtmltopdf
引擎	Headless Chrome	Headless Chrome / Chromium	Headless Chrome	旧版 Qt WebKit
渲染保真度	像素级完美	像素级完美	像素级完美	像素级完美，但也存在一些怪癖和局限性
HTML5 支持	满的	满的	满的	部分且有限
CSS3 支持	满的	满的	满的	极其有限
JavaScript 支持	满的	满的	满的	不完整且已过时
与 .NET 代码集成	异步 .NET API	使用 PuppeteerSharp 时采用异步 .NET API；否则采用 Node.js 脚本。	异步 .NET API	命令行进程或 C# 封装库（例如 DinkToPdf）
除了 HTML 转换之外的 PDF 功能	广泛的	没有任何	有限的	没有任何
支持	商业的。可提供优先支持	社区。为 PuppeteerSharp 提供基于赞助商的优先支持	商业的。可提供优先支持	社区。没有正式的支持渠道
维护状态	积极维护	积极维护	积极维护	已停止维护
执照	商业的。符合条件的用例可使用免费许可	Apache-2.0。MIT 许可，适用于 PuppeteerSharp	商业的	LGPL-3.0；DinkToPdf 的 MIT 许可
再分发权	所有许可均免版税	所有许可均免版税	不包含在内；需要单独购买	所有许可均免版税
开发者许可	拥有所有许可证的无限开发者	拥有所有许可证的无限开发者	因许可证级别而异；只有最高级别的许可证才无限制	拥有所有许可证的无限开发者
在线驾照验证	无需在线验证	未进行许可证验证	除高级许可证外，所有许可证均需此项	未进行许可证验证

结论

Docotic.Pdf 及其 HtmlToPdf 插件提供可靠、高质量的 HTML 转 PDF 功能，并配备功能齐全的 PDF API。该库非常适合从 HTML 生成 PDF 报告、发票、收据和其他商务文档，并能完美保留像素级的视觉效果。

该插件提供完全本地运行的异步 .NET API。您的数据始终保留在您的服务器上，让您可以完全掌控安全性和隐私性。

除了 HTML 转 PDF 功能外，Docotic.Pdf 还可以为生成的 PDF 添加密码保护，并使用数字签名（包括 LTV 签名）进行签名。

您可以通过合并多个生成的 PDF 来组装最终文档。如果 HTML 转换或合并后 PDF 文件过大，该库可以删除文件中的重复对象，并应用其他方法来减小文件大小。为了改善阅读体验，Docotic.Pdf 还可以优化 PDF 用于 Fast Web View（线性化 PDF）。

使用免费许可证密钥试用该库

后续步骤：

查看 HTML 转 PDF 代码示例
探索更全面的库 API
如有任何疑问或建议，请联系我们

常见问题解答

如何为 .NET 选择合适的 HTML 转 PDF 库？

在选择库之前，请先定义并收集您的需求。如果您事先知道某个候选库无法合并转换后的 PDF 文件，而您的解决方案又需要此功能，那么在评估过程中就能节省时间。请参阅比较部分，了解常用的 .NET HTML 转 PDF 库的对比信息。

为什么我的HTML代码在PDF中无法正确渲染？

如果您的 HTML 代码在 Google Chrome 浏览器中显示正常，但在生成的 PDF 文件中显示异常，请检查转换选项。确保页面宽度足以容纳所有内容。HTML 代码可能还需要在转换前执行 JavaScript 代码。

为什么使用 HTML 模板而不是直接使用 PDF API？

使用 HTML 模板可以让您的解决方案在文档布局方面非常灵活。您可以利用 HTML 和 CSS 强大的样式功能轻松更改 PDF 的外观。此外，您无需使用 PDF API 来复制在线文档的设计。

如何将ASPX转换为PDF？

要将 ASPX 转换为 PDF，请让 ASP.NET 引擎为 ASPX 页面生成 HTML，然后使用 Docotic.Pdf 库将该 HTML 转换为 PDF。更多详细信息请参见相关章节。

如何将SVG图像叠加到PDF上？

要将 SVG 叠加到 PDF 上，请先从 SVG 生成 PDF，然后从生成的文档的第一页创建一个 XObject。由于 XObject 具有透明背景，因此您可以将其放置在另一个文档的 PDF 页面上。

如何给生成的PDF文件添加水印？

要向由 HTML 生成的 PDF 文档添加水印，请创建一个 XObject 对象，向其中填充水印内容，然后将该 XObject 对象绘制在文档页面上方。水印可以使用矢量图形、图像和文本。

Docotic.pdf 比 wkhtmltopdf 更好吗？

Docotic.Pdf 完全支持现代 HTML、CSS 和 JavaScript，而 wkhtmltopdf 对现代 Web 文档的渲染效果往往不一致。此外，Docotic.Pdf 提供的 API 功能不仅限于 HTML 转 PDF。例如，该库可以使用支持 LTV 的数字签名对 PDF 进行签名，而 wkhtmltopdf 只能转换 HTML。