# 在 Playwright 中配置代理

Source: https://ipvolt.com/zh/guides/playwright-proxy-setup
Markdown: https://ipvolt.com/zh/guides/playwright-proxy-setup.md
Language: zh-CN

[ipvolt 首页](https://ipvolt.com/zh.md) / [指南](https://ipvolt.com/zh/guides.md) / 在 Playwright 中配置代理

集成
审校于: 2026-09-10
阅读约 4 分钟
作者： ipvolt

为 Playwright 浏览器上下文设置带认证的 HTTP 代理，保持测试状态隔离，并将页面导航与子资源请求的故障分开诊断。

## 起点

让受控的浏览器测试经由代理运行，同时让凭据、浏览器状态和导航失败都易于推断。

## 选择测试的范围

Playwright 支持在浏览器启动时或在单个浏览器上下文上设置代理。对于隔离的场景，使用上下文。代理的用户名和密码与 httpCredentials 是分开的，后者用于向网站认证。

在 Node.js 示例项目中，用 npm install playwright 安装 playwright，再用 npx playwright install chromium 安装其 Chromium 浏览器。把 PROXY_URL 设为你真实的 HTTP(S) 网关；https://proxy.example.invalid:8443 只是一个示例。以私密方式注入 PROXY_USERNAME 和 PROXY_PASSWORD。

## 运行一次有限制的导航

保存为 proxy-browser.mjs 并运行 node proxy-browser.mjs。本示例对 HTTP(S) 代理使用用户名/密码认证；不要假设这些认证选项对 SOCKS 网关同样有效。

### proxy-browser.mjs · Playwright Chromium

```javascript
import { chromium } from 'playwright';

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error('Missing environment variable: ' + name);
  return value;
}

const proxy = {
  server: required('PROXY_URL'),
  username: required('PROXY_USERNAME'),
  password: required('PROXY_PASSWORD'),
};
const browser = await chromium.launch({ timeout: 30_000 });
try {
  const context = await browser.newContext({ proxy });
  context.setDefaultTimeout(15_000);
  context.setDefaultNavigationTimeout(30_000);
  const page = await context.newPage();
  const response = await page.goto('https://example.com/', {
    waitUntil: 'domcontentloaded',
  });
  if (!response || !response.ok()) throw new Error('Navigation did not succeed');
  console.log({ status: response.status() });
  await context.close();
} finally {
  await browser.close();
}
```

## 区分页面成功与网络成功

导航响应描述的是主文档，而不是页面发出的每个图片、脚本或 API 请求。对于真实测试，应断言你的工作流所依赖的确切界面或响应。使用你自己控制的页面，并让断言与一个可观察的结果绑定。

单个页面可能产生许多请求。如果你的提供商按请求轮换，在期望整个浏览器流程保持一个稳定出口之前，先确认它如何处理这些连接。Cookie 仍然是浏览器状态；选择粘性代理不会创建或恢复它们。

当页面超时时，先在 curl 中通过同一个网关重复一个小请求。然后检查脱敏后的浏览器请求失败记录以及具体失败的资源。在基础连通性检查期间，避免收集包含真实账户数据的截图或跟踪记录。

## 上线之前

- 为该场景使用全新的上下文。
- 将代理凭据与网站凭据分开。
- 导航之后验证应用真正的成功条件。

## 参考来源与延伸阅读

- [Playwright: HTTP proxy and network events](https://playwright.dev/docs/network#http-proxy)
- [Playwright: browser contexts and timeouts](https://playwright.dev/docs/api/class-browsercontext)
- [Playwright: navigation response behavior](https://playwright.dev/docs/api/class-page#page-goto)

## 相关指南

- [轮换代理与粘性代理：为会话连续性做好规划](https://ipvolt.com/zh/guides/rotating-vs-sticky-proxies.md)
- [在 curl 中使用代理：-x、环境变量、SOCKS5 与认证](https://ipvolt.com/zh/guides/curl-proxy-setup.md)
- [移动代理与住宅代理：建立一套有用的评估方法](https://ipvolt.com/zh/guides/mobile-vs-residential-proxies.md)

## 关于 ipvolt

示例使用通用的代理设置，并附上原始技术文档链接。具体产品的行为请向你的服务商确认。ipvolt 仍在开发中。

[阅读英文原文](https://ipvolt.com/guides/playwright-proxy-setup.md)

## 了解何时开放体验。

ipvolt · 开发中

我们正在为开发者和数据团队打造代理基础设施。加入意向名单，ipvolt 就绪时第一时间收到通知。

开放体验时仅发一封通知邮件，不发送其他邮件。

[申请抢先体验](https://ipvolt.com/zh/guides/playwright-proxy-setup#waitlist-closing)

[隐私政策](https://ipvolt.com/privacy)