如何在 C# 的 HttpClient 中使用代理：實作模式與排錯方法

上週我花了超多時間盯著一個 407 Proxy Authentication Required 的回應，還一度以為是代理服務商出問題。結果最後才發現，是我把憑證設在錯的屬性上——只要兩行就能修好，我卻花了兩個小時才找到。如果你也有類似經驗，那這篇指南就是寫給你的。

在 C# 裡用 HttpClient 設定代理，看起來很簡單，實務上卻常常踩雷：socket 耗盡、SOCKS5 版本不相容、憑證設錯位置……這些問題真的會吃掉不少時間。

我在 Thunderbit 一直有接觸網頁爬取與資料擷取工具，也反覆看過這些錯誤在我們自己的工程討論、以及我們關注的開發者社群中一再出現。這篇教學會把完整流程一次講清楚：設定、驗證、代理輪換、協定選擇，以及一個我真心希望在剛入門時就存在的排錯表。

難度： 初學到中階
預估時間： 約 15 分鐘可跟著做，若要落地到生產環境的輪換模式則更久
你需要準備： .NET 6+ SDK（支援 SOCKS5 與現代 handler 功能；.NET Framework 4.x 也可做基本 HTTP 代理範例）、一個程式編輯器，以及至少一個可測試的代理端點

什麼是 HttpClient？為什麼它需要代理？

HttpClient 是 .NET 內建的 System.Net.Http 類別，用來發送 HTTP 請求並接收回應。它支援 async/await、自訂標頭、取消權杖，以及以 handler 為基礎的設定方式。Microsoft 將它描述為一個「透過 URI 所識別的資源發送 HTTP 請求並接收 HTTP 回應的類別」來源。

代理伺服器則是介於應用程式與目標網站之間的中介。當流量經過代理轉送時，目標網站看到的是代理的 IP，而不是你的真實 IP。

HttpClient 本身沒有 Proxy 屬性。代理路由是設定在底層 handler 上——不論是 HttpClientHandler 還是 SocketsHttpHandler——它們都接受一個 WebProxy 實例。可以把流程理解成這樣：

