---
title: "Playwright 代理设置：认证、轮换与地理定位 | Proxonym"
description: "为 Playwright 配置代理：在启动时或按上下文进行身份验证、每个上下文一个粘性 IP、与地区匹配的语言区域和时区，以及重试。"
url: https://proxonym.com/zh/integrations/playwright
updated: 2026-10-02T03:03:46+00:00
---

# 如何在 Playwright 中使用代理

Playwright 支持在启动时或为每个浏览器上下文设置代理（包括用户名和密码）。本指南涵盖身份认证、按上下文分配粘性 IP、位置匹配以及稳健的页面导航。

- 共 6 步
- 12 分钟完成配置
- 复制即用的代码

开始之前

- Node.js 20 或更高版本；运行 Python 示例则需要 Python 3.10 或更高版本
- Playwright，且至少已安装一个浏览器
- Proxonym 住宅代理或移动代理套餐

连接参数

- **主机**: `gw.proxonym.com`
- **HTTP**: `8000`
- **SOCKS5**: `1080`
- **用户名**: `USERNAME-country-us`

1. **安装 Playwright 和浏览器**: 先安装库，再下载您要驱动的浏览器。将 JavaScript 示例保存为 `.mjs` 文件，即可使用 `import` 和顶层 `await`。 Shell `npm install playwright npx playwright install chromium`
2. **通过网关启动浏览器**: 在 `proxy` 选项中传入网关、用户名和密码。Playwright 会替您完成网关登录，无需额外的认证步骤。 JavaScript `// launch.mjs import { chromium } from 'playwright'; const browser = await chromium.launch({ proxy: { server: 'http://gw.proxonym.com:8000', username: 'USERNAME', password: 'PASSWORD', }, }); const page = await browser.newPage(); await page.goto('https://api.ipify.org'); console.log('Exit IP:', await page.textContent('body')); await browser.close();`
3. **为每个上下文分配独立的粘性 IP**: 一个页面会建立许多连接，因此请使用 `-session-` ID 让它们都走同一个 IP。每个上下文都可以设置自己的代理，这样一个浏览器就能同时运行多个身份，各自使用独立的国家和会话。 JavaScript `// contexts.mjs import { randomBytes } from 'node:crypto'; import { chromium } from 'playwright'; const browser = await chromium.launch(); for (const country of ['us', 'gb', 'de']) { const context = await browser.newContext({ proxy: { server: 'http://gw.proxonym.com:8000', username: 'USERNAME-country-${country}-session-${randomBytes(4).toString('hex')}-lifetime-30', password: 'PASSWORD', }, }); const page = await context.newPage(); await page.goto('https://api.ipify.org'); console.log(country, await page.textContent('body')); await context.close(); } await browser.close();`
4. **让语言区域和时区与 IP 匹配**: 在用户名中定位国家、州或城市，并相应设置上下文的语言区域和时区，避免浏览器信息与其出口 IP 相互矛盾。 JavaScript `const context = await browser.newContext({ proxy: { server: 'http://gw.proxonym.com:8000', username: 'USERNAME-country-fr-city-paris-session-p4r1s-lifetime-30', password: 'PASSWORD', }, locale: 'fr-FR', timezoneId: 'Europe/Paris', }); const page = await context.newPage(); await page.goto('https://ipinfo.io/json'); console.log(await page.textContent('body'));`
5. **节省流量并重试失败的导航**: 屏蔽图片、媒体和字体以减少计费流量，并对因隧道错误或超时而失败的导航进行重试。网关拒绝连接时，会表现为 `net::ERR_TUNNEL_CONNECTION_FAILED` 之类的错误。 JavaScript `await context.route('**/*', (route) => { const type = route.request().resourceType(); return ['image', 'media', 'font'].includes(type) ? route.abort() : route.continue(); }); async function gotoWithRetry(page, url, tries = 3) { for (let attempt = 1; ; attempt++) { try { return await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60_000 }); } catch (err) { console.error('attempt ${attempt}:', err.message.split('\n')[0]); if (attempt === tries) throw err; } } } const response = await gotoWithRetry(page, 'https://example.com'); console.log('Status:', response?.status());`
6. **在 Python 中使用相同设置**: Playwright for Python 使用相同的代理配置键。用 `pip install playwright` 和 `playwright install chromium` 安装，然后在启动时或在 `new_context()` 中传入代理。 Python `from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(proxy={ "server": "http://gw.proxonym.com:8000", "username": "USERNAME-country-us", "password": "PASSWORD", }) page = browser.new_page() page.goto("https://api.ipify.org") print("Exit IP:", page.text_content("body")) browser.close()`

