如何在 C# 中為 PDF 渲染設定代理伺服器

簡化工作流程（3 個步驟）

1. 透過 NuGet 安裝 IronPDF：Install-Package IronPdf
2. 將代理字串作為第三個參數傳遞給 RenderHtmlAsPdf
3. 格式：http(s)://host:port 或 http(s)://user:pass@host:port 適用於需驗證的代理伺服器

如何將代理伺服器傳遞給 RenderHtmlAsPdf？

Proxy 參數是四個方法簽名中的可選 string：

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

// Instance methods
PdfDocument RenderHtmlAsPdf(string Html, string BaseUrlOrPath, string Proxy = null)
PdfDocument RenderHtmlAsPdf(string Html, Uri BaseUrl = null, string Proxy = null)

// Static methods
PdfDocument StaticRenderHtmlAsPdf(string Html, ChromePdfRenderOptions Options = null, string Proxy = null)
PdfDocument StaticRenderHtmlAsPdf(string Html, string BaseUrlOrPath, ChromePdfRenderOptions Options = null, string Proxy = null)

' Instance methods
Function RenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Proxy As String = Nothing) As PdfDocument
End Function

Function RenderHtmlAsPdf(Html As String, Optional BaseUrl As Uri = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

' Static methods
Shared Function StaticRenderHtmlAsPdf(Html As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

Shared Function StaticRenderHtmlAsPdf(Html As String, BaseUrlOrPath As String, Optional Options As ChromePdfRenderOptions = Nothing, Optional Proxy As String = Nothing) As PdfDocument
End Function

當此參數設定為 null（預設值）時，IronPDF 的 Chromium 引擎會直接連線至外部資源——即您 HTML 文件中引用的樣式表、圖片、字型及 JavaScript 檔案。 當您提供代理伺服器字串時，渲染引擎發出的所有 HTTP/HTTPS 請求都會透過該代理伺服器進行路由。

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.co/rp.local:8443"
);

using IronPdf;

var renderer = new ChromePdfRenderer();

// Direct connection (default — no proxy)
var pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>");

// Through an unauthenticated proxy
var pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath: null,
    proxy: "http://squid.internal:3128"
);

// Using the Uri overload
var pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl: new Uri("https://assets.example.com/"),
    proxy: "https://proxy.co/rp.local:8443"
);

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

' Direct connection (default — no proxy)
Dim pdfDirect = renderer.RenderHtmlAsPdf("<h1>Direct</h1>")

' Through an unauthenticated proxy
Dim pdfProxied = renderer.RenderHtmlAsPdf(
    "<h1>Proxied</h1>",
    baseUrlOrPath:=Nothing,
    proxy:="http://squid.internal:3128"
)

' Using the Uri overload
Dim pdfUri = renderer.RenderHtmlAsPdf(
    "<h1>Proxied via Uri overload</h1>",
    baseUrl:=New Uri("https://assets.example.com/"),
    proxy:="https://proxy.co/rp.local:8443"
)

代理字串同時支援 http:// 和 https:// 兩種格式。 當代理伺服器本身要求應用程式與代理伺服器之間的連線必須使用 TLS 加密時，請使用 https://。 此處的"方案"指的是代理連線，而非最終資源——http:// 代理仍可透過 CONNECT 隧道傳輸來擷取 https:// 資源。

靜態方法的變體接受相同的代理參數，這對於在主控台應用程式或單元測試中進行一次性渲染非常有用：

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.co/rp.local:8080"
);

// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.co/rp.local:8080"
);

' Static render with proxy — no renderer instance needed
Dim pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options:=Nothing,
    proxy:="http://proxy.co/rp.local:8080"
)

重要：ChromePdfRenderOptions 上不存在 Proxy 屬性。 不要在那裡尋找。 代理僅是 RenderHtmlAsPdf 和 FromHtml 重載方法中的參數。

如何透過企業代理伺服器進行驗證？

大多數Enterprise級代理伺服器都需要憑證。 您可以使用 http(s)://username:password@host:port 格式，將它們直接嵌入代理 URL 中：

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.co/rp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.co/rp.local:8080";

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: @"C:\templates\assets\",
    proxy: proxyWithAuth
);
pdf.SaveAs("report.pdf");

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