[你的 C# 應用程式] → [HttpClient + Handler] → [代理伺服器] → [目標網站]

所以「在運行中的 HttpClient 上直接改代理」不是單純屬性賦值，而是一個設計問題。這部分在輪換章節會再詳細說明。

試用 Thunderbit，讓資料擷取更省事

為什麼要在 C# 的 HttpClient 中使用代理

開發者讓 HttpClient 流量走代理，通常是為了以下幾個很常見的理由，而不同情境也會對應不同的代理類型。

• 避免 IP 封鎖與速率限制： 大規模網頁爬取、名單開發或價格監控時尤其重要。單一 IP 狂打網站，很快就會被擋。
• 繞過地區限制： 透過特定國家的代理存取區域限定的 API 或內容。
• 隱藏來源 IP： 在敏感資料蒐集或競品研究時，多一層隱私保護。
• 企業或合規需求： 很多企業要求所有對外流量都先經過中央閘道，以便記錄與治理。
• 測試與 QA： 不用真的把基礎設施部署到那些地區，也能模擬不同位置或網路條件的請求。

使用情境	常見代理選擇	適合的原因
大規模網頁爬取	輪換型住宅代理	IP 多樣性高，較不易被反機器人系統辨識
電商價格監控	住宅代理或地區定向資料中心代理	可檢查不同地區的價格與庫存
透過固定閘道存取 API	資料中心代理或企業代理	IP 可預測、可做白名單，成本較低
企業合規	系統代理、PAC 代理、公司認證代理	集中式記錄與對外流量控管
QA 與在地化測試	指定國家代理池	模擬目標地區的真實使用者存取

代理使用通常也會隨著規模成長而演進。你一開始可能只會先用一個固定代理確認路由是否正常；到了生產環境的爬蟲，通常會改成代理池，依目標網域、地理位置或失敗率來分配請求。成熟團隊往往會進一步採用代管代理閘道，讓輪換、重試與 session 黏著都在單一端點後面完成。

但代理輪換不是萬靈丹。如果目標網站會封鎖可疑行為，單純換 IP 只是在請求頻率、標頭、cookie 和 TLS 指紋也一起處理好的前提下才真正有效。

哪些 .NET 版本支援哪些功能：快速相容性對照

把部落格上的代理範例直接貼到錯的目標框架，是很多人默默失敗的主因之一。最大的分界點是 .NET Framework 4.x 與現代 .NET（.NET 6+）。以下是各版本的支援情況：

功能	.NET Framework 4.x	.NET 6	.NET 7	.NET 8–9
WebProxy + HttpClientHandler	有	有	有	有
透過 WebProxy("socks5://...") 使用 SOCKS5	無	有（自 .NET 6 起支援）	有	有
SocketsHttpHandler（預設 handler）	無	有	有	有
HttpClient.DefaultProxy 靜態屬性	無	有	有	有
PooledConnectionLifetime	無	有	有	有

如果你的目標是 .NET Framework 4.x，就請使用 HttpClientHandler 搭配 WebProxy 來做 HTTP/HTTPS 代理。SOCKS5 與較新的連線池控制功能則需要 .NET 6 以上。

還有一個很容易忽略的行為：在現代 .NET 裡，HttpClient.DefaultProxy 是靜態屬性。如果它在共用的啟動程式碼中被設定，或是繼承了環境變數（像是 HTTPS_PROXY 或 HTTP_PROXY），每個 HttpClient 實例都會吃到這個設定，除非你明確在 handler 上覆寫。在容器化部署裡，這常常會造成「為什麼我的 client 用了我根本沒設定過的代理？」這種困惑。

步驟 1：建立新的 C# Console 專案

打開終端機，先建立一個新專案：

dotnet new console -n ProxyHttpClientDemo
cd ProxyHttpClientDemo

再用 dotnet --version 確認你的 SDK 版本。本指南的範例以 .NET 6+ 為主，能完整涵蓋相關功能。如果你需要最新的 LTS SDK，可以到 Microsoft 下載頁面 取得。

接著打開編輯器裡的 Program.cs，重點都會在那裡完成。

步驟 2：先做一個不使用代理的基準 HTTP 請求

在設定代理前，先確認你目前真實的對外 IP。這樣等代理啟用後，就能驗證 IP 是否真的有變。

using System.Net.Http;

using var client = new HttpClient();
var ip = await client.GetStringAsync("https://api.ipify.org/");
Console.WriteLine($"Direct IP: {ip}");

執行後，你應該會看到目前的公開 IP，例如：

Direct IP: 203.0.113.10

先把這個值記住。下一步完成後，它應該會不同。

步驟 3：用 HttpClientHandler 設定 WebProxy

標準做法由三個物件組成：WebProxy、handler，以及 client。

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

var proxy = new WebProxy("http://proxy.example.com:8080")
{
    BypassProxyOnLocal = false
};

var handler = new HttpClientHandler
{
    Proxy = proxy,
    UseProxy = true,
    UseDefaultCredentials = false
};

using var client = new HttpClient(handler);
var ip = await client.GetStringAsync("https://api.ipify.org/");
Console.WriteLine($"Proxy IP: {ip}");

請把 proxy.example.com:8080 換成你的實際代理端點。如果一切設定正確，輸出的 IP 應該會變成代理出口 IP，而不是你的真實 IP。

這幾個屬性要特別理解：

• Proxy — handler 用來路由流量的 IWebProxy 實例。
• UseProxy = true — 告訴 handler 確實要使用你設定的代理。（看起來很基本，但忘記設它真的很常讓人卡很久。）
• BypassProxyOnLocal = false — 避免 handler 對看起來像「本機」的目的地略過代理。
• UseDefaultCredentials — 控制 handler 是否傳送 Windows 預設認證。這和代理帳密不是同一件事。

步驟 4：使用 NetworkCredential 加上代理驗證

大部分付費代理服務都需要帳密。正確做法是把認證設在 WebProxy 物件本身：

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

var proxy = new WebProxy("http://proxy.example.com:8080")
{
    Credentials = new NetworkCredential("proxy-user", "proxy-password")
};

var handler = new HttpClientHandler
{
    Proxy = proxy,
    UseProxy = true
};

using var client = new HttpClient(handler);
var ip = await client.GetStringAsync("https://api.ipify.org/");
Console.WriteLine($"Authenticated proxy IP: {ip}");

很多服務商會給你像 http://username:password@host:port 這樣的格式。對 .NET 程式來說，建議使用 NetworkCredential 而不是把帳密直接塞進 URI。這樣可以避免密碼裡有特殊字元時的跳脫問題，也能更清楚地區分 URI 與認證資訊。

我會在下一節特別說明最常見的驗證錯誤，以及它為什麼會導致 407。

步驟 5：讀取或輸出回應資料

如果不只是快速檢查 IP，而是要處理正式資料，回應就要正確處理：

using var response = await client.GetAsync("https://example.com/api/products");

if (!response.IsSuccessStatusCode)
{
    Console.WriteLine($"Request failed: {(int)response.StatusCode} {response.ReasonPhrase}");
    return;
}

var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

如果是爬取流程，代理請求只是傳輸層的一部分。你後面還需要解析、標準化、去重、重試，以及匯出到 Excel、Google Sheets、資料庫或其他目的地。像 Thunderbit 這類工具可以幫你自動完成擷取與匯出步驟——它的 Chrome 擴充功能 可以處理結構化資料擷取，並免費匯出到 Google Sheets、Excel、Airtable 或 Notion，而不需要你自己寫解析程式。

將爬取的資料匯出到 Excel、Sheets、Airtable 或 Notion Get Started Free

代理認證 vs. 伺服器認證：導致 407 的常見錯誤

我在 Stack Overflow、Microsoft Q&A，甚至——老實說——自己的程式裡都看過這個錯誤。

這個區分很簡單，但真的很容易搞混：

• 代理認證：用來向代理伺服器驗證你的身分。
• 伺服器認證：用來向目的地／目標伺服器驗證你的身分。

在 HttpClientHandler 裡，這兩者放在不同屬性上。把憑證設錯位置，是 出現 407 Proxy Authentication Required 的第一大原因。

// ❌ 錯誤：這是設定目的伺服器的憑證，不是代理
handler.Credentials = new NetworkCredential("user", "pass");

// ✅ 正確：把憑證設在代理物件本身
handler.Proxy = new WebProxy("http://proxy:8080")
{
    Credentials = new NetworkCredential("user", "pass")
};

HttpClientHandler.Credentials 是給目的地伺服器用的。WebProxy.Credentials 才是給代理用的。如果代理回傳 407，代表你的憑證應該設在代理上。

還有一個坑：HttpClientHandler.PreAuthenticate 是控制對目標伺服器的預先驗證，不是用來控制 Proxy-Authorization 標頭的。這個屬性 不是解 407 的方法。

如何在 C# 的 HttpClient 中輪換代理

這是論壇裡很常被問到的問題。答案一開始可能讓人失望：你不能直接在已存在的 HttpClient 實例上改代理。 代理是綁在 handler 上的，而 handler 是在建構時設定的。HttpClient 本身沒有可變的 Proxy 屬性。

最直覺但不太對的做法是：每個請求都 new HttpClient(new HttpClientHandler { Proxy = ... })。問題是，Microsoft 已明確警告不要每個請求都建立並釋放 client，因為連線關閉後埠口不會立刻釋放，容易造成 TCP port 耗盡。

以下這三種做法，才是真正在生產環境可行的模式。

方法 1：透過 IHttpClientFactory 使用命名 client

如果你的代理清單在啟動時就已經知道，命名 client 是最簡潔的選擇。每個命名 client 都有自己的 handler 設定，應用程式可以在執行時依名稱取得對應 client。

builder.Services.AddHttpClient("proxy-us")
    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
    {
        Proxy = new WebProxy("http://us-proxy.example.com:8080")
        {
            Credentials = new NetworkCredential("user", "pass")
        },
        UseProxy = true
    });

