---
title: "Puppeteer 代理设置：带身份验证 | Proxonym"
description: "通过代理运行 Puppeteer：使用 --proxy-server 启动 Chrome，用 page.authenticate 登录，为每个上下文保持粘性 IP 并匹配地区。"
url: https://proxonym.com/zh/integrations/puppeteer
updated: 2026-10-02T03:03:46+00:00
---

# 如何在 Puppeteer 中使用代理

Puppeteer 通过启动参数让 Chrome 使用代理，并用 page.authenticate() 完成网关登录。本指南还介绍粘性会话、每个浏览器上下文一个 IP、位置匹配以及更轻量的页面加载。

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

开始之前

- Node.js 22 或更高版本
- Puppeteer 22 或更高版本
- Proxonym 住宅代理或移动代理套餐

连接参数

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

1. **安装 Puppeteer**: 安装该包时，还会一并下载匹配版本的 Chrome for Testing。将示例保存为 `.mjs` 文件，即可使用 `import` 和顶层 `await`。 Shell `npm install puppeteer`
2. **通过网关启动 Chrome**: Chrome 会忽略 `--proxy-server` 中的凭据，因此只需在其中传入主机和端口，并在首次导航之前用 `page.authenticate()` 提供用户名和密码。 JavaScript `// launch.mjs import puppeteer from 'puppeteer'; const browser = await puppeteer.launch({ args: ['--proxy-server=http://gw.proxonym.com:8000'], }); const page = await browser.newPage(); await page.authenticate({ username: 'USERNAME', password: 'PASSWORD' }); await page.goto('https://api.ipify.org'); console.log('Exit IP:', await page.evaluate(() => document.body.innerText)); await browser.close();`
3. **在整个会话中保持同一 IP**: 一个页面会建立许多连接，使用轮换用户名时，每个连接都可能从不同的 IP 发出。添加 `-session-` ID，让所有连接共用同一个 IP，并将 `-lifetime-` 设得比任务时长更长，最长 120 分钟。 JavaScript `import { randomBytes } from 'node:crypto'; const session = randomBytes(4).toString('hex'); await page.authenticate({ username: 'USERNAME-country-us-session-${session}-lifetime-30', password: 'PASSWORD', });`
4. **每个浏览器上下文使用一个 IP**: 各个浏览器上下文的 Cookie 和连接相互独立，每个上下文都可以使用自己的代理。为每个上下文分配不同的会话 ID 或国家，即可在一个 Chrome 进程中运行多个身份。 JavaScript `// contexts.mjs import { randomBytes } from 'node:crypto'; import puppeteer from 'puppeteer'; const browser = await puppeteer.launch(); async function openIdentity(country) { 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-30', password: 'PASSWORD', }); return page; } const pages = await Promise.all(['us', 'gb', 'de'].map(openIdentity)); for (const page of pages) { await page.goto('https://api.ipify.org'); console.log(await page.evaluate(() => document.body.innerText)); } await browser.close();`
5. **让浏览器与地理位置匹配**: 在用户名中定位国家、州或城市，再让时区和语言与之保持一致，使浏览器和 IP 呈现的信息相互吻合。 JavaScript `await page.authenticate({ username: 'USERNAME-country-de-city-berlin-session-b3x9-lifetime-30', password: 'PASSWORD', }); await page.emulateTimezone('Europe/Berlin'); await page.setExtraHTTPHeaders({ 'Accept-Language': 'de-DE,de;q=0.9' }); await page.goto('https://ipinfo.io/json'); console.log(await page.evaluate(() => document.body.innerText));`
6. **节省流量并处理错误**: 住宅代理流量按 GB 计费，因此请屏蔽不需要的图片、媒体和字体。隧道被拒绝时，`page.goto()` 会抛出 `net::ERR_TUNNEL_CONNECTION_FAILED`，值得换一个新的会话 ID 重试；而登录被拒绝时，返回的是 407 状态码。 JavaScript `await page.setRequestInterception(true); page.on('request', (request) => { if (['image', 'media', 'font'].includes(request.resourceType())) request.abort(); else request.continue(); }); try { const response = await page.goto('https://example.com', { waitUntil: 'domcontentloaded', timeout: 60_000, }); console.log('Status:', response?.status()); } catch (err) { console.error('Navigation failed:', err.message); }`

## 常见问题

### 为什么 Puppeteer 会报 ERR_TUNNEL_CONNECTION_FAILED 错误？

这表示网关拒绝建立通往目标网站的隧道。402 表示余额已用完或套餐已过期，403 表示目标网站受可接受使用政策限制而被屏蔽；502 和 504 则是暂时性错误，换一个新的会话 ID 重试即可。登录问题的表现则不同：页面返回 407 状态码；如果没有调用 page.authenticate()，则会出现 ERR_INVALID_AUTH_CREDENTIALS 错误。

### 每个页面或标签页可以使用不同的 IP 吗？

可以。为每个身份创建一个带独立 proxyServer 的浏览器上下文，在其中打开页面，并用带有不同会话 ID 或国家的用户名为每个页面完成认证。同一上下文中的页面共享 Cookie 和连接，因此请把一个上下文视为一个身份，对应一个粘性 IP。

### 无头模式会影响代理的工作方式吗？

不会。无论是无头模式还是有头模式，代理启动参数、认证步骤和用户名参数都完全相同。不同的是浏览器指纹，因此请让时区、语言和视口与出口位置保持一致，并让请求频率符合真实用户访问该网站的水平。

### 如何减少每个页面消耗的流量？

通过请求拦截屏蔽图片、媒体和字体，等待 domcontentloaded 而不是等到网络完全空闲，并在整个流程中复用同一个粘性会话，避免重复加载页面。一次完整的页面加载可能传输好几 MB 数据，因此在按 GB 计费的住宅代理套餐上，这些措施的效果非常明显。

技巧与注意事项

- Chrome 不支持需要用户名和密码的 SOCKS5 代理，因此在浏览器中请使用 8000 端口的 HTTP 网关。
- page.authenticate() 只对单个页面生效，因此每打开一个新页面或弹出窗口，都要重新调用。
- 将粘性会话时长设得比脚本运行时间更长（住宅代理最长 120 分钟），以免 IP 在流程中途发生变化。
- 对于需要数天都保持同一地址的登录和账号，静态 ISP 代理比轮换的住宅代理会话更合适。

延伸阅读

- [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)
- [Playwright (JavaScript 库)](https://proxonym.com/zh/integrations/playwright)
- [AdsPower (指纹浏览器)](https://proxonym.com/zh/integrations/adspower)
