1. IronPDF
  2. 操作指南
  3. 基礎 URL 和資產編碼
如何在 C# 中使用基本網址生成 PDF

How to Use Base URLs & Asset Encoding in C# .NET 10

Curtis Chau
Curtis Chau
更新:
This article was translated from English: Does it need improvement?
Translated
View the article in English

IronPDF中的基本 URL 允許在 HTML 到 PDF 轉換期間正確載入 CSS、 JavaScript和圖像資源，方法是指定 BaseUrlOrPath 參數，該參數可以是 Web URL 或用於相對資源解析的本機檔案路徑。

快速入門：在IronPDF中實現基本 URL

在.NET C# 中，透過實作基本 URL 來實現 HTML 到 PDF 轉換期間的無縫資源加載，從而開始使用IronPDF 。 此範例示範如何設定 BaseUrlOrPath 以確保所有 CSS、 JavaScript和圖像都正確引用，從而以最少的設定簡化 PDF 產生。

  1. 使用NuGet套件管理器安裝https://www.nuget.org/packages/IronPdf

    PM > Install-Package IronPdf

  2. 複製並運行這段程式碼。

    new IronPdf.ChromePdfRenderer().RenderHtmlAsPdf("<img src='icons/logo.png'>", @"C:\site\assets\").SaveAs("with-assets.pdf");

  3. 部署到您的生產環境進行測試

    今天就在您的專案中開始使用免費試用IronPDF

    arrow pointer

最簡工作流程(5個步驟)

  1. 下載IronPDF ，支援 HTML、CSS 和影像轉換。
  2. 在 HTML 中為外部影像指定**`BaseUrlOrPath`**參數
  3. 在 MVC 中配置正確的**`src`**以用於 Web 和 PDF 顯示
  4. 為自訂頁首和頁尾指定**`BaseUrl`**屬性
  5. 檢查輸出的PDF文件


如何從包含圖像和 CSS 資源的 HTML 字串渲染 PDF？

將 HTML 字串轉換為 PDF 時，為 CSS、 JavaScript檔案和圖片等資源設定BaseUrlOrPath參數。 BaseUrlOrPath 指定所有資源載入的基本 URL。

這可以是"http"開頭的網頁 URL，用來載入遠端資源；也可以是存取磁碟上資源的本機檔案路徑。 正確設定 BaseUrlOrPath 可確保在轉換過程中資源正確載入。 有關 HTML 轉 PDF 的更多詳細信息，請查看我們全面的HTML 轉 PDF 教程。

:path=/static-assets/pdf/content-code-examples/how-to/base-urls-baseurl.cs
using IronPdf;

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

string baseUrl = @"C:\site\assets\";
string html = "<img src='icons/iron.png'>";

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html, baseUrl);

// Export PDF
pdf.SaveAs("html-with-assets.pdf");
$vbLabelText   $csharpLabel

對於涉及外部資源的複雜場景，請參閱我們關於管理字體或在 PDF 中新增圖像的指南。

如何在MVC應用程式中設定基本URL？

在 MVC 應用程式中，指定影像檔案路徑需要仔細配置。 To ensure IronPDF finds images and displays them correctly on the website, configure the baseUrl and HTML src="" attribute properly.

文件層次結構如下所示

  • baseUrlOrPath 到 @"wwwroot/image"
  • src 屬性到"../image/Sample.jpg"
wwwroot
└── image
    ├── Sample.jpg
    └── Sample.png

例如：

:path=/static-assets/pdf/content-code-examples/how-to/base-mvc.cs
// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("html.Result", @"wwwroot/image");
$vbLabelText   $csharpLabel 

<img src="../image/Sample.jpg"/>
<img src="../image/Sample.png"/>

<img src="../image/Sample.jpg"/>
<img src="../image/Sample.png"/>
HTML

有關ASP.NET Core MVC 的具體實現，請參閱我們的CSHTML 轉 PDF (MVC Core) 指南。

我應該避免使用哪些文件路徑格式？

警告

無效的檔案路徑格式

這些格式在 Chrome 瀏覽器中可以正常工作，但在 MVC 應用程式中指向錯誤的目錄。如果在 RenderHtmlAsPdf 方法中提供 baseUrlOrPath，則它們可以在IronPDF中正常工作：

<img src="image/footer.png"/>  
<img src="./image/footer.png"/>  
<img src="image/footer.png"/>  
<img src="./image/footer.png"/>
HTML

這些格式適用於 MVC 應用程序，但無法用於IronPDF檔案路徑：

