1. IronPDF
  2. 操作指南
  3. 代理配置

如何在C#中配置代理服务器进行PDF渲染

Darrius Serrant
Darrius Serrant
已更新:
This article was translated from English: Does it need improvement?
Translated
View the article in English

在IronPDF中，代理配置是RenderHtmlAsPdf()重载的方法参数，而不是ChromePdfRenderOptions上的属性。 这种区别很重要，因为RenderHtmlAsPdf()根本没有代理参数，这需要针对在公司代理后面渲染实时URLs时采用不同的策略。 如果您传递null（默认），IronPDF将直接连接。

本指南涵盖您在生产中遇到的所有代理情景：直接代理字符串、经过认证的公司代理、RenderUrlAsPdf解决方案、Docker容器配置、CI/CD管道集成，以及SSL拦截和NTLM认证的常见故障排除模式。

开始免费30天试用以测试您环境中的代理配置。

快速入门：通过代理渲染PDF

IronPDF的可选proxy参数可以帮助您转换位于公司代理后的实时网页。 使用此代码片段快速入门。

  1. 使用 NuGet 包管理器安装 https://www.nuget.org/packages/IronPdf

    PM > Install-Package IronPdf

  2. 复制并运行这段代码。

    using IronPdf;

var renderer = new ChromePdfRenderer();

// Proxy is the third parameter — not a render option
PdfDocument pdf = renderer.RenderHtmlAsPdf(
    "<h1>Hello from behind the proxy</h1>",
    baseUrlOrPath: null,
    proxy: "http://proxy.corp.local:8080"
);
pdf.SaveAs("proxied-output.pdf");

  3. 部署到您的生产环境中进行测试

    通过免费试用立即在您的项目中开始使用IronPDF

    arrow pointer

最小工作流程（3步）

  1. 通过NuGet安装IronPDF：Install-Package IronPdf
  2. 将代理字符串作为第三个参数传递给RenderHtmlAsPdf
  3. 格式：http(s)://user:pass@host:port用于认证的代理

如何将代理传递给RenderHtmlAsPdf？

参数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
$vbLabelText   $csharpLabel

当此参数为null（默认）时，IronPDF的Chromium引擎直接连接到外部资源——样式表、图片、字体和HTML中引用的JavaScript文件。 当您提供代理字符串时，渲染引擎的所有HTTP/HTTPS请求都会通过该代理路由。

:path=/static-assets/pdf/content-code-examples/how-to/proxy-3.cs
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.corp.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.corp.local:8443"
)
$vbLabelText   $csharpLabel

代理字符串支持https://协议。 当代理本身需要为您的应用程序和代理服务器之间的连接启用TLS加密时，使用https://。 这里的协议是指代理连接，而不是最终资源——一个https://资源。

静态方法变体接受相同的代理参数，这对控制台应用程序或单元测试中的一次性渲染非常有用：

:path=/static-assets/pdf/content-code-examples/how-to/proxy-4.cs
// Static render with proxy — no renderer instance needed
var pdf = ChromePdfRenderer.StaticRenderHtmlAsPdf(
    "<h1>Static render through proxy</h1>",
    options: null,
    proxy: "http://proxy.corp.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.corp.local:8080"
)
$vbLabelText   $csharpLabel

重要：在Proxy属性。 不要在那里寻找它。 代理严格是FromHtml重载的方法参数。

如何与企业代理进行身份验证？

大多数企业代理需要凭证。 您可以使用http(s)://username:password@host:port格式将它们直接嵌入代理URL中:

:path=/static-assets/pdf/content-code-examples/how-to/proxy-5.cs
using IronPdf;

var renderer = new ChromePdfRenderer();

string proxyWithAuth = "http://svc-account:P%40ssw0rd%21@proxy.corp.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.corp.local:8080"

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

在密码中URL-encode特殊字符。如果您的密码包含/或其他保留的URI字符，它们必须经过百分比编码。 常见编码：

字符 编码后
@ %40
# %23
: %3A
/ %2F
! %21
% %25

使用Uri.EscapeDataString()以编程方式编码密码：

string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.local:8080";
string rawPassword = "P@ssw0rd!";
string encoded = Uri.EscapeDataString(rawPassword); // "P%40ssw0rd%21"
string proxy = $"http://svc-account:{encoded}@proxy.corp.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.corp.local:8080"
$vbLabelText   $csharpLabel

