C# 中的 HTML 轉 PDF - 庫選項的現實

wkhtmltopdf 封裝器 — DLL 載入錯誤生態系統

開發者最常搜尋到這些文章的關鍵字是以下幾種變體：

System.DllNotFoundException：無法載入 DLL"libwkhtmltox"

平台特定變體包括：

無法載入共用庫"wkhtmltox"或其某個依賴項
    (Linux — libwkhtmltox.so not found)

找不到指定的模組。 (0x8007007E)
    (Windows — wkhtmltox.dll path not configured)

dyld：庫未載入：libwkhtmltox.dylib
    (macOS — not supported on ARM64/Apple Silicon)

這些錯誤來自 DinkToPdf、NReco.PdfGenerator、WkHtmlToXSharp 以及其他圍繞同一個已廢棄二進位檔案的 C# 封裝程式。 wkhtmltopdf GitHub組織已於 2024 年 7 月存檔。 QtWebKit 底層引擎已於 2015 年被 Qt 棄用。專案狀態頁面明確將其標記為已棄用。

除了 DLL 載入問題之外，渲染引擎的效能也僅停留在 Safari 2011 的水平。 沒有 Flexbox，沒有 Grid，CSS3 功能有限， JavaScript不穩定。 此外，還有一些未修復的嚴重漏洞： CVE-2022-35583 (CVSS 9.8) 可利用 SSRF 攻擊，透過精心建構的 HTML 竊取 AWS 憑證。

wkhtmltopdf 的時代已經過去了。 DLL 載入錯誤是更深層問題的徵兆：你依賴的軟體已經過時，沒有出路。

iText 7(pdfHTML 外掛程式)— 有限的 CSS，AGPL 許可

為什麼 PdfSharp 不支援 HTML？

PdfSharp因其受歡迎程度(3,490 萬NuGet下載)和頻繁推薦而出現在"HTML 轉 PDF"搜尋結果中。 但 PdfSharp 沒有 HTML 解析器。 它提供基於座標的繪圖 API：DrawImage()，具有明確的 X/Y 位置。

常用的解決方法 HtmlRenderer.PdfSharp 僅支援 HTML 4.01 和 CSS Level 2。 如果您的 HTML 使用了 2010 年之後引入的任何 CSS 功能——Flexbox(2012 年)、Grid(2017 年)、自訂屬性(2017 年)、border-radius(2011 年)——它將無法渲染。

選擇 PdfSharp 並期望獲得 HTML 支援的開發者最終要么需要使用基於坐標的程式碼手動定位每個元素，要么需要添加第二個庫來進行 HTML 渲染——此時 PdfSharp 就顯得多餘了。

是什麼讓《Puppeteer》成為資源密集遊戲？

Puppeteer Sharp透過.NET綁定控制無頭 Chrome 瀏覽器。 渲染精準度與 Chrome 一致，因為它就是 Chrome。 成本在於營運方面：您需要管理外部瀏覽器進程。

以下是 木偶師夏普 生產環境的實際部署範例——不是教程中的 5 行範例程式碼，而是並發生成 PDF 所需的瀏覽器池程式碼：

using PuppeteerSharp;
using System.Collections.Concurrent;

public class PdfBrowserPool : IAsyncDisposable
{
    private readonly ConcurrentBag<IBrowser> _available = new();
    private readonly SemaphoreSlim _semaphore;
    private readonly int _maxBrowsers;

    public PdfBrowserPool(int maxBrowsers = 4)
    {
        _maxBrowsers = maxBrowsers;
        _semaphore = new SemaphoreSlim(maxBrowsers, maxBrowsers);
    }

    public async Task InitializeAsync()
    {
        await new BrowserFetcher().DownloadAsync(); // ~280MB download
        for (int i = 0; i < _maxBrowsers; i++)
        {
            var browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox",
                               "--disable-dev-shm-usage" }
            });
            _available.Add(browser);
        }
    }

    public async Task<byte[]> ConvertHtmlToPdf(string html)
    {
        await _semaphore.WaitAsync();
        IBrowser browser = null;
        try
        {
            if (!_available.TryTake(out browser))
                throw new InvalidOperationException("No browser available");

            await using var page = await browser.NewPageAsync();
            await page.SetContentAsync(html, new NavigationOptions
            {
                WaitUntil = new[] { WaitUntilNavigation.Networkidle0 }
            });
            var result = await page.PdfAsync(new PdfOptions
            {
                Format = PaperFormat.A4,
                PrintBackground = true
            });
            return result;
        }
        catch (Exception ex) when (ex is NavigationException or TargetClosedException)
        {
            // Browser crashed — replace it
            browser?.Dispose();
            browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox" }
            });
            throw; // Re-throw after recovery
        }
        finally
        {
            if (browser != null) _available.Add(browser);
            _semaphore.Release();
        }
    }

    public async ValueTask DisposeAsync()
    {
        foreach (var browser in _available)
        {
            await browser.CloseAsync();
            browser.Dispose();
        }
    }
}

using PuppeteerSharp;
using System.Collections.Concurrent;

public class PdfBrowserPool : IAsyncDisposable
{
    private readonly ConcurrentBag<IBrowser> _available = new();
    private readonly SemaphoreSlim _semaphore;
    private readonly int _maxBrowsers;

    public PdfBrowserPool(int maxBrowsers = 4)
    {
        _maxBrowsers = maxBrowsers;
        _semaphore = new SemaphoreSlim(maxBrowsers, maxBrowsers);
    }

