---
title: "Puppeteer 与 Playwright 代理：认证与轮换 | Proxonym"
description: "为 Puppeteer 或 Playwright 配置带身份验证的代理：按浏览器上下文轮换 IP、定位国家，并保持无头浏览器会话一致。"
url: https://proxonym.com/zh/blog/puppeteer-playwright-proxies
updated: 2026-10-02T03:03:46+00:00
---

教程 · 2026年10月1日 · 阅读约 5 分钟

# Puppeteer 与 Playwright 代理：认证、轮换与地理定位

在 Puppeteer 和 Playwright 中使用认证代理的 Node.js 代码：每个浏览器上下文一个 IP、地理定位并匹配语言区域和时区，以及常见错误的解决方法。

作者：Proxonym 团队

Chromium 不接受写在 URL 中的代理凭据，因此在 Puppeteer 中设置代理需要两步：启动浏览器时传入 `--proxy-server`，然后用用户名和密码调用 `page.authenticate()`。Playwright 则把这两步合并为一个 `proxy` 选项，既可以为整个浏览器设置，也可以为每个上下文单独设置。本指南提供这两者的可运行代码，并介绍如何为每个浏览器上下文分配一个 IP、如何进行地理定位，以及让无头会话与其 IP 保持一致的相关设置。

## Puppeteer 设置代理：启动参数与 page.authenticate

**JavaScript**

```javascript
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=http://gw.proxonym.com:8000'],
  });
  const page = await browser.newPage();
  await page.authenticate({
    username: 'USERNAME-country-us-session-k3p9x2-lifetime-15',
    password: 'PASSWORD',
  });
  await page.goto('https://api.ipify.org', { waitUntil: 'domcontentloaded' });
  console.log(await page.evaluate(() => document.body.innerText));   // the exit IP
  await browser.close();
})();
```

请在首次导航之前调用 `page.authenticate()`；它会为页面发出的每个请求应答网关的 `407` 认证质询。请使用 HTTP 端口 8000：Chromium 无法对 SOCKS5 代理进行身份认证。