## 常见问题

### Playwright 能使用带用户名和密码的 SOCKS5 代理吗？

Playwright 可以连接 SOCKS5 服务器，但其用户名和密码字段仅适用于 HTTP 代理。只要需要用凭据认证，就请使用 http://gw.proxonym.com:8000。HTTP 端点通过 CONNECT 隧道传输 HTTPS，并接受相同的定位参数和会话参数，因此在浏览器自动化中选择它不会有任何损失。

### 代理应该在启动时设置，还是按上下文设置？

如果所有页面都应共用同一个身份，就在启动时设置。如果需要并行使用多个 IP 或多个地区，就按上下文设置：上下文比单独的浏览器轻量得多，而且各自的 Cookie 和连接相互隔离。没有单独设置代理的上下文，会沿用启动时的设置（如果有的话）。

### Playwright for Python 的用法一样吗？

一样。在 launch() 和 new_context() 中，proxy 选项接受相同的 server、username 和 password 键，用户名参数同样控制 IP 轮换、粘性会话和地理定位。异步 API 的行为完全一致，因此您可以将本页的 JavaScript 示例逐行移植过去。

### 为什么通过代理访问时 page.goto 会超时？

常见原因是页面过重或目标网站响应缓慢。网关会在目标请求超过 60 秒后以 504 结束请求，因此请等待 domcontentloaded 而不是 networkidle，屏蔽图片和媒体，并使用新的会话 ID 重试。如果反复出现隧道错误，则说明问题出在凭据、余额或目标网站被屏蔽上。

技巧与注意事项

- Playwright 只会向 HTTP 代理发送用户名和密码，因此需要认证时，请使用 8000 端口，而不是 SOCKS5 端点。
- 使用轮换用户名时，一次页面加载可能会用到多个出口 IP，因此凡是涉及登录、加入购物车或多步骤流程的操作，都请使用会话 ID。
- 每个上下文完成任务后请及时关闭，以释放其连接，让下一个身份从干净的状态开始。
- 让粘性会话时长长于上下文的存续时间（住宅代理最长 120 分钟），以免 IP 在流程中途发生变化。

延伸阅读

- [Puppeteer 与 Playwright 代理：认证、轮换与地理定位](https://proxonym.com/zh/blog/puppeteer-playwright-proxies)
- [轮换代理与粘性代理：如何选择合适的会话类型](https://proxonym.com/zh/blog/rotating-vs-sticky-sessions)

卡在某一步了？

大多数故障都可以从错误代码中找到原因。请先查看错误代码，再单独测试代理。

- [帮助中心](https://proxonym.com/zh/help)
- [网关错误代码](https://proxonym.com/zh/docs#errors-and-troubleshooting)
- [测试您的代理](https://proxonym.com/zh/proxy-checker)

## 更多集成指南

[全部集成](https://proxonym.com/zh/integrations)

- [Node.js (JavaScript 运行时)](https://proxonym.com/zh/integrations/nodejs)
- [Puppeteer (JavaScript 库)](https://proxonym.com/zh/integrations/puppeteer)
- [AdsPower (指纹浏览器)](https://proxonym.com/zh/integrations/adspower)
