最後更新：2026 年 10 月 30 日。

如何在 Playwright 中使用住宅代理

如果你已經有住宅代理，將它接入 Playwright 通常只需要設定幾個參數：代理伺服器地址、連接埠，以及認證資訊。真正容易讓人困惑的地方，往往是如何判斷代理是否正常運作。瀏覽器能夠啟動，並不代表代理設定一定正確；即使代理已經連通，目標網站也仍有可能返回錯誤頁面或驗證頁面。

本文將以 KindProxy 控制面板中的 HTTP/HTTPS 動態住宅代理設定為例，帶你完成一套 Python 實操流程。同時也會提供一份簡短的 Node.js 範例，並分別說明如何檢查代理連接、出口 IP、地理位置以及目標網頁的回應。

1. 安裝 Playwright

首先建立 Python 虛擬環境、安裝 Playwright，並下載 Chromium：

python -m venv .venv
source .venv/bin/activate
python -m pip install playwright
python -m playwright install chromium
sudo .venv/bin/playwright install-deps chromium

最後一條命令用於安裝 Chromium 在 Linux 上運行所需的系統依賴，需要使用 sudo 權限。如果缺少這些依賴，Chromium 啟動時可能會報錯並退出，例如提示找不到 libatk-1.0.so.0 等系統庫。其他 Linux 發行版的安裝方式，可以參考 Playwright 的 Linux 瀏覽器依賴安裝說明。

如果你使用的是 Windows PowerShell，可以透過下面的命令建立並啟用虛擬環境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install playwright
python -m playwright install chromium

更多安裝方式請參考 Playwright Python 入門指南。

2. 在 KindProxy 獲取代理設定

登入 KindProxy 流量代理控制面板，選擇 HTTP/HTTPS 協議，根據需要設定代理地區和工作階段類型，然後複製系統產生的代理參數。

KindProxy 流量代理設定介面，展示認證方式、地區定位、協議、主機類型、連接埠和工作階段選項。帳號密碼已隱藏。

上圖展示的是本文使用的 HTTP/HTTPS 代理設定，帳號密碼已做隱藏處理。

下面的範例使用控制面板中對應的設定：

設定項	本文範例	在 Playwright 中的填寫方式
協議	HTTP/HTTPS	`server` 地址使用控制面板提供的 `http://` 協議前綴。
主機類型	DNS 域名	使用系統提供的閘道主機名稱。
主機和連接埠	`gw.kindproxy.com:12000`	將 `server` 設定為 `http://gw.kindproxy.com:12000`。
認證方式	用戶名/密碼	將產生的用戶名和密碼分別傳入對應欄位。
工作階段類型	動態 IP	出口 IP 的變化方式取決於你在控制面板中選擇的工作階段選項。
地區	可選國家、州、城市或 ASN	請完整複製系統產生的用戶名，不要自行拼接或修改其中的定位參數。

控制面板產生的用戶名可能已經包含你選擇的地區參數。請直接複製完整用戶名，不要根據介面上顯示的選項自行拼接。如果使用本文的 HTTP 範例，需要採用用戶名和密碼認證。如果你選擇的是 IP 白名單認證，請按照控制面板中對應的說明設定，這屬於另一種認證方式。

Playwright 支援 SOCKS 代理地址格式，但在我們的測試中，Chromium 使用用戶名和密碼認證時，無法連接 KindProxy 的 SOCKS5 端點。因此，本文重點介紹已經驗證過的 HTTP/HTTPS 代理設定。關於 Playwright 支援的代理設定方式，可以查看官方的網絡設定文件。

在選擇地區或工作階段類型之前，你也可以先了解 KindProxy 提供的不同住宅代理套餐。

正在為 Playwright 專案尋找住宅代理？

查看 KindProxy 住宅代理套餐，了解不同流量套餐、可選地區和工作階段類型。你可以先從較小的流量套餐開始，再根據專案需求逐步擴展。

3. 將代理帳號資訊保存在腳本之外

建議透過環境變數設定代理參數。這樣可以避免將帳號密碼直接寫進 Python 檔案，也方便你在開發和生產環境中使用不同的代理設定。

macOS 或 Linux 系統：

export PROXY_SERVER="http://gw.kindproxy.com:12000"
export PROXY_USERNAME="paste-the-generated-username"
export PROXY_PASSWORD="paste-your-proxy-password"

Windows PowerShell：

$env:PROXY_SERVER = "http://gw.kindproxy.com:12000"
$env:PROXY_USERNAME = "paste-the-generated-username"
$env:PROXY_PASSWORD = "paste-your-proxy-password"