builder.Services.AddHttpClient("proxy-eu")
    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
    {
        Proxy = new WebProxy("http://eu-proxy.example.com:8080")
        {
            Credentials = new NetworkCredential("user", "pass")
        },
        UseProxy = true
    });

// 在請求時：
var client = httpClientFactory.CreateClient("proxy-us");

factory 會幫你管理 handler 的生命週期，也避免了每個請求都建立 client 的反模式。

方法 2：SocketsHttpHandler + PooledConnectionLifetime（.NET 6+）

如果你有一個長時間運作的 client，且背後接的是會在新連線時更換出口 IP 的代理閘道，可以用 PooledConnectionLifetime 讓連線在指定時間後重新建立。

var handler = new SocketsHttpHandler
{
    Proxy = new WebProxy("http://rotating-gateway.example.com:8080")
    {
        Credentials = new NetworkCredential("user", "pass")
    },
    UseProxy = true,
    PooledConnectionLifetime = TimeSpan.FromMinutes(5)
};

using var client = new HttpClient(handler);

這不代表 Proxy 物件會在每個請求中神奇地自動變更。它最適合的是：代理閘道會在每次新 TCP 連線時分配不同的出口 IP，或是 DNS 型代理池會隨時間將主機名稱解析到不同端點。

方法 3：用自訂 DelegatingHandler 做進階代理選擇

當代理選擇取決於請求 URL、payload 或執行時上下文時，可以自訂 routing handler，檢查每個請求後，將它轉送到對應的內層 handler pipeline。

public sealed class ProxyRoutingHandler : DelegatingHandler
{
    private readonly IReadOnlyDictionary<string, HttpMessageInvoker> _clients;

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        var key = SelectProxyKey(request);
        return _clients[key].SendAsync(request, cancellationToken);
    }
}

這是進階設計。執行緒安全、釋放資源、handler 重用、重試行為與記錄都得自己負責。我只會在前兩種方法真的不適用時才推薦這樣做。

三種做法比較

做法	複雜度	.NET 版本	執行緒安全	額外負擔
命名 client（IHttpClientFactory）	低	.NET Core 2.1+	高（設定不可變）	低
SocketsHttpHandler + PooledConnectionLifetime	中	.NET 6+	高	低
自訂 DelegatingHandler	高	任意	視實作而定	中

對大多數團隊來說，命名 client 是最好的起點。若是穩定的輪換代理閘道，可以進一步用 PooledConnectionLifetime；只有在代理選擇需要依請求層級中繼資料判斷時，才考慮自訂路由。

選對代理協定：HTTP、HTTPS 與 SOCKS5

不是每種代理都說同一種語言，用錯協定通常只會得到讓人困惑的錯誤訊息。

HTTP 代理： 能理解 HTTP 請求。對純 HTTP 目標，它可以直接轉送；對 HTTPS 目標，客戶端會先送出 CONNECT 建立隧道，再透過該隧道與目的地進行 TLS 協商。這是最常見的模型。

HTTPS 終止型代理： 代理會提供自己的 TLS 憑證，然後再把上游流量重新加密。這常見於企業檢查系統與某些代管爬取 API。如果客戶端不信任代理的憑證鏈，就會出現憑證驗證錯誤。

SOCKS5 代理： 是傳輸層的 TCP 隧道，適用於任何 TCP 流量，不限於 HTTP。住宅代理供應商很常使用。它已被 .NET 6+ 原生支援。

SOCKS5 範例：

var handler = new SocketsHttpHandler
{
    Proxy = new WebProxy("socks5://proxy.example.com:1080")
    {
        Credentials = new NetworkCredential("proxy-user", "proxy-password")
    },
    UseProxy = true
};

using var client = new HttpClient(handler);
var ip = await client.GetStringAsync("https://api.ipify.org/");
Console.WriteLine(ip);

關於 SSL 憑證驗證的補充說明

使用 HTTPS 終止型代理時，你可能會看到 RemoteCertificateNameMismatch 錯誤。可以用 ServerCertificateCustomValidationCallback 自訂驗證：

var handler = new HttpClientHandler
{
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
};

請只在本機開發環境，或是使用你完全信任且已獲批准的 TLS 攔截代理時才這樣做。 如果不加判斷地直接回傳 true，等於關掉重要的安全檢查，會讓你暴露在中間人攻擊風險下。在正式環境中，若是標準 CONNECT 或 SOCKS 代理，請維持 SSL 驗證開啟。

C# HttpClient 常見代理錯誤排查

這張表會把外在症狀對應到最可能的根因，以及你應該先嘗試的修正方式。我建議把這段收藏起來——它涵蓋了 Stack Overflow 討論 和開發者論壇裡最常見的錯誤。

錯誤 / 症狀	常見原因	修正方式
407 Proxy Authentication Required	憑證設在 handler.Credentials，而不是 handler.Proxy.Credentials；使用了錯誤的使用者名稱格式；URL 內嵌密碼含特殊字元	使用 WebProxy.Credentials = new NetworkCredential(...)；避免把帳密嵌進 URI；確認供應商要求的使用者名稱格式
TaskCanceledException / Timeout	代理端點慢、無法連線、過載，或被防火牆擋住；預設 100 秒 timeout 太短	先用 curl 測試代理；確認端點可用後再提高 HttpClient.Timeout；加上重試與代理健康檢查
SocketException / socket 耗盡	每個請求都建立並釋放 HttpClient 或 handler	改用 IHttpClientFactory、單例 client，或搭配 pooling 控制 的 SocketsHttpHandler
SSL RemoteCertificateNameMismatch	公司或代管代理做了 HTTPS 攔截	視情況安裝／信任代理 CA；只在受控開發或核准的 MITM 場景中使用自訂驗證
302 Redirect loop	企業代理 / VPN 的登入頁或白名單封鎖導致反覆重新導向	測試直接連線；檢查 Location 標頭；確認代理白名單與驗證入口
HttpRequestException / SOCKS URL 無法連線	在 .NET Framework 或舊版 .NET 上執行 SOCKS 程式；協定或埠號寫錯	使用 .NET 6+ 原生 SOCKS 支援；確認格式為 socks5://host:port；依供應商文件測試
看起來代理沒生效	UseProxy = false；目標被視為 local 而略過；NO_PROXY 環境變數；handler 設定與預期不同	設定 UseProxy = true；檢查 HttpClient.DefaultProxy；清除或覆寫環境變數；設定 BypassProxyOnLocal = false

快速排查流程

1. 請求有成功嗎？ → 有：比對 api.ipify.org 的輸出是否與預期代理 IP 一致。
2. 沒有，但有 HTTP 狀態碼？ → 407：修正代理憑證。403/429：目標封鎖或限流代理。3xx 迴圈：代理／企業閘道可能在重導向。
3. 沒有狀態碼，只有例外？ → Timeout：檢查代理可達性。Socket／憑證例外：檢查連線池、協定、TLS 與 .NET 版本。

你也可以先用下面幾個命令，在 .NET 之外驗證代理本身是否正常：

curl -x http://user:pass@proxy.example.com:8080 https://api.ipify.org/
curl --socks5 user:pass@proxy.example.com:1080 https://api.ipify.org/

如果 curl 可以，但你的 C# 程式不行，通常差異會出在驗證方式、TLS 信任存放區、環境變數，或帳密跳脫處理。先讓 curl 的代理 URL、協定與驗證方式完全一致，再把憑證移到 NetworkCredential。

什麼時候可以不管代理管理：無程式碼替代方案

有相當一部分搜尋「HttpClient proxy C#」的人，其實不是想學代理理論，而是想讓爬蟲穩定跑下去。老實說，什麼時候該自己寫 C# 代理程式、什麼時候不該，這件事值得坦白講清楚。

適合自己用 C# + 代理輪換開發爬蟲的情況：

• 你需要完全掌控請求邏輯、cookie、標頭、重試與解析
• 爬蟲要整合到既有的 .NET 程式碼庫或內部服務
• 合規或資安需求要求你端到端自行掌控基礎設施

適合使用像 Thunderbit 這種無程式碼工具的情況：

• 你的目標是從網站擷取結構化資料，而不是處理 HTTP 基礎設施
• 你不想維護代理池、處理 CAPTCHA 或排查 socket 耗盡
• 團隊需要把資料直接送進 Excel、Google Sheets、Airtable 或 Notion，而不想寫解析程式

Thunderbit 的 Chrome 擴充功能透過雲端爬取模式，能自動處理代理輪換與反機器人措施。它的 API 也讓開發者可以用 JSON schema 定義資料結構，直接取得結構化結果，而完全不用自己管理 HttpClient 或 WebProxy。對做 價格比較爬取 或 名單擷取 的團隊來說，省下的設定時間非常可觀。

情境	自訂 C# + 代理	Thunderbit
完整控制請求邏輯	有	無（僅 API 層控制）
需要自己管理代理	有	無（自動處理）
反機器人 / CAPTCHA 處理	手動或第三方	內建
設定時間	數小時到數天	幾分鐘
最適合	既有 .NET 程式碼庫、自訂流程	快速資料擷取、非技術團隊、試算表匯出

這不是在說「永遠不要用 HttpClient」。如果你正在打造正式的 .NET 服務，你當然應該理解代理設定。但如果你只是為了一個一次性的資料蒐集任務，花好幾個小時在 407 錯誤上打轉，那其實有更簡單的做法——選它們完全沒什麼好丟臉的。你可以看看 Thunderbit 的價格方案，或到 YouTube 頻道 看操作示範。

重點整理

核心模式其實都一樣：WebProxy → handler → HttpClient。後面所有內容，都是在處理生產環境裡最常出現的操作失誤。

• 憑證要設在代理上，不是 handler 上。 407 那一段的對照範例，是最重要的一條。
• 不要每個請求或每個代理都建立新的 HttpClient。 善用 IHttpClientFactory 的命名 client、SocketsHttpHandler 搭配 PooledConnectionLifetime，或進階的自訂路由 handler。
• 在複製 SOCKS5 或 SocketsHttpHandler 程式碼前，先確認 .NET 版本。 上面的相容性表可以幫你避免默默失敗。
• 先在 .NET 之外測試代理。 一條簡單的 curl 指令，就能排除很多問題。
• 如果你只是想穩定拿到結構化資料，不想被代理問題綁住， 像 Thunderbit 這種工具可以把傳輸層處理好，讓你專心處理資料本身。

下次遇到 407 或 TaskCanceledException 時，先從上面的排錯表開始看。

常見問題

我可以直接修改既有 HttpClient 實例的代理嗎？

不行。代理是綁在 handler 上，而 handler 是在建構時設定的。HttpClient 沒有可變的 Proxy 屬性。若要使用不同代理，請建立不同的 handler 與 client，並用 IHttpClientFactory 的命名 client 或預先設定好的 client 池來管理。

HttpClient 預設會使用系統代理嗎？

會。在現代 .NET 中，如果你沒有明確設定 handler，HttpClient 會沿用系統預設代理設定，包括透過 HttpClient.DefaultProxy 讀取 HTTPS_PROXY、HTTP_PROXY 這類環境變數。若想關閉，請在 handler 上明確設 UseProxy = false。

我該怎麼在 C# 的 HttpClient 使用 SOCKS5 代理？

請搭配 SocketsHttpHandler 使用 new WebProxy("socks5://host:port")。原生 SOCKS 代理支援需要 .NET 6 或更新版本。在 .NET Framework 4.x 上，SOCKS5 沒有原生支援，你需要第三方函式庫。

為什麼我一直拿到 407 Proxy Authentication Required？

最常見原因是：你把憑證設在 handler.Credentials（這是給目的伺服器用的），而不是 handler.Proxy.Credentials（這才是給代理用的）。請參考上面的「代理認證 vs. 伺服器認證」章節。

使用代理時，關閉 SSL 憑證驗證安全嗎？

只有在本機開發，或你完全信任代理供應商的情況下才可考慮（例如某些 HTTPS 代理模式下的代管爬取 API）。正式環境若使用標準 CONNECT 或 SOCKS 代理，請保留 SSL 驗證，避免中間人攻擊。

試用 Thunderbit，輕鬆完成網頁爬取 Get Started Free

延伸閱讀

• 最佳自動化網頁爬蟲工具
• 如何建立網頁爬蟲
• 最佳網頁爬蟲服務
• 網頁爬蟲最適合的程式語言
• 避免被封鎖的網頁爬取方法