# 如何在 Playwright、Puppeteer、Selenium 配置代理？

按自动化工具选择代理与认证入口，区分动态账密、静态实例及 Selenium 的接入限制。

浏览器自动化的代理配置由执行进程控制，普通浏览器里设置成功不代表脚本已经使用。下面按工具确认入口和认证方式。

## 步骤一：获取只只HTTP代理信息

- **动态住宅**：进入“动态住宅网络 → 账密认证”，取得 `us.zzhttp.com`、端口 `7878`、生成的完整代理用户名和对应子账号密码；协议按工具选择 HTTP 或 SOCKS5 TCP。先确认实名、权益、共享流量和子账号状态。
- **静态住宅**：进入“静态住宅网络 → IP 管理”，复制已交付、可用且未到期实例的实际 IP、端口与独立代理账密。静态购买无需实名认证，不使用动态网关、子账号或客户白名单。

详细获取步骤见[账密认证](/help/network/account-auth)和[静态住宅首次连接](/help/getting-started/static-residential-quickstart)。代理密码不是控制台登录密码。

## 步骤二：按工具配置代理和认证

| 工具 | 端点入口 | 认证入口与注意事项 |
| --- | --- | --- |
| Playwright | 启动浏览器或创建上下文时的 `proxy.server` | HTTP 的 `proxy.username`、`proxy.password`；详见[既有示例](/developers/examples/playwright) |
| Puppeteer | 启动参数 `--proxy-server=http://主机:端口` | 页面导航前调用 `page.authenticate({username, password})`，不要只把账密塞到启动参数 |
| Selenium + Chromium | 浏览器代理能力或 `--proxy-server` 只设置端点 | 普通代理端点配置不能自动解决账密认证；既有示例使用动态 API 提取与来源白名单，不能直接用于静态实例 |

Playwright 与 Puppeteer 的 HTTP 账密分别填入动态完整用户名／子账号密码，或静态实例独立凭据。Chromium 的 SOCKS5 用户名密码认证限制不因使用自动化框架而消失，优先使用 HTTP 账密。

Selenium 静态用户需要先选用并验证支持 HTTP 代理认证的驱动接入方案；没有认证处理时无法仅凭端口完成配置。可以先使用 Playwright 的 HTTP 账密方式验证实例。[Selenium 既有示例](/developers/examples/selenium)属于动态 API 提取流程，不让静态用户创建动态白名单。

## 步骤三：保存配置并启动任务

1. 将端点和凭据从运行时私有配置注入，不写入代码仓库或输出日志。
2. 在发出首个请求前完成代理和认证设置。Playwright 修改代理后创建新的浏览器或上下文；Puppeteer 在页面导航前完成认证。
3. 每个任务明确使用对应上下文／用户数据目录，限制并发，结束后关闭页面和进程。多个上下文使用同一实例不会自动获得不同 IP。

## 步骤四：验证出口

先运行只有检测页的最小任务，读取 `https://ipinfo.io/json` 的响应，再增加目标操作。检测必须发生在刚启动的自动化上下文内，不用终端直连结果代替浏览器结果。

## 验证代理是否生效

在真正执行任务的环境中打开或请求 `https://ipinfo.io/json`，核对 `ip`、`country`、`region`，并与该环境未启用代理时的出口比较。动态网关主机与出口 IP 不相同，不要求检测结果等于网关解析地址。静态按实例标称出口核对；地区数据库可能存在偏差。再访问允许测试的 HTTPS 页面确认链路。

## 常见问题

- **连接失败或超时**：核对端点、端口、协议和执行环境网络，见[连接失败排查](/help/troubleshooting/connection-failed)。
- **认证失败**：动态核对完整用户名、子账号、权益与实际连接来源；静态核对实例当前凭据与有效期，不能靠补动态白名单解决。见[407 排查](/help/troubleshooting/proxy-auth-407)。
- **仍显示原出口**：确认代理已绑定到实际设备或任务，排除绕过列表、其他代理覆盖和旧配置。
- **检测成功但目标失败**：目标站点的 `403`、`429`、页面变化和代理连接错误分别排查，先降低并发并查看实际错误。

需要长期保持同一出口时使用静态实例；动态[粘性会话](/help/network/sticky-session)只在配置的会话周期内保持，不等于永久固定 IP。多个设备使用同一实例仍可能共用出口。截图、日志和任务导出中不要暴露完整凭据。

认证入口参考[Playwright 官方 HTTP 代理说明](https://playwright.dev/docs/network#http-proxy)和[Puppeteer authenticate 文档](https://pptr.dev/api/puppeteer.page.authenticate)。