Puppeteer 与 Playwright 代理:认证、轮换与地理定位
在 Puppeteer 和 Playwright 中使用认证代理的 Node.js 代码:每个浏览器上下文一个 IP、地理定位并匹配语言区域和时区,以及常见错误的解决方法。
作者:Proxonym 团队
Chromium 不接受写在 URL 中的代理凭据,因此在 Puppeteer 中设置代理需要两步:启动浏览器时传入 --proxy-server,然后用用户名和密码调用 page.authenticate()。Playwright 则把这两步合并为一个 proxy 选项,既可以为整个浏览器设置,也可以为每个上下文单独设置。本指南提供这两者的可运行代码,并介绍如何为每个浏览器上下文分配一个 IP、如何进行地理定位,以及让无头会话与其 IP 保持一致的相关设置。
Puppeteer 设置代理:启动参数与 page.authenticate
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 绑定的网站出错。请为每个浏览器身份分配一个比任务持续时间更长的粘性会话,住宅代理最长可达 120 分钟。轮换会话与粘性会话一文介绍了如何确定会话时长。
每个浏览器上下文一个 IP
为每个 IP 单独启动一个浏览器很慢。浏览器上下文是同一浏览器进程中开销很小、彼此隔离的配置环境,各自拥有独立的 Cookie、存储和缓存。为每个上下文配上独立的粘性会话,只需启动一次浏览器,就能获得许多互不相干的身份。
Puppeteer
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
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 接受同样的字典:
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 请求头,正是反爬虫脚本专门检查的那种不一致。
// 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、时区和语言三者一致:
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。每次请求都随机更换指纹,只会让您看起来更不像真人,而不是更像。
- 控制节奏。等待页面加载完成,避免同时用多个上下文猛刷同一个网站;出现验证码时应放慢速度,而不是硬闯过去。网页抓取防封禁一文深入介绍了速率控制。
在按 GB 计费的套餐上,浏览器流量累积得很快。屏蔽图片、媒体和字体可以减少每个页面的传输量:
// 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());如果您有大批浏览器全天候渲染完整页面,不限流量住宅代理按带宽而非按 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 发送请求:
curl -v -o /dev/null -x http://gw.proxonym.com:8000 \
-U "USERNAME-country-us-session-k3p9x2:PASSWORD" https://example.com现成的代码片段可在 Puppeteer 和 Playwright 集成页面找到。
要点总结
- Puppeteer 需要在启动时传入
--proxy-server(或为每个上下文设置proxyServer),再加上page.authenticate()。Playwright 只需一个包含服务器地址、用户名和密码的proxy选项。 - 浏览器流量务必使用粘性会话,每个身份一个。
- 每个身份使用一个浏览器上下文,而不是每个 IP 启动一个浏览器。
- 让语言区域和时区与出口国家一致,并堵住 WebRTC 泄露。
- Chromium 无法对 SOCKS5 进行身份认证,因此需要认证的代理请使用 HTTP 端口。