Dim proxyWithAuth As String = "http://svc-account:P%40ssw0rd%21@proxy.co/rp.local:8080"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
    htmlContent,
    baseUrlOrPath: "C:\templates\assets\",
    proxy:=proxyWithAuth
)
pdf.SaveAs("report.pdf")

請對密碼中的特殊字元進行 URL 編碼。若您的密碼包含 / 或其他保留的 URI 字元，必須進行百分比編碼。 常見編碼：

請使用 Uri.EscapeDataString() 來程式化地編碼密碼：

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.co/rp.local:8080";

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.co/rp.local:8080";

Imports System

Dim rawPassword As String = "P@ssw0rd!"
Dim encoded As String = Uri.EscapeDataString(rawPassword) ' "P%40ssw0rd%21"
Dim proxy As String = $"http://svc-account:{encoded}@proxy.co/rp.local:8080"

請勿將代理伺服器驗證與網頁驗證混淆。ChromeHttpLoginCredentials.Net/workUsername 和 NetworkPassword 屬性是用來對渲染中的網頁進行驗證（透過 NTLM/Negotiate 與網站進行驗證），而非對代理伺服器進行驗證。 關於代理伺服器驗證，憑證應如上所示，直接放入代理伺服器 URL 字串中。

如何渲染位於代理伺服器後方的 URL？

RenderUrlToPdf 不接受代理參數。 這是 API 設計上的刻意選擇 — NavigateUrl 會引導 Chromium 前往特定 URL，而該導航的代理伺服器設定處理方式，與 HTML 渲染期間的資源載入處理方式不同。

建議的解決方案：使用配置了 HttpProxy 的 HttpClient 自行擷取 HTML，然後將 HTML 字串傳遞給 RenderHtmlAsPdf 並帶上 proxy 參數（以便被引用的資源 — 圖片、CSS、字型 — 也能透過代理伺服器路由）。

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.co/rp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.co/rp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.co/rp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.co/rp.local:8080")
{
    Credentials = new NetworkCredential("svc-account", "P@ssw0rd!")
};

var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var httpClient = new HttpClient(handler);

// Step 2: Fetch the HTML from the target URL
string targetUrl = "https://dashboard.internal.co/rp/quarterly-report";
string html = await httpClient.GetStringAsync(targetUrl);

// Step 3: Render the fetched HTML, with the proxy for asset loading
var renderer = new ChromePdfRenderer();

PdfDocument pdf = renderer.RenderHtmlAsPdf(
    html,
    baseUrlOrPath: targetUrl,  // Resolves relative asset paths against the original URL
    proxy: "http://svc-account:P%40ssw0rd%21@proxy.co/rp.local:8080"
);
pdf.SaveAs("quarterly-report.pdf");

Imports IronPdf
Imports System.Net
Imports System.Net.Http

' Step 1: Configure HttpClient with the corporate proxy
Dim proxy As New WebProxy("http://proxy.co/rp.local:8080") With {
    .Credentials = New NetworkCredential("svc-account", "P@ssw0rd!")
}

Dim handler As New HttpClientHandler With {
    .Proxy = proxy,
    .UseProxy = True
}

Using httpClient As New HttpClient(handler)
    ' Step 2: Fetch the HTML from the target URL
    Dim targetUrl As String = "https://dashboard.internal.co/rp/quarterly-report"
    Dim html As String = Await httpClient.GetStringAsync(targetUrl)

    ' Step 3: Render the fetched HTML, with the proxy for asset loading
    Dim renderer As New ChromePdfRenderer()

    Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(
        html,
        baseUrlOrPath:=targetUrl,  ' Resolves relative asset paths against the original URL
        proxy:="http://svc-account:P%40ssw0rd%21@proxy.co/rp.local:8080"
    )
    pdf.SaveAs("quarterly-report.pdf")
End Using

將 baseUrlOrPath 參數設定為原始目標 URL，以便從抓取的 HTML 中解析相對路徑 (<img src="/images/logo.png">, <link href="/css/styles.css">) 時能正確解析。 proxy 參數可確保在渲染過程中，這些資源請求會透過代理伺服器進行路由。