<img src="/image/footer.png"/>  
<img src="~/image/footer.png"/>
<img src="/image/footer.png"/>  
<img src="~/image/footer.png"/>
HTML

)}]

資產加載方面常見的故障排除技巧有哪些？

當資源載入失敗時，請考慮以下故障排除步驟：

1.驗證絕對路徑：在開發過程中使用絕對檔案路徑來確認其可訪問性
2.檢查檔案權限：確保應用程式對資產目錄具有讀取權限
3.使用遠端 URL 進行測試：使用完全限定 URL 來隔離路徑問題
4.啟用日誌記錄：使用 IronPDF 的自訂日誌記錄功能來偵錯資源載入問題 

// Example: Debug asset loading with absolute paths
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Enable debug logging
renderer.RenderingOptions.EnableJavaScript = true;
renderer.RenderingOptions.WaitFor.RenderDelay(500); // Give assets time to load

// Use absolute path for testing
string absoluteBasePath = Path.GetFullPath(@"C:\MyProject\wwwroot\assets");
string html = @"
    <html>
    <head>
        <link rel='stylesheet' href='styles/main.css'>
    </head>
    <body>
        <img src='images/logo.png' />
        <script src='scripts/app.js'></script>
    </body>
    </html>";

PdfDocument pdf = renderer.RenderHtmlAsPdf(html, absoluteBasePath);
// Example: Debug asset loading with absolute paths
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Enable debug logging
renderer.RenderingOptions.EnableJavaScript = true;
renderer.RenderingOptions.WaitFor.RenderDelay(500); // Give assets time to load

// Use absolute path for testing
string absoluteBasePath = Path.GetFullPath(@"C:\MyProject\wwwroot\assets");
string html = @"
    <html>
    <head>
        <link rel='stylesheet' href='styles/main.css'>
    </head>
    <body>
        <img src='images/logo.png' />
        <script src='scripts/app.js'></script>
    </body>
    </html>";

PdfDocument pdf = renderer.RenderHtmlAsPdf(html, absoluteBasePath);
$vbLabelText   $csharpLabel

如何加入有圖片的HTML頁首和頁尾？

當將 HTML 頁首和頁尾渲染到新的或現有的 PDF 時，它們被視為獨立的 HTML 文檔，不會從 PDF 繼承 BaseURL。 有關更全面的頁首和頁尾選項，請參閱我們的頁首和頁尾指南。

設定資源載入的 BaseURL：

:path=/static-assets/pdf/content-code-examples/how-to/base-header-footer.cs
using IronPdf;
using System;

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

// Add header
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    MaxHeight = 20,
    HtmlFragment = "<img src='logo.png'>",
    BaseUrl = new Uri(@"C:\assets\images\").AbsoluteUri
};
$vbLabelText   $csharpLabel

為什麼頭部資訊不繼承主文檔的基本URL？

為了提高效能和實作隔離，頁首和頁尾會渲染成單獨的 HTML 文件。 這種設計允許：

  • 獨立樣式，不影響主要內容
  • 所有頁面呈現一致
  • 更好地管理大型文件的內存
  • 可靈活使用不同的資產來源

如何為郵件​​頭和郵件內容設定不同的基本URL？

為頁首、頁尾和主要內容指定不同的基本 URL，以便有效組織資源：

ChromePdfRenderer renderer = new ChromePdfRenderer();

// Main content base URL
string contentBaseUrl = @"C:\website\public\";

// Header specific assets
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    HtmlFragment = "<img src='header-logo.png'><link rel='stylesheet' href='header.css'>",
    BaseUrl = new Uri(@"C:\website\headers\").AbsoluteUri
};

// Footer specific assets
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
    HtmlFragment = "<div class='footer'>© 2024 Company</div><link rel='stylesheet' href='footer.css'>",
    BaseUrl = new Uri(@"C:\website\footers\").AbsoluteUri
};

// Render main content with its own base URL
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main Content</h1>", contentBaseUrl);
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Main content base URL
string contentBaseUrl = @"C:\website\public\";

// Header specific assets
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    HtmlFragment = "<img src='header-logo.png'><link rel='stylesheet' href='header.css'>",
    BaseUrl = new Uri(@"C:\website\headers\").AbsoluteUri
};

// Footer specific assets
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
    HtmlFragment = "<div class='footer'>© 2024 Company</div><link rel='stylesheet' href='footer.css'>",
    BaseUrl = new Uri(@"C:\website\footers\").AbsoluteUri
};