    public async Task InitializeAsync()
    {
        await new BrowserFetcher().DownloadAsync(); // ~280MB download
        for (int i = 0; i < _maxBrowsers; i++)
        {
            var browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox",
                               "--disable-dev-shm-usage" }
            });
            _available.Add(browser);
        }
    }

    public async Task<byte[]> ConvertHtmlToPdf(string html)
    {
        await _semaphore.WaitAsync();
        IBrowser browser = null;
        try
        {
            if (!_available.TryTake(out browser))
                throw new InvalidOperationException("No browser available");

            await using var page = await browser.NewPageAsync();
            await page.SetContentAsync(html, new NavigationOptions
            {
                WaitUntil = new[] { WaitUntilNavigation.Networkidle0 }
            });
            var result = await page.PdfAsync(new PdfOptions
            {
                Format = PaperFormat.A4,
                PrintBackground = true
            });
            return result;
        }
        catch (Exception ex) when (ex is NavigationException or TargetClosedException)
        {
            // Browser crashed — replace it
            browser?.Dispose();
            browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox" }
            });
            throw; // Re-throw after recovery
        }
        finally
        {
            if (browser != null) _available.Add(browser);
            _semaphore.Release();
        }
    }

    public async ValueTask DisposeAsync()
    {
        foreach (var browser in _available)
        {
            await browser.CloseAsync();
            browser.Dispose();
        }
    }
}

在產生單一 PDF 檔案之前，需要編寫大約 60 行基礎架構程式碼。 您還需要記憶體洩漏監控(Chromium 進程會隨著時間的推移累積記憶體)、健康檢查以及包含 20 多個 Chromium 依賴項的 Dockerfile。 Docker 映像大小增加 300-400MB。

將此與IronPDF 的等效方法進行比較：

using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
// Browser pooling, process management, crash recovery — handled internally

using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
// Browser pooling, process management, crash recovery — handled internally

如果你的團隊能夠承擔營運成本，那麼 木偶師夏普 是一個可行的選擇。 對於希望專注於應用程式而不是瀏覽器基礎架構的團隊來說， IronPDF在內部處理相同的渲染工作。

為什麼 QuestPDF 無法轉換 HTML？

在 Reddit 和 Stack Overflow 上幾乎所有關於"HTML 轉 PDF C#"的討論中都會提到 QuestPDF。 這造成了一致的模式：開發者購買或整合 QuestPDF 時期望它能進行 HTML 轉換，然後發現它根本不渲染 HTML。

QuestPDF是一個流暢的 C# API，用於以程式設計方式建立文件。 它的定位明確是"停止與 HTML 到 PDF 的轉換作鬥爭"——它用 C# 程式碼取代了 HTML 方法。 這是有意為之的設計選擇。 2022年至 2024 年的GitHub討論顯示，開發者是在開始實施後才發現這一點的。 維護人員始終確認暫無計劃支援 HTML。

如果您現有的工作流程使用 HTML 範本(例如用於發票的Razor檢視、用於報表的儀表板 HTML、用於歸檔的 Web 內容)，QuestPDF 要求使用 C# 串流 API 程式碼重寫每個範本。 對於使用結構化資料從頭開始建立文件佈局的新項目，QuestPDF 的 API 設計精良且有效率。

社區許可證適用於年總收入低於 100 萬美元的企業。 除此之外，還需要商業許可。

Aspose.PDF怎麼樣？

Aspose.PDF 提供廣泛的 PDF 功能，採用商業許可模式(起價約為 999 美元/開發人員)。 HTML 轉換使用自訂引擎，而不是瀏覽器——類似於 iText，它可以處理基本的 HTML，但不能準確地渲染現代 CSS 功能。

主要問題是平台穩定性：Aspose 依賴 System.Drawing.Common，而 System.Drawing.Common 在 Linux 上需要 libgdiplus。 微軟在.NET 6+ 中棄用了對非 Windows 平台的此功能。 開發人員報告稱，Linux 部署中存在特有的記憶體洩漏問題，而 Windows 上不會出現此類問題。 Aspose 能夠滿足僅限 Windows 環境的需求。 對於跨平台或容器化部署，依賴鏈會帶來持續的風險。

如何從其他庫遷移？

對於從 iTextSharp 或 wkhtmltopdf 遷移過來的團隊， IronPDF直接接受 URL——當您現有的工作流程產生 HTML 檔案或提供頁面時，這非常有用：

using IronPdf;

var renderer = new ChromePdfRenderer();

// Convert from URL — useful when migrating from wkhtmltopdf URL-based workflows
var pdf = renderer.RenderUrlAsPdf("https://localhost:5001/reports/quarterly");
pdf.SaveAs("report.pdf");

// Convert from local HTML file
var pdfFromFile = renderer.RenderHtmlFileAsPdf("templates/invoice.html");
pdfFromFile.SaveAs("invoice.pdf");

using IronPdf;

var renderer = new ChromePdfRenderer();

// Convert from URL — useful when migrating from wkhtmltopdf URL-based workflows
var pdf = renderer.RenderUrlAsPdf("https://localhost:5001/reports/quarterly");
pdf.SaveAs("report.pdf");

// Convert from local HTML file
var pdfFromFile = renderer.RenderHtmlFileAsPdf("templates/invoice.html");
pdfFromFile.SaveAs("invoice.pdf");

部署

IronPDF可在 Windows (x64)、Linux (x64, ARM64)、macOS (x64, Apple Silicon) 和 Docker 容器上運作。 Docker 配置是標準的.NET映像：

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY . .
ENTRYPOINT ["dotnet", "MyApp.dll"]

無需安裝 Chromium，無需依賴原生庫，無需沙箱配置。

許可：永久許可起價為 749 美元。定價資訊請造訪IronPDF 。 無AGPL協議，無單件收費，無收入門檻。