不要将代理认证与网页认证混淆。 NetworkPassword属性验证的是正在渲染的网页（与网站使用NTLM/协商），而不是代理服务器。 对于代理身份验证，凭证如上所示放在代理URL字符串中。

Icon Quote related to 如何与企业代理进行身份验证？

我最喜欢的这种库是 IronPDF。它允许快速高效地操作 PDF 文件。它还具有许多有价值的功能，比如导出为 PDF/A 格式和数字签名 PDF 文档。

Milan Jovanovic related to 如何与企业代理进行身份验证？

Milan Jovanovic

微软MVP

查看案例研究
Icon Quote related to 如何与企业代理进行身份验证？

IronOCR 意味着我们每年可以节省 $40,000 的人工处理成本，同时提高生产力，并释放资源用于高影响任务。我强烈推荐它。

Brent Matzelle related to 如何与企业代理进行身份验证？

Brent Matzelle

首席技术官，OPYN

查看案例研究
Icon Quote related to 如何与企业代理进行身份验证？

Iron Suite 在我们的运营中起着至关重要的作用。这些工具提高了业务各方面的效率，包括创建平面图和改善库存管理。

David Jones related to 如何与企业代理进行身份验证？

David Jones

首席软件工程师，Agorus Build

查看案例研究

如何通过代理渲染URL？

RenderUrlToPdf不接受代理参数。 这是一个故意的API设计选择——NavigateUrl导航Chromium到一个URL，并且该导航的代理配置与HTML渲染期间的资源加载处理方式不同。

建议的解决方案：使用配置了RenderHtmlAsPdf（以便引用的资产——图像、CSS、字体——也通过代理路由）。

:path=/static-assets/pdf/content-code-examples/how-to/proxy-7.cs
using IronPdf;
using System.Net;
using System.Net.Http;

// Step 1: Configure HttpClient with the corporate proxy
var proxy = new WebProxy("http://proxy.corp.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.corp/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.corp.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.corp.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.corp/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.corp.local:8080"
    )
    pdf.SaveAs("quarterly-report.pdf")
End Using
$vbLabelText   $csharpLabel

参数<link href="/css/styles.css">）可以正确解析。 参数proxy确保这些资产请求在渲染期间通过代理路由。

这种模式也适用于经过认证的页面——在获取之前使用适当的cookie或头配置HttpClient，然后将经过认证的HTML传递给IronPDF。 HTTP请求头指南涵盖了对身份验证请求的头配置。

如果页面依赖JavaScript进行渲染（SPA、React仪表板、Angular应用程序），获取的HTML将仅包含初始框架——HttpClient获取期间不会执行客户端渲染。 对于这些情况，您有两个选择：设置系统级RenderHtmlAsPdf()。

如何在Docker容器中配置代理？

在容器化环境中，您可能更喜欢系统级代理配置而不是每个方法的参数。 IronPDF的Chromium引擎遵循Linux容器用于出站流量路由的标准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.corp.local:8080
ENV HTTPS_PROXY=http://proxy.corp.local:8080
ENV NO_PROXY=localhost,127.0.0.1,.internal.corp

# 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会自动获取系统级配置：

:path=/static-assets/pdf/content-code-examples/how-to/proxy-9.cs
// 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)
$vbLabelText   $csharpLabel

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
YAML

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'
YAML

Jenkins（声明性管道）：

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

在这三种情况下，Chromium会自动读取环境变量。 如果您更喜欢显式控制，请从环境中读取代理URL，并将其作为方法参数传递：

:path=/static-assets/pdf/content-code-examples/how-to/proxy-13.cs
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)
$vbLabelText   $csharpLabel

如何排除代理问题？

超时错误：企业代理增加了延迟。 将渲染超时从默认为60秒增加：

renderer.RenderingOptions.Timeout = 120; // seconds
renderer.RenderingOptions.Timeout = 120; // seconds
renderer.RenderingOptions.Timeout = 120 ' seconds
$vbLabelText   $csharpLabel

这是RenderTimeout属性——它控制Chromium为页面加载和资源获取的等待时间。 如果您的代理为每个请求增加5–10秒的延迟，并且页面加载了20多个外部资源，则60秒可能不够。

SSL拦截（中间人代理）：许多企业代理通过公司根CA证书解密和重新加密HTTPS流量。 Chromium拒绝这些连接，因为它默认不信任公司CA。 两种解决方案：

  1. 在容器或主机的受信根存储中安装公司CA证书。 在Linux上：将update-ca-certificates。
  2. 仅限于开发环境，您可以禁用证书验证——但永远不要在生产环境中这样做。 更安全的方法总是安装正确的证书。