注意用户名中的 session 参数。加载一个页面就会拉取几十个资源：脚本、样式、字体和 API 调用。如果没有粘性会话，这些连接可能会从不同的 IP 发出，真实访客绝不会这样，而且这会让那些把 Cookie 与 IP 绑定的网站出错。请为每个浏览器身份分配一个比任务持续时间更长的粘性会话，[住宅代理](https://proxonym.com/zh/residential-proxies)最长可达 120 分钟。[轮换会话与粘性会话](https://proxonym.com/zh/blog/rotating-vs-sticky-sessions)一文介绍了如何确定会话时长。

## 每个浏览器上下文一个 IP

为每个 IP 单独启动一个浏览器很慢。浏览器上下文是同一浏览器进程中开销很小、彼此隔离的配置环境，各自拥有独立的 Cookie、存储和缓存。为每个上下文配上独立的粘性会话，只需启动一次浏览器，就能获得许多互不相干的身份。

### Puppeteer

**JavaScript**

```javascript
const { randomBytes } = require('node:crypto');

async function withIdentity(browser, country, task) {
  const context = await browser.createBrowserContext({
    proxyServer: 'http://gw.proxonym.com:8000',
  });
  const page = await context.newPage();
  await page.authenticate({
    username: `USERNAME-country-${country}-session-${randomBytes(4).toString('hex')}-lifetime-20`,
    password: 'PASSWORD',
  });
  try {
    return await task(page);
  } finally {
    await context.close();
  }
}

// await withIdentity(browser, 'de', (page) => page.goto('https://example.com'));
```

在 Puppeteer 22 及更高版本中，该方法名为 `createBrowserContext()`；旧版本中则叫作 `createIncognitoBrowserContext()`。每个上下文只保留一个身份，不要在已有页面上切换用户名：Chromium 会缓存代理凭据，因此在同一上下文中再次调用 `authenticate()` 可能不会生效。

### Playwright

**JavaScript**

```javascript
const { chromium } = require('playwright');
const { randomBytes } = require('node:crypto');

(async () => {
  const browser = await chromium.launch();
  for (const country of ['us', 'gb', 'jp']) {
    const context = await browser.newContext({
      proxy: {
        server: 'http://gw.proxonym.com:8000',
        username: `USERNAME-country-${country}-session-${randomBytes(4).toString('hex')}-lifetime-20`,
        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();
})();
```

如果想让整个浏览器都使用同一个代理，改为把同一个 `proxy` 对象传给 `chromium.launch()` 即可。在较早的 Playwright 版本中，Windows 上的 Chromium 需要先在启动时设置一个占位代理 `proxy: { server: 'http://per-context' }`，按上下文设置的代理才能生效。Python API 接受同样的字典：

**Python**

```python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context(proxy={
        "server": "http://gw.proxonym.com:8000",
        "username": "USERNAME-country-gb-session-q7m2x9-lifetime-20",
        "password": "PASSWORD",
    })
    page = context.new_page()
    page.goto("https://api.ipify.org")
    print(page.text_content("body"))
    browser.close()
```

### 浏览器该搭配哪种代理

- **动态住宅代理 + 粘性会话**：适合数据抓取和短时会话，每个上下文一个全新身份，每个身份最长保持 120 分钟。
- **ISP 代理**：适合需要长期保留的浏览器环境，例如每天都应从同一 IP 登录的账号。IP 在整个租期内固定不变，且带宽不限。
- **不限流量住宅代理**：适合高强度、持续不断的页面渲染，在这种场景下，按 GB 计费会让流量费用成为成本的大头。

## 地理定位：保持浏览器环境一致

在用户名中用 `-country-` 指定出口位置，如需更精细的定位，再加上 `-state-` 或 `-city-`。然后让浏览器的设置与之保持一致。德国 IP 搭配美国时区，再加上只有英语的 `Accept-Language` 请求头，正是反爬虫脚本专门检查的那种不一致。

**JavaScript**

```javascript
// Playwright: everything goes into the context options
const context = await browser.newContext({
  proxy: {
    server: 'http://gw.proxonym.com:8000',
    username: 'USERNAME-country-de-city-berlin-session-b81f2c-lifetime-30',
    password: 'PASSWORD',
  },
  locale: 'de-DE',
  timezoneId: 'Europe/Berlin',
});

// Puppeteer: set per page
await page.emulateTimezone('Europe/Berlin');
await page.setExtraHTTPHeaders({ 'Accept-Language': 'de-DE,de;q=0.9,en;q=0.6' });
```

Playwright 的 `locale` 选项会同时设置 `navigator.language` 和 `Accept-Language` 请求头。而在 Puppeteer 中，额外设置的请求头不会改变 `navigator.language`，因此请确认目标网站读取的是两者中的哪一个。

### 运行前检查浏览器环境

开始任务前，请确认 IP、时区和语言三者一致：

**JavaScript**

```javascript
await page.goto('https://api.ipify.org');
const report = await page.evaluate(() => ({
  ip: document.body.innerText.trim(),
  timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
  language: navigator.language,
}));
console.log(report);   // { ip: '...', timezone: 'Europe/Berlin', language: 'de-DE' }
```

在 IP 地理位置数据库中查询该 IP，确认所在国家；并对每个上下文重复这项检查，因为每个上下文都有自己的会话，因而也有自己的 IP。

## 无头浏览器检测：代理能解决什么，不能解决什么

代理改变的是 IP 地址，而不是浏览器。给自动化流量打分的网站会同时检查这两者，因此请记住以下几点：

- **使用完整的无头模式。**Puppeteer 默认的 `headless: true` 运行的是 Chrome 的新版无头模式。在 Playwright 中，传入 `channel: 'chromium'` 即可使用该模式，而不是更轻量的 headless shell，后者与常规浏览器的差异更大。
- **堵住 WebRTC 泄露。**WebRTC 可能绕过代理，通过 UDP 暴露您的真实 IP。请在启动参数中加入 `--force-webrtc-ip-handling-policy=disable_non_proxied_udp`。
- **保持一致。**在一个身份的整个生命周期内，保持相同的 IP、User-Agent、时区和 Cookie。每次请求都随机更换指纹，只会让您看起来更不像真人，而不是更像。
- **控制节奏。**等待页面加载完成，避免同时用多个上下文猛刷同一个网站；出现验证码时应放慢速度，而不是硬闯过去。[网页抓取防封禁](https://proxonym.com/zh/blog/web-scraping-without-getting-blocked)一文深入介绍了速率控制。

在按 GB 计费的套餐上，浏览器流量累积得很快。屏蔽图片、媒体和字体可以减少每个页面的传输量：

**JavaScript**

```javascript
// Playwright
await context.route('**/*', (route) =>
  ['image', 'media', 'font'].includes(route.request().resourceType()) ? route.abort() : route.continue());

// Puppeteer
await page.setRequestInterception(true);
page.on('request', (req) =>
  ['image', 'media', 'font'].includes(req.resourceType()) ? req.abort() : req.continue());
```

如果您有大批浏览器全天候渲染完整页面，[不限流量住宅代理](https://proxonym.com/zh/unlimited-residential-proxies)按带宽而非按 GB 计费，并支持最长 12 小时的粘性会话。

## 故障排查

| 错误 | 可能原因 | 解决方法 |
| --- | --- | --- |
| `net::ERR_PROXY_CONNECTION_FAILED` | 浏览器无法连接到网关 | 检查主机和端口；允许访问 8000 端口的出站流量 |
| `net::ERR_TUNNEL_CONNECTION_FAILED` | 网关拒绝了 CONNECT 请求，例如返回 `402`（余额不足）、`403`（目标被拦截）或 `502`（节点连接失败） | 用 curl 复现，查看状态码 |
| `net::ERR_INVALID_AUTH_CREDENTIALS` | 用户名或密码错误，或在导航之后才调用 `authenticate()` | 先完成认证，并从控制台复制凭据 |
| 导航超时 | 节点速度慢或页面过大 | 使用 `waitUntil: 'domcontentloaded'`，屏蔽媒体资源，并换用新会话重试 |

要准确查看网关返回了什么，可以使用同一个用户名，通过带 `-v` 参数的 curl 发送请求：

**Shell**

```bash
curl -v -o /dev/null -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-us-session-k3p9x2:PASSWORD" https://example.com
```

现成的代码片段可在 [Puppeteer](https://proxonym.com/zh/integrations/puppeteer) 和 [Playwright](https://proxonym.com/zh/integrations/playwright) 集成页面找到。

## 要点总结

- Puppeteer 需要在启动时传入 `--proxy-server`（或为每个上下文设置 `proxyServer`），再加上 `page.authenticate()`。Playwright 只需一个包含服务器地址、用户名和密码的 `proxy` 选项。
- 浏览器流量务必使用粘性会话，每个身份一个。
- 每个身份使用一个浏览器上下文，而不是每个 IP 启动一个浏览器。
- 让语言区域和时区与出口国家一致，并堵住 WebRTC 泄露。
- Chromium 无法对 SOCKS5 进行身份认证，因此需要认证的代理请使用 HTTP 端口。

学以致用

- [住宅代理](https://proxonym.com/zh/residential-proxies): 最适合抓取防护严密的网站。 低至 **$0.74**/GB
- [不限流量住宅代理](https://proxonym.com/zh/unlimited-residential-proxies): 最适合大规模爬取和 AI 训练数据采集。 低至 **$33.25**/天
- [ISP 代理](https://proxonym.com/zh/isp-proxies): 最适合账号管理和长时会话。 低至 **$1.15**/IP

分步配置指南

- [Puppeteer 代理配置](https://proxonym.com/zh/integrations/puppeteer)
- [Playwright 代理配置](https://proxonym.com/zh/integrations/playwright)
- [Selenium 代理配置](https://proxonym.com/zh/integrations/selenium)

在您的目标网站上实测

自助购买套餐，支持加密货币付款，几分钟内即可开通。套餐绝不自动续费。

## 继续阅读

[全部文章](https://proxonym.com/zh/blog)

- [面向 AI 智能体的代理：为 LLM 应用提供可靠的网页访问](https://proxonym.com/zh/blog/proxies-for-ai-agents): 一旦被网站封锁，AI 智能体就会失灵。从搜索增强到浏览型智能体，本文说明每类任务适合哪种工具，并附上 Playwright 代码，以及让智能体始终受网站欢迎的使用规则。 (指南, 阅读约 5 分钟)
- [如何选择住宅代理服务商：10 项检查要点](https://proxonym.com/zh/blog/choose-residential-proxy-provider): 标价往往掩盖了大部分真实成本。本文给出区分住宅代理服务商的十项检查、一份危险信号对照表，以及在您自己的目标网站上进行测试的简单方法。 (指南, 阅读约 5 分钟)
- [住宅代理与数据中心代理：如何按业务需求选择](https://proxonym.com/zh/blog/residential-vs-datacenter-proxies): 住宅代理与数据中心代理的逐项对比，附决策表、混合路由策略，以及基于真实按 GB 和按 IP 价格的成本测算。 (指南, 阅读约 6 分钟)
