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

如何在 C# .NET 10 中使用基本 URL 和資源編碼

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

透過指定 BaseUrlOrPath 參數，IronPDF 中的基本 URL 可讓 CSS、JavaScript 和圖片資產在 HTML 至 PDF 的轉換過程中被正確載入，該參數可以是網頁 URL 或用於相對資產解析的本機檔案路徑。

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

在使用 .NET C# 將 HTML 轉換為 PDF 的過程中，透過實作基礎 URL 來實現資產的無縫載入，即可開始使用 IronPDF。 本範例示範如何設定 BaseUrlOrPath 以確保所有 CSS、JavaScript 和圖片都能正確引用，以最少的設定簡化 PDF 的產生。

Nuget Icon立即開始使用 NuGet 建立 PDF 檔案：

  1. 使用 NuGet 套件管理器安裝 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 中為網頁和 PDF 顯示配置正確的 src
  4. 為自訂頁首和頁尾指定 BaseUrl 屬性
  5. 檢查輸出PDF


我該如何使用圖片和 CSS 資產從 HTML 字串渲染 PDF？

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

這可以是以 'http' 開頭的網頁 URL，用來載入遠端資產；或是本機檔案路徑，用來存取磁碟上的資產。 正確設定 BaseUrlOrPath 可確保資產在轉換過程中正常載入。 如需瞭解 HTML 轉換為 PDF 的更多詳細資訊，請查看我們全面的 HTML to 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 <code 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 to 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

請注意ChromePdfRenderOptions.CustomCssUrl屬性目前僅在使用RenderHtmlAsPdf方法從 HTML 字串渲染至 PDF 時起作用。

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

CustomCssUrl 非常適合以下用途：

  • Print 特定樣式：隱藏導航選單或互動元素
  • PDF版面最佳化：調整邊距和分頁符以利列印
  • 條件格式化：僅在產生 PDF 時套用樣式
  • A/B測試：測試不同的PDF版面，而無需修改來源HTML

如何處理 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。

  1. 在 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

為達到最佳效果：

  • 小圖示和標誌使用 base64 (< 50KB)
  • 大型圖片和照片使用外部參考資料
  • 編碼前考慮壓縮
  • 針對內容類型使用適當的圖片格式

如需進階的 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 bots，將他對技術的熱愛與創意結合。

準備好開始了嗎？
Nuget 下載 17,570,948 | 版本： 2026.2 剛剛發布