如何在 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://。 此处的"方案"指的是代理连接，而非最终资源——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"
)

重要提示：Proxy 属性不存在于 ChromePdfRenderOptions 上。 别在那儿找。 该代理严格仅作为 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 字符，必须对其进行百分比编码。 常用编码：

using 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 字符串通过 proxy 参数传递给 RenderHtmlAsPdf（以便引用的资源——图像、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 中的相对路径（<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"]

设置这些环境变量后，您可以不带代理参数直接调用 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 都会自动读取环境变量。 如果您希望进行显式控制，请从环境中读取代理 URL 并将其作为方法参数传递：

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 拦截（中间人代理）：许多企业代理会使用企业根 CA 证书对 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 环境）。 解决方法是在主机上或作为侧车容器运行本地 NTLM 到 Basic 的转发代理，例如 CNTLM。 使用您的 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 协议——某些代理需要显式配置才能允许隧道传输。

后续步骤