Playwright 代理設定指南：驗證、隔離與故障排查

可靠的 Playwright 代理測試，不只是把代理位址填進設定。網路身分、瀏覽器狀態、逾時、重試及診斷必須一起設計。本指南適用於經授權的在地化檢查、廣告驗證、跨區域品質測試和公開網頁測試，不用於規避存取控制。

先決定代理的作用範圍

Playwright 可在啟動瀏覽器或建立 BrowserContext 時設定代理。若同一瀏覽器程序內的所有情境都共用同一閘道，可使用啟動層級設定；若測試矩陣要分別使用不同區域、憑證或工作階段策略，則應使用情境層級設定。

建議把一個 BrowserContext 視為一個邏輯網路身分。它會隔離 Cookie、快取與儲存空間，適合作為代理工作階段的邊界。建立情境後完成一個業務流程、記錄結果並關閉。購物車、登入或地區偏好尚未完成時，不要任意切換身分。

不要把憑證寫進原始碼

import { chromium } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext({
  proxy: {
    server: process.env.PROXY_SERVER,
    username: process.env.PROXY_USERNAME,
    password: process.env.PROXY_PASSWORD
  }
});

const page = await context.newPage();
await page.goto(process.env.TARGET_URL, {
  waitUntil: 'domcontentloaded',
  timeout: 30000
});

await context.close();
await browser.close();

代理端點及憑證應由祕密管理系統或受保護的環境變數注入。日誌不得輸出完整使用者名稱、密碼或工作階段權杖；只保留不含祕密的設定名稱、區域、產品類型和不可逆的短雜湊。

建立可比較的區域矩陣

把區域、代理產品、預期語系、工作階段策略和並行上限定義成資料。北美、歐洲和亞太應使用相同的授權目標、步驟與斷言，避免把測試程式差異誤判成網路差異。

每次執行至少檢查：出口區域是否正確、頁面語言與貨幣是否符合預期、關鍵資源是否完整、登入或購物車工作階段是否連續，以及最後業務步驟是否成功。HTTP 回應成功不代表結果可用。

使用分層逾時

不要用一個過大的逾時涵蓋所有階段。可先以導覽 30 秒、操作 10 秒、斷言 5 秒為起點，再依實際 p95 延遲調整。較慢的區域路徑可提高導覽預算，但不應讓不存在的元素無限等待。

現代頁面常有持續運作的分析、客服或串流連線，因此不宜機械式等待所有網路活動停止。較可靠的完成條件是 DOM 就緒後，以符合業務目標的元素、資料或狀態進行斷言。

只重試明確的暫時性故障

測試層級重試會在新的工作程序中重建瀏覽器及應用程式狀態，適合少數真實的基礎設施抖動。單次導覽若需重試，應只針對已分類的連線錯誤或有限的伺服器回應，設定次數上限、指數退避與隨機抖動，並記錄每次嘗試。

代理驗證失敗、固定重現的斷言錯誤和政策封鎖不應盲目重試。無限重試會掩蓋根因，也可能超過目標允許的速率。

常見故障排查

• 407 代理驗證失敗：檢查端點格式、憑證範圍、帳戶狀態，以及所選產品是否支援帳密驗證。
• DNS 或連線逾時：比較直連與代理解析，核對閘道主機及連接埠，先以單一區域、低並行重現。
• TLS 錯誤：檢查系統時間、憑證檢查政策和目標主機名稱；不要把關閉憑證驗證當成日常修正。
• 429：降低並行、遵守重試提示，並核對允許的存取速率。
• 403 或挑戰頁：確認授權、條款及預期瀏覽器行為，不得嘗試規避存取控制。
• 頁面可開啟但地區錯誤：同時核對出口區域、瀏覽器語系、時區、語言標頭、Cookie 與帳戶偏好。

讓每次失敗都可解釋

每次執行應記錄測試名稱、時間、區域、代理產品、情境編號、導覽耗時、最終狀態、重試次數和斷言結果。失敗時保存已去除祕密的螢幕截圖與 Playwright Trace。Trace 可協助分辨延遲發生於連線前、重新導向、API 依賴或斷言階段。

核心指標應包含可用結果率、p50/p95 延遲、挑戰率、重試率和每個可用結果的成本。頁面狀態、地區及業務完成全部正確，才算成功。

上線前檢查清單

• 每個邏輯身分使用獨立 BrowserContext。
• 憑證只存放於受保護的執行階段祕密。
• 分別設定導覽、操作及斷言逾時。
• 依區域和目標限制並行。
• 僅對已分類的暫時性故障進行有限重試。
• 對日誌、截圖及 Trace 去除祕密。
• 驗證地區、工作階段連續性及業務完成。
• 只測試已獲授權的目標與資料。

選擇合適的 98IP 工作階段模式

需要切換網路身分的區域測試，可評估 98IP 動態住宅代理；需要較長時間保持身分的流程，可比較 98IP 靜態住宅代理。建議從低並行開始，依可用結果逐步增加規模。

98IP 提供上述代理服務，本文由 98IP 團隊發布。請遵守適用法律、目標條款與速率限制，不得使用自動化規避存取控制。

資料說明

本文技術行為核對了 Playwright 的 Network、BrowserContext、Timeouts 與 Retries 官方文件，查閱日期為 2026 年 8 月 16 日。依 98IP 零外鏈規則，僅以純文字記錄資料名稱及日期。