請將用戶名和密碼佔位內容替換為你從控制面板複製的真實資訊。不要將真實代理帳號提交到 Git 倉庫，也不要在截圖或客服支援請求中洩露這些資訊。

4. 運行完整的 Python 代理連接檢查

將下面的程式碼儲存為 check_proxy.py：

import asyncio
import os

from playwright.async_api import async_playwright


async def main():
    proxy_server = os.getenv(
        "PROXY_SERVER",
        "http://gw.kindproxy.com:12000",
    )
    proxy_username = os.getenv("PROXY_USERNAME")
    proxy_password = os.getenv("PROXY_PASSWORD")

    if not proxy_username:
        raise ValueError(
            "Please set PROXY_USERNAME environment variable."
        )

    if not proxy_password:
        raise ValueError(
            "Please set PROXY_PASSWORD environment variable."
        )

    proxy = {
        "server": proxy_server,
        "username": proxy_username,
        "password": proxy_password,
    }

    async with async_playwright() as playwright:
        browser = await playwright.chromium.launch(proxy=proxy)
        try:
            page = await browser.new_page()
            response = await page.goto(
                "https://api.ipify.org?format=json",
                wait_until="domcontentloaded",
                timeout=60_000,
            )

            print(
                "HTTP status:",
                response.status if response else "No response",
            )
            print(
                "IP check response:",
                await page.locator("body").inner_text(),
            )
        finally:
            await browser.close()


asyncio.run(main())

在設定好環境變數的同一個終端中運行：

python check_proxy.py

這段腳本會將閘道地址和認證資訊分別傳遞給 Playwright。URL 中的 http:// 前綴表示連接代理伺服器時使用的協議，而腳本實際存取的網頁仍然是 HTTPS。範例中將頁面導航逾時時間設定為 60 秒，為回應較慢的網頁預留更多時間。你可以根據目標網頁和目前網絡狀況自行調整。

更多設定細節可以參考官方的 Playwright 網絡設定文件。

5. 分別檢查出口 IP、地理位置和目標網頁

建議將下面三項檢查分開進行，不要簡單地用一次請求的成功或失敗來判斷整個代理是否正常：

檢查項目	怎樣算正常	能說明什麼
代理連接	IP 查詢頁面能夠正常打開，並返回一個 IP 地址。	Playwright 已經透過目前網絡路徑存取到 IP 查詢頁面。
出口 IP 和地理位置	返回的 IP 與本機直連 IP 不同，查詢到的地區與所選地區基本一致。	代理出口地址及其大致地理位置符合預期。不同 IP 地理位置資料庫的結果可能並不完全一致。
目標網頁	目標網站返回了你的自動化流程所需要的內容。	目標網站接受了本次請求，並返回了可用內容。

Linux 環境測試結果

在 Ubuntu 環境中，我們使用 Playwright 1.52.0 和 Chromium，透過上述 HTTP 代理設定成功打開了 IP 查詢頁面，並收到了 HTTP 200 回應和出口 IP。這說明在該次測試中，用戶名和密碼認證方式可以正常運作。實際結果可能因代理端點、地區和網絡環境而有所不同。

需要注意的是，IP 查詢頁面返回 HTTP 200，並不代表其他網站也一定會正常返回頁面。同樣，IP 查詢結果只能確認目前可見的出口 IP，不能保證所有地理位置資料庫給出的定位都準確。如果你的專案對地區定位有要求，建議參考多個定位來源，或者透過自己能夠控制的網頁進行驗證。

如果代理連接檢查成功，但目標網站仍然顯示 CAPTCHA 驗證碼、拒絕存取提示或空白頁面，應將其視為目標網站的回應結果，而不是直接認定為代理認證失敗。

6. Node.js 版本範例

在 Node.js 中，也可以使用相同的代理參數啟動 Chromium。首先透過 npm install playwright 安裝 Playwright，然後運行 npx playwright install chromium 安裝 Chromium。

const { chromium } = require("playwright");

(async () => {
  const proxyServer =
    process.env.PROXY_SERVER || "http://gw.kindproxy.com:12000";
  const proxyUsername = process.env.PROXY_USERNAME;
  const proxyPassword = process.env.PROXY_PASSWORD;

  if (!proxyUsername) {
    throw new Error("Please set PROXY_USERNAME environment variable.");
  }

  if (!proxyPassword) {
    throw new Error("Please set PROXY_PASSWORD environment variable.");
  }

  const browser = await chromium.launch({
    proxy: {
      server: proxyServer,
      username: proxyUsername,
      password: proxyPassword,
    },
  });

  try {
    const page = await browser.newPage();
    const response = await page.goto("https://api.ipify.org?format=json", {
      waitUntil: "domcontentloaded",
      timeout: 60_000,
    });

    console.log(
      "HTTP status:",
      response ? response.status() : "No response"
    );
    console.log(
      "IP check response:",
      await page.locator("body").innerText()
    );
  } finally {
    await browser.close();
  }
})();