NTLM认证：内联user:pass@host格式支持基本和摘要代理认证。 NTLM（在Windows为中心的企业中很常见）通过代理URL字符串不受支持。 解决方法是在主机上或作为sidecar容器运行一个本地NTLM到基本转发代理，如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.corp.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.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP
var proxy = new WebProxy("http://proxy.corp.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.Content.ReadAsStringAsync());
// Should return the proxy's external IP, not your machine's IP
Imports System
Imports System.Net
Imports System.Net.Http

Dim proxy As New WebProxy("http://proxy.corp.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
$vbLabelText   $csharpLabel

如果这成功但IronPDF仍然失败，问题很可能是SSL拦截或您的代理和Chromium的CONNECT隧道之间的协议不匹配。 检查代理是否支持HTTP CONNECT用于HTTPS资源——某些代理需要显式配置以允许隧道。

下一步

IronPDF中的代理支持是一种RenderHtmlAsPdf()的方法参数——传递代理字符串，Chromium引擎将所有HTTP流量通过它路由。 对于HTTPS_PROXY环境变量让您无需代码更改即可进行基础设施级控制。

浏览登录和身份验证指导以获取网页身份验证（与代理身份验证不同）的信息，HTTP请求头指南以获取自定义头，以及渲染选项参考以进行超时和性能优化。

查看许可证选项从$999开始。 ChromePdfRendererAPI参考记录了每个方法的重载，ChromePdfRenderOptions参考涵盖了所有可配置的属性。 RenderUrlAsPdf() ProxyAddress ChromePdfRenderOptions RenderHtmlAsPdf StaticRenderHtmlAsPdf RenderUrlAsPdf HttpClient WebProxy RenderHtmlAsPdf() ```yaml

spec: containers:

  • name: pdf-generator image: myregistry/pdf-service:latest env:

常见问题解答

如何在C#中配置用于PDF渲染的代理服务器？

要在C#中配置用于PDF渲染的代理服务器，可以在调用IronPDF中的RenderHtmlAsPdf方法时使用代理参数。这允许您指定用于访问网络资源的代理设置。

使用IronPDF的一代理的目的是什么？

在IronPDF中使用代理有助于在渲染PDF时管理网络请求，尤其是在受到互联网访问限制的环境中，如在防火墙或企业网络内。

IronPDF可以处理认证代理吗？

是的，IronPDF可以处理认证代理。您需要在C#代码中提供必要的认证凭证及代理设置。

在Docker容器中可以使用IronPDF和代理吗？

是的，可以配置IronPDF在Docker容器中使用代理。确保正确设置Docker环境变量以传递代理设置。

如何排查IronPDF中代理出现的问题？

要排查IronPDF中的代理问题，检查您的代理设置，确保认证信息正确，并验证网络的可访问性。查看日志中的任何错误信息也可以帮助识别问题。

可以在具有代理配置的CI/CD管道中使用IronPDF吗？

是的，可以在具有代理配置的CI/CD管道中集成IronPDF。确保您的构建环境已设置好，以在PDF渲染过程中传递必要的代理设置。

在企业环境中使用IronPDF代理的好处是什么？

在企业环境中使用IronPDF代理可以增强安全性、控制互联网访问和管理带宽使用，使遵守组织的IT政策变得更容易。

Darrius Serrant
Darrius Serrant
  立即与工程团队聊天
全栈软件工程师（WebOps）

Darrius Serrant 拥有迈阿密大学的计算机科学学士学位，目前在 Iron Software 担任全栈 WebOps 市场工程师。从小就被编码吸引，他认为计算机既神秘又易于接触，使其成为创意和问题解决的理想媒介。

在 Iron Software，Darrius 喜欢创造新事物，并简化复杂概念以使其更易理解。作为我们常驻的开发者之一，他还自愿教授学生，与下一代分享他的专业知识。

对于 Darrius 来说，他的工作令人满意，因为它被重视并产生真正的影响。

准备开始了吗？
Nuget 下载 20,088,359 | 版本: 2026.7 刚刚发布
Still Scrolling Icon

还在滚动吗？

想快速获得证据？ PM > Install-Package IronPdf
运行示例看着你的HTML代码变成PDF文件。