此模式亦適用於需經身份驗證的頁面——在擷取前，請將 HttpClient 設定為適當的 Cookie 或標頭，然後將經過驗證的 HTML 傳遞給 IronPDF。 HTTP 請求標頭操作指南涵蓋了經過驗證請求的標頭設定。

若頁面仰賴 JavaScript 進行渲染（如單頁應用程式、React 儀表板、Angular 應用程式），所擷取的 HTML 僅會包含初始骨架——在 HttpClient 擷取過程中，客戶端渲染將不會執行。 針對此類情況，您有兩種選擇：設定系統層級的 HTTPS_PROXY 環境變數（詳見下一節），使 RenderUrlAsPdf() 在作業系統層級透過代理伺服器進行路由；或使用無頭瀏覽器先擷取完全渲染的 HTML，再將其傳遞給 RenderHtmlAsPdf()。

如何在 Docker 容器中設定代理伺服器？

在容器化環境中，您可能更傾向於採用系統層級的代理伺服器設定，而非逐個方法的參數設定。 IronPDF 的 Chromium 引擎支援 Linux 容器用於出站流量路由的標準 HTTP_PROXY 和 HTTPS_PROXY 環境變數。

請在您的 Dockerfile 中設定以下內容：

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# System-level proxy for all outbound HTTP/HTTPS traffic
ENV HTTP_PROXY=http://proxy.co/rp.local:8080
ENV HTTPS_PROXY=http://proxy.co/rp.local:8080
ENV NO_PROXY=localhost,127.0.0.1,.internal.co/rp

# Install IronPDF dependencies (fonts, etc.)
RUN apt-get update && apt-get install -y \
    libgdiplus \
    libc6-dev \
    fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

設定這些環境變數後，您即可在不指定 proxy 參數的情況下呼叫 RenderHtmlAsPdf — Chromium 會自動偵測系統層級的設定：

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

// No proxy parameter needed — Chromium uses HTTP_PROXY env var
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);

' No proxy parameter needed — Chromium uses HTTP_PROXY env var
Dim renderer As New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)

RenderHtmlAsPdf() 對內部資源而言至關重要。 若未如此設定，對內部服務（例如運行於 Kubernetes 叢集內的本地 CSS 伺服器或圖片 CDN）的請求將不必要地經由代理伺服器轉發。 請以逗號分隔應繞過代理伺服器的主機名稱與網域。

若您同時需要用於一般流量的系統層級代理伺服器，以及用於特定渲染的另一組代理伺服器，則方法參數的設定將優先於環境變數。 這讓您能在需要時對每次渲染進行控制。

您如何在 CI/CD 管道中處理代理伺服器？

企業網路中的 CI/CD 執行器通常位於代理伺服器之後。 請將代理伺服器 URL 作為建置變數或機密資訊傳遞 — 切勿在原始碼控制系統中硬編碼憑證。

GitHub Actions：

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{secrets.CORP_PROXY_URL}}
      HTTPS_PROXY: ${{secrets.CORP_PROXY_URL}}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

jobs:
  generate-pdf:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{secrets.CORP_PROXY_URL}}
      HTTPS_PROXY: ${{secrets.CORP_PROXY_URL}}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build
      - run: dotnet test

Azure DevOps：

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

variables:
  - group: proxy-settings  # Contains PROXY_URL secret

steps:
  - script: |
      export HTTP_PROXY=$(PROXY_URL)
      export HTTPS_PROXY=$(PROXY_URL)
      dotnet run --project PdfGenerator
    displayName: 'Generate PDFs behind proxy'

Jenkins（宣告式管線）：

environment {
    HTTP_PROXY  = credentials('corp-proxy-url')
    HTTPS_PROXY = credentials('corp-proxy-url')
}

在這三種情況下，Chromium 都會自動讀取環境變數。 若您偏好明確控制，請從環境中讀取代理伺服器網址，並將其作為方法參數傳入：

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

string? proxy = Environment.GetEnvironmentVariable("HTTPS_PROXY");
var pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath: null, proxy: proxy);