運行腳本前，請像 Python 範例一樣，在環境變數中設定 PROXY_SERVER、PROXY_USERNAME 和 PROXY_PASSWORD。範例將頁面導航逾時時間設定為 60 秒，你可以根據目標網頁的回應速度適當調大或調小。

7. 常見問題及排查方法

問題表現	優先檢查的內容
瀏覽器提示代理認證失敗或 HTTP 407	檢查產生的用戶名和密碼是否完整、準確，並確認控制面板中選擇的是用戶名/密碼認證方式。
瀏覽器啟動或頁面導航逾時	檢查主機名稱、連接埠、協議、網絡存取情況，以及運行 Playwright 的機器是否能夠存取代理端點。
網頁回應較慢，反覆觸發導航逾時	可以嘗試調大頁面導航逾時時間，例如設定為 `timeout=60_000`。同時檢查代理連接、網絡狀況和目標伺服器回應。需要注意，延長逾時時間無法解決代理端點不可達或目標伺服器無回應的問題。
Python 提示缺少 `PROXY_USERNAME` 或 `PROXY_PASSWORD`	請確認已經設定對應的環境變數，並且設定變數和運行腳本使用的是同一個終端或進程環境。
IP 查詢頁面可以打開，但顯示的地區不符合預期	重新檢查國家、州、城市或 ASN 的選擇，以及系統產生的用戶名。不同地理位置資料庫可能會返回不同結果。
IP 查詢正常，但目標網站存取失敗	單獨檢查目標網站的回應。即使代理已經連接成功，目標網站仍可能返回錯誤、驗證頁面或不完整內容。
多頁存取過程中出口 IP 發生變化	檢查目前選擇的工作階段類型是否為動態輪換模式。根據業務需求選擇合適的工作階段模式，並按照控制面板產生的參數進行設定。

不要僅僅為了排查代理連接問題，就急着安裝所謂的隱匿偵測外掛或修改瀏覽器指紋。建議先分別確認代理參數、IP 查詢結果和目標網頁回應。如果你希望在一系列請求中保持相對穩定的出口 IP，可以進一步了解動態代理與工作階段機制的運作方式，再選擇適合自己使用場景的工作階段類型。

常見問題（FAQ）

Playwright Python 可以使用住宅代理嗎？

可以。你可以在 chromium.launch() 中傳入代理伺服器地址、用戶名和密碼，也可以在瀏覽器上下文層級設定代理。請使用代理服務商提供的準確端點和認證資訊。

代理地址一定要以 `http://` 開頭嗎？

請按照代理控制面板提供的協議和地址格式填寫。本文使用的 KindProxy HTTP/HTTPS 設定為 http://gw.kindproxy.com:12000。這裡的協議前綴表示連接代理伺服器時使用的方式，並不影響你透過代理存取 HTTPS 網站。

為什麼目標網站仍然會顯示 CAPTCHA 驗證碼？

代理提供的是網絡連接路徑和出口 IP，目標網站仍會自行決定如何回應請求。如果出現 CAPTCHA 驗證碼或錯誤頁面，說明目標網站沒有為本次請求返回預期內容，但這本身並不能證明代理連接失敗。

準備好在 Playwright 中使用住宅代理了嗎？

現在，你已經了解如何在 Playwright 中設定和測試住宅代理，接下來可以根據專案需求選擇合適的代理套餐。

KindProxy 提供按流量計費的動態住宅代理套餐，支援全球多個地區定位，以及動態輪換和黏性工作階段。你可以根據目前專案所需流量靈活選擇，並隨著自動化或資料擷取任務的增長逐步擴展。

查看 KindProxy 住宅代理套餐

如何在 Playwright 中使用住宅代理#

1. 安裝 Playwright#

2. 在 KindProxy 獲取代理設定#

3. 將代理帳號資訊保存在腳本之外#

4. 運行完整的 Python 代理連接檢查#

5. 分別檢查出口 IP、地理位置和目標網頁#

Linux 環境測試結果#

6. Node.js 版本範例#

7. 常見問題及排查方法#

常見問題（FAQ）#

Playwright Python 可以使用住宅代理嗎？#

代理地址一定要以 http:// 開頭嗎？#

為什麼目標網站仍然會顯示 CAPTCHA 驗證碼？#

延伸閱讀#

準備好在 Playwright 中使用住宅代理了嗎？#