// Render main content with its own base URL
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main Content</h1>", contentBaseUrl);
$vbLabelText   $csharpLabel

如何將包含本機資源的 HTML 檔案轉換為 PDF？

將 HTML 檔案渲染為 PDF 時，所有資源都假定位於該檔案本機。請參閱我們的HTML 文件轉 PDF 指南，以了解更多關於 HTML 文件轉換的資訊。

:path=/static-assets/pdf/content-code-examples/how-to/base-html-file.cs
using IronPdf;

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

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlFileAsPdf("C:\\Assets\\TestInvoice1.html");

// Export PDF
pdf.SaveAs("Invoice.pdf");
$vbLabelText   $csharpLabel

在上面的範例中，所有 JS、CSS 和映像檔都從磁碟上的 C:\Assets 資料夾載入——與 HTML 檔案位於同一目錄。

For convenience, use CustomCssUrl in ChromePdfRenderOptions for Additional Stylesheets to specify an additional stylesheet used only for .NET PDF rendering if desired. 例如：

:path=/static-assets/pdf/content-code-examples/how-to/base-html-file-baseurl.cs
using IronPdf;

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

// Set additional CSS url
renderer.RenderingOptions.CustomCssUrl = "./style.css";

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export PDF
pdf.SaveAs("tryCss.pdf");
$vbLabelText   $csharpLabel

請注意該屬性目前僅在使用 RenderHtmlAsPdf 方法將 HTML 字串渲染為 PDF 時有效。

何時應該使用 CustomCssUrl 進行額外樣式設定？

CustomCssUrl 非常適合用於：
-特定於列印的樣式：隱藏導覽選單或互動元素

  • PDF佈局最佳化：調整列印時的頁邊距和分頁符
    -條件格式：僅在產生 PDF 時套用樣式
  • A/B 測試：在不修改來源 HTML 的情況下測試不同的 PDF 佈局

如何在HTML檔案中處理相對資源路徑？

處理包含相對路徑的 HTML 檔案時，請確保檔案結構支援這些引用：

// Example HTML file structure
/*
C:\Projects\Reports\
    ├── invoice.html
    ├── css\
    │   └── styles.css
    ├── js\
    │   └── calculations.js
    └── images\
        └── logo.png
*/

// HTML content with relative paths
string htmlContent = @"
<!DOCTYPE html>
<html>
<head>
    <link rel='stylesheet' href='css/styles.css'>
    <script src='js/calculations.js'></script>
</head>
<body>
    <img src='images/logo.png' alt='Company Logo'>
    <h1>Invoice #12345</h1>
</body>
</html>";

// Save HTML and render
File.WriteAllText(@"C:\Projects\Reports\invoice.html", htmlContent);
ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlFileAsPdf(@"C:\Projects\Reports\invoice.html");
pdf.SaveAs("invoice-output.pdf");
// Example HTML file structure
/*
C:\Projects\Reports\
    ├── invoice.html
    ├── css\
    │   └── styles.css
    ├── js\
    │   └── calculations.js
    └── images\
        └── logo.png
*/

// HTML content with relative paths
string htmlContent = @"
<!DOCTYPE html>
<html>
<head>
    <link rel='stylesheet' href='css/styles.css'>
    <script src='js/calculations.js'></script>
</head>
<body>
    <img src='images/logo.png' alt='Company Logo'>
    <h1>Invoice #12345</h1>
</body>
</html>";

// Save HTML and render
File.WriteAllText(@"C:\Projects\Reports\invoice.html", htmlContent);
ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlFileAsPdf(@"C:\Projects\Reports\invoice.html");
pdf.SaveAs("invoice-output.pdf");
$vbLabelText   $csharpLabel

如何使用 Base64 直接在 HTML 中對影像進行編碼？

圖片資源可以直接編碼到 HTML 檔案或字串中，避免圖片缺失的問題。 此方法請使用 base64 編碼。 有關處理各種圖像格式的信息，請參閱我們的圖像指南。

  1. 首先透過讀取檔案或透過網路請求接收來取得影像的二進位資料。
  2. 使用 Microsoft .NET中的 Convert.ToBase64String 方法將二進位資料轉換為 base64。
  3. 在 HTML 中使用"data:image/svg+xml;base64"在 base64 資料之前建立圖像標籤。 請注意，影像類型是在 base64 資料之前指定的。 有關圖像格式類型的更多信息，請訪問MDN Web 文件中的"圖像類型和格式"部分。