Option Strict On



Dim proxy As String = Environment.GetEnvironmentVariable("HTTPS_PROXY")
Dim pdf = renderer.RenderHtmlAsPdf(html, baseUrlOrPath:=Nothing, proxy:=proxy)

如何排除代理伺服器問題？

超時錯誤：企業代理伺服器會增加延遲。 將渲染超時從預設的 60 秒延長：

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120; // seconds

renderer.RenderingOptions.Timeout = 120 ' seconds

這是 RenderTimeout 屬性 —— 它控制 Chromium 等待頁面載入與資源擷取的總時間長度。 若您的代理伺服器每筆請求會增加 5 至 10 秒的延遲，且頁面需載入 20 個以上的外部資源，60 秒可能就不夠用了。

SSL 攔截（MITM 代理）：許多企業代理伺服器會使用企業根憑證來解密並重新加密 HTTPS 流量。 Chromium 會拒絕這些連線，因為它預設不信任該企業憑證授權機構。 兩種解決方案：

1. 將企業 CA 憑證安裝至容器或主機的受信任根儲存庫中。 在 Linux 上：將 .crt 複製到 /usr/local/share/ca-certificates/，並執行 update-ca-certificates。
2. 僅限於開發環境中，您可以停用憑證驗證 —— 但切勿在正式運作環境中執行此操作。 最安全的做法始終是安裝正確的憑證。

NTLM 驗證：內嵌的 user:pass@host 格式支援 Basic 和 Digest 代理伺服器驗證。 代理伺服器 URL 字串不支援 NTLM（常見於以 Windows 為核心的 Enterprise 環境）。 解決方案是在主機上或作為 sidecar 容器，執行如 CNTLM 之類的本地 NTLM 轉 Basic 轉發代理。 請使用您的 NTLM 憑證設定 CNTLM，然後將 IronPDF 指向 http://localhost:3128（CNTLM 的預設埠）。

空白 PDF 或資源缺失：若 PDF 能正常顯示但圖片/CSS 缺失，表示您的 HTML 引用了被代理伺服器封鎖的資源，或需要使用不同的代理路徑。 請確認 baseUrlOrPath 參數能否透過代理伺服器正確解析，並檢查代理伺服器的存取日誌中是否有 403 或 407 回應。

本地資源的代理伺服器繞過：若您的 HTML 同時引用了本地資源（封裝的圖片、內嵌 CSS）與遠端資源（CDN 字型、外部腳本），代理伺服器僅需處理遠端請求。 將 baseUrlOrPath 設定為本地目錄以存放檔案系統資源，並讓代理伺服器僅處理網路請求。 這可避免不必要地將本地檔案讀取透過代理伺服器進行。

連線診斷：在將代理字串用於 IronPDF 之前，請先透過簡單的 HttpClient 請求進行測試，以確認其正確性：

var proxy = new WebProxy("http://proxy.co/rp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Co/ntent.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

var proxy = new WebProxy("http://proxy.co/rp.local:8080");
var handler = new HttpClientHandler { Proxy = proxy, UseProxy = true };
using var client = new HttpClient(handler);

var response = await client.GetAsync("https://httpbin.org/ip");
Console.WriteLine(await response.Co/ntent.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP

Imports System.Net.Http
Imports System.Net

Dim proxy As New WebProxy("http://proxy.co/rp.local:8080")
Dim handler As New HttpClientHandler With {.Proxy = proxy, .UseProxy = True}
Using client As New HttpClient(handler)
    Dim response = Await client.GetAsync("https://httpbin.org/ip")
    Console.WriteLine(Await response.Content.ReadAsStringAsync())
    ' Should return the proxy's external IP, not your machine's IP
End Using

若此操作成功但 IronPDF 仍無法運作，問題很可能是 SSL 攔截，或是您的代理伺服器與 Chromium 的 CONNECT 隧道之間存在協定不符。 請確認代理伺服器是否支援 HTTPS 資源的 HTTP CONNECT 協定 — 部分代理伺服器需要明確設定才能允許隧道傳輸。

後續步驟