:path=/static-assets/pdf/content-code-examples/how-to/add-images-to-pdfs-base64-image.cs
using IronPdf;
using System;
using System.IO;

ChromePdfRenderer renderer = new ChromePdfRenderer();

// Import image file binary data
byte[] binaryData = File.ReadAllBytes("ironpdf-logo-text-dotnet.svg");

// Convert the binary data to base 64
string imgDataUri = Convert.ToBase64String(binaryData);

// Embed in HTML
string html = $"<img src='data:image/svg+xml;base64,{imgDataUri}'>";

// Convert HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html);

// Export the PDF
pdf.SaveAs("embedImageBase64.pdf");
$vbLabelText   $csharpLabel

為什麼我會選擇 Base64 編碼而不是檔案引用？

Base64編碼有以下幾個優點：
-自包含 HTML ：無外部依賴，簡化分發
-跨平台相容性：不受檔案系統差異的影響
-安全性：無需存取檔案系統，降低安全風險
-可靠性：消除生產中資產缺失錯誤
-版本控制：圖像是 HTML 的一部分，簡化了版本控制。

但是，請考慮以下權衡利弊：

  • HTML 檔案大小增加：Base64 編碼會使檔案大小增加約 33%。
    -不支援快取：嵌入式圖片無法單獨快取。
    -記憶體使用情況：整個圖像必須載入到記憶體中

哪些影像格式最適合 Base64 編碼？

不同影像格式在進行 Base64 編碼時效率各不相同：

// Example: Encoding different image formats
public string EncodeImageWithMimeType(string imagePath)
{
    byte[] imageBytes = File.ReadAllBytes(imagePath);
    string base64 = Convert.ToBase64String(imageBytes);

    // Determine MIME type based on extension
    string extension = Path.GetExtension(imagePath).ToLower();
    string mimeType = extension switch
    {
        ".png" => "image/png",      // Best for graphics with transparency
        ".jpg" or ".jpeg" => "image/jpeg",  // Best for photographs
        ".gif" => "image/gif",       // Best for simple animations
        ".svg" => "image/svg+xml",   // Best for scalable graphics
        ".webp" => "image/webp",     // Best overall compression
        _ => "image/png"             // Default fallback
    };

    return $"data:{mimeType};base64,{base64}";
}

// Usage
string encodedImage = EncodeImageWithMimeType("logo.png");
string html = $"<img src='{encodedImage}' alt='Company Logo'>";
// Example: Encoding different image formats
public string EncodeImageWithMimeType(string imagePath)
{
    byte[] imageBytes = File.ReadAllBytes(imagePath);
    string base64 = Convert.ToBase64String(imageBytes);

    // Determine MIME type based on extension
    string extension = Path.GetExtension(imagePath).ToLower();
    string mimeType = extension switch
    {
        ".png" => "image/png",      // Best for graphics with transparency
        ".jpg" or ".jpeg" => "image/jpeg",  // Best for photographs
        ".gif" => "image/gif",       // Best for simple animations
        ".svg" => "image/svg+xml",   // Best for scalable graphics
        ".webp" => "image/webp",     // Best overall compression
        _ => "image/png"             // Default fallback
    };

    return $"data:{mimeType};base64,{base64}";
}

// Usage
string encodedImage = EncodeImageWithMimeType("logo.png");
string html = $"<img src='{encodedImage}' alt='Company Logo'>";
$vbLabelText   $csharpLabel

Base64編碼如何影響PDF檔案大小？

Base64編碼對PDF檔案大小的影響是可以預見的：

// Comparison example
public void CompareFileSizes()
{
    ChromePdfRenderer renderer = new ChromePdfRenderer();

    // Method 1: External image reference
    string htmlExternal = "<img src='large-photo.jpg'>";
    PdfDocument pdfExternal = renderer.RenderHtmlAsPdf(htmlExternal, @"C:\images\");

    // Method 2: Base64 encoded image
    byte[] imageBytes = File.ReadAllBytes(@"C:\images\large-photo.jpg");
    string base64Image = Convert.ToBase64String(imageBytes);
    string htmlBase64 = $"<img src='data:image/jpeg;base64,{base64Image}'>";
    PdfDocument pdfBase64 = renderer.RenderHtmlAsPdf(htmlBase64);

    // Compare sizes
    Console.WriteLine($"Original image: {imageBytes.Length / 1024} KB");
    Console.WriteLine($"PDF with external image: {pdfExternal.BinaryData.Length / 1024} KB");
    Console.WriteLine($"PDF with base64 image: {pdfBase64.BinaryData.Length / 1024} KB");
}
// Comparison example
public void CompareFileSizes()
{
    ChromePdfRenderer renderer = new ChromePdfRenderer();

    // Method 1: External image reference
    string htmlExternal = "<img src='large-photo.jpg'>";
    PdfDocument pdfExternal = renderer.RenderHtmlAsPdf(htmlExternal, @"C:\images\");

    // Method 2: Base64 encoded image
    byte[] imageBytes = File.ReadAllBytes(@"C:\images\large-photo.jpg");
    string base64Image = Convert.ToBase64String(imageBytes);
    string htmlBase64 = $"<img src='data:image/jpeg;base64,{base64Image}'>";
    PdfDocument pdfBase64 = renderer.RenderHtmlAsPdf(htmlBase64);

    // Compare sizes
    Console.WriteLine($"Original image: {imageBytes.Length / 1024} KB");
    Console.WriteLine($"PDF with external image: {pdfExternal.BinaryData.Length / 1024} KB");
    Console.WriteLine($"PDF with base64 image: {pdfBase64.BinaryData.Length / 1024} KB");
}
$vbLabelText   $csharpLabel

為了獲得最佳效果：

  • 小圖示和標誌（< 50KB）請使用 base64 編碼
  • 對於大型圖像和照片，請使用外部參考資料。
  • 編碼前請考慮壓縮。
  • 使用適合內容類型的圖像格式

如需了解更進階的 PDF 最佳化技巧，請參閱我們的PDF 壓縮指南。

常見問題解答

將 HTML 轉換為 PDF 時，如何確保 CSS 和 JavaScript 資產能正確載入？

IronPDF 允許您在 HTML 轉換為 PDF 時指定一個 BaseUrlOrPath 參數。此參數可以是網頁 URL 或本機檔案路徑，作為 HTML 中所有相對資產路徑的基本參考，以確保 CSS、JavaScript 和圖片能正確載入。

BaseUrlOrPath 參數有何用途？

IronPDF 中的 BaseUrlOrPath 參數指定了所有資產（CSS、JavaScript、圖片）在 HTML 轉換為 PDF 時相對載入的基本 URL。對於遠端資產，它可以設定為以 'http' 開頭的 web URL；對於基於磁碟的資產，它可以設定為本機檔案路徑。

如何只用一行代碼就能渲染出有資產的 PDF？

您可以使用 IronPDF 的 ChromePdfRenderer 在一行中渲染包含資產的 HTML：`new IronPdf.ChromePdfRenderer().RenderHtmlAsPdf("", @"C:\site\assets\").SaveAs("with-assets.pdf");`.這會設定 BaseUrlOrPath，以確保所有資產都能正確載入。

如何在 MVC 應用程式中設定影像路徑以產生 PDF？

在使用 IronPDF 的 MVC 應用程式中，請將 baseUrlOrPath 設定為您的 wwwroot 子目錄 (例如 @"wwwroot/image「)，並將 HTML src 屬性設定為相對路徑 (例如 」.../image/Sample.jpg" )。這可確保圖像在網站上和產生的 PDF 中都能正確顯示。

將 HTML 轉換為 PDF 時，可以同時使用本機和遠端資產嗎？

是的，IronPDF 支持本地和远程资產。對於遠端資產，請將 BaseUrlOrPath 設定為以 'http' 開頭的 Web URL。對於本機資產，請使用磁碟上的檔案路徑。這種靈活性允許您在 PDF 生成過程中引用來自不同來源的資產。

如果我沒有設定 BaseUrlOrPath 參數會如何？

如果不在 IronPDF 中設定 BaseUrlOrPath 參數，HTML 中的相對資產路徑將無法正確解析，導致生成的 PDF 中遺失 CSS 式樣、JavaScript 功能和圖片。當您的 HTML 包含相對資產參考時，請務必指定此參數。

Curtis Chau
Curtis Chau
  立即與工程團隊聊天
技術作家

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

除了開發之外，Curtis 對物聯網 (IoT) 有著濃厚的興趣，探索將硬體和軟體結合的創新方式。在閒暇時間，他喜愛遊戲並構建 Discord 機器人，結合科技與創意的樂趣。

準備好開始了嗎？
Nuget 下載 17,803,474 | 版本： 2026.3 剛剛發布
Still Scrolling Icon

還在滾動嗎？

想快速取得證據？ PM > Install-Package IronPdf
運行範例看著你的HTML程式碼變成PDF檔。