周一至周五 09:00 - 18:00（UTC+08:00） 
©2026 NST LABS TECH LTD. 保留所有权利。Kai WatanabeScraping Infrastructure Evangelist
剧作家代理无法使用？2026年的完整设置指南
TL;DR
- Playwright 代理通常失败是因为其
server、凭证、协议或作用域错误，而不是因为 Playwright 缺乏代理支持。
- 将一个代理放在
chromium.launch({ proxy }) 中以供整个浏览器使用，或放在 browser.newContext({ proxy }) 中以供一个独立的上下文使用。当前的 Playwright 不需要在上下文代理之前假装的启动级别代理。
- 在 Playwright Test 中，使用
use.proxy 配置运行时流量；HTTPS_PROXY 对于 npx playwright install 仅控制浏览器下载过程。
- HTTP 407 表示代理拒绝身份验证。目标响应如 403 或 429 通常意味着代理连接正常，而目标拒绝或限制了请求。
- 分层验证路由：测试网关，加载一个小的授权端点，然后检查真实页面的失败请求和追踪信息。
- 每个逻辑浏览器上下文保持一个代理会话，将凭证存储在源代码之外，且只使用公共或授权的目标。
为什么你的 Playwright 代理不工作？
你的 Playwright 代理很可能不工作是因为代理设置错误、应用在错误的作用域、从运行时无法访问或在身份验证期间被拒绝。Playwright 当前支持在浏览器或浏览器上下文级别使用 HTTP、HTTPS 和 SOCKS5 代理服务器，如官方 Playwright 网络指南中所述。相同的标准代理对象可以连接到生成的 Nstproxy 住宅代理 网关，而无需特定于提供商的浏览器 SDK。
首先应分类症状，而不是反复更改代码：
| 症状 | 最可能的层 | 第一步检查 |
|---|
ERR_PROXY_CONNECTION_FAILED | 网络路由 | 主机、端口、DNS、容器可达性 |
ERR_TUNNEL_CONNECTION_FAILED | 代理隧道 | 协议、网关能力、上游策略 |
| HTTP 407 | 代理身份验证 | 用户名、密码、账户状态 |
| HTTP 403 或 429 | 目标响应 | 目标权限、速率、会话一致性 |
| 页面加载但 IP 不变 | 配置作用域或绕过 | 启动/上下文配置和绕过规则 |
| 导航超时 | 代理质量或页面资产 | 一个简单的端点、请求失败、追踪 |
| 证书授权错误 | TLS 检查或私有 CA | 证书链和受信任 CA 配置 |
这种区分很重要：407 是代理错误，而网站返回的 403 并不能证明 Playwright 无视了代理。指南的其余部分构建一个已知良好的设置，然后隔离每个层。
配置 Playwright 代理之前你需要什么？
使用当前的 Node.js 运行时、当前的 Playwright 版本和完整的代理凭证集。本指南的实时检查使用了 Node.js 22.23.2 和 Playwright 1.62.1 以及 Python 3.12 和 Playwright 1.62.0，于 2026 年 8 月 6 日进行。目前的 npm 包要求 Node.js 20 或更新版本。
对于 Node.js，创建一个干净的项目并安装 Playwright：
npm init -y
npm install playwright@1.62.1
npx playwright install chromium
server: 方案、主机和端口，例如 http://proxy.example:8000username: 代理账户或生成的会话用户名password: 匹配的密码bypass: 可选的以逗号分隔的主机，应直接连接
请勿将用户名和密码粘贴到 server 中。Playwright 提供单独的凭证字段，将其分开可以避免在密码包含 @、: 或 / 时发生 URL 解析错误。
快速查看
生成当前的 Nstproxy Channel 凭证，测试它与一个小的授权端点，然后将相同的代理设置应用于 Playwright。
如何为整个 Playwright 浏览器设置代理？
将代理对象传递给 chromium.launch()，当该浏览器进程中的每个上下文和页面都应使用相同的路由时：
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({
headless: true,
proxy: {
server: process.env.PROXY_SERVER,
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD,
},
});
const context = await browser.newContext();
const page = await context.newPage();
const response = await page.goto('https://api.ipify.org?format=json', {
waitUntil: 'domcontentloaded',
timeout: 30_000,
});
console.log('HTTP 状态:', response?.status());
console.log('响应:', await page.textContent('body'));
await browser.close();
})();
通过部署的秘密机制设置这三个环境变量。记录 HTTP 状态以供诊断，但对返回的 IP 进行匿名处理，并且永远不要打印密码。公共 IP 端点对于一次请求的路由检查很有用；不应将其作为高频健康检查。
等效的 Nstproxy 设置使用 PROXY_SERVER 中的网关以及 PROXY_USERNAME 和 PROXY_PASSWORD 中生成的通道值。从经过身份验证的仪表板中复制它们，因为位置和会话参数可以嵌入生成的用户名中。
如何在 Playwright Test 中配置代理？
const { defineConfig } = require('@playwright/test');
module.exports = defineConfig({
timeout: 60_000,
use: {
proxy: {
server: process.env.PROXY_SERVER,
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD,
},
trace: 'retain-on-failure',
},
});
然后使用 shell 或 CI 平台提供的秘密运行套件：
PROXY_SERVER="http://proxy.example:8000" \
PROXY_USERNAME="your-generated-username" \
PROXY_PASSWORD="your-secret" \
npx playwright test
此配置在验证期间使用 Playwright Test 1.62.1 加载。保持配置文件不包含实时凭据，以便可以安全提交。
上下文级 Playwright 代理需要启动占位符吗？
不需要。目前 Playwright 可以在没有代理的情况下启动 Chromium，并将代理直接应用于 browser.newContext()。Browser.newContext 代理 API 明确记录了上下文选项及其 server、username、password 和 bypass 字段。
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext({
proxy: {
server: process.env.PROXY_SERVER,
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD,
},
});
const page = await context.newPage();
await page.goto('https://api.ipify.org?format=json');
console.log(await page.textContent('body'));
await browser.close();
})();
此确切行为也在本地使用 Playwright 1.62.1、Basic-auth HTTP 代理和受控 HTTP 目标进行了测试：上下文请求通过代理返回 200，且没有任何启动级别的占位符。需要特殊 per-context 启动代理的旧第三方教程并不是当前 API 的可靠描述。
上下文级路由在一个进程需要多个隔离身份或区域时非常有用。为每个逻辑会话创建一个上下文，并在该会话结束后关闭它。不要在登录或多步流程的过程中更改代理，因为 Cookie、IP 声誉和服务器端会话状态可能不再一致。
如何使用 Playwright Python 代理？
Python 在启动浏览器时使用相同的代理对象形状：
python -m venv .venv
source .venv/bin/activate
python -m pip install "playwright==1.62.0"
playwright install chromium
import os
from playwright.sync_api import sync_playwright
with sync_playwright() as playwright:
browser = playwright.chromium.launch(
headless=True,
proxy={
"server": os.environ["PROXY_SERVER"],
"username": os.environ["PROXY_USERNAME"],
"password": os.environ["PROXY_PASSWORD"],
},
)
page = browser.new_page()
response = page.goto(
"https://api.ipify.org?format=json",
wait_until="domcontentloaded",
timeout=30_000,
)
print("HTTP 状态:", response.status if response else None)
print(page.text_content("body"))
browser.close()
此 Python 模式与 Playwright 1.62.0 一起在受控本地代理上实时运行，并通过该代理返回 HTTP 200。如果已经在使用异步 Python，请将相同的 proxy 字典应用于 async_playwright().chromium.launch() 并等待每个操作。
如何验证 Playwright 实际使用了代理？
验证三阶段的路由，以确保一个复杂的页面不会掩盖真正的故障。
1. 独立测试代理
在运行 Playwright 的同一台机器或容器上使用 curl：
curl --proxy "$PROXY_SERVER" \
--proxy-user "$PROXY_USERNAME:$PROXY_PASSWORD" \
--max-time 20 \
"https://api.ipify.org?format=json"
如果 curl 无法连接，请修复主机名、端口、防火墙、凭据或帐户，然后再调试浏览器代码。如果 curl 成功但 Playwright 失败，请比较这两个进程使用的确切方案和凭证值。
2. 加载一个小的授权端点
运行最小启动示例，检查 HTTP 状态和报告的出站 IP。将其与直接请求进行比较，但从共享日志中删除这两个值。不同的 IP 加上 HTTP 200 确认路由；它并不确认完整应用程序能够工作。
3. 检查真实页面的子请求
现代页面可以在脚本、API、字体或图像失败时渲染 HTML。添加临时监听器：
page.on('requestfailed', request => {
console.error('FAILED', request.method(), request.url(), request.failure());
});
page.on('response', response => {
if (response.status() >= 400) {
console.error('HTTP', response.status(), response.url());
}
});
这些事件揭示了故障是传输级别还是 HTTP 响应级别。在失败时保留 Playwright 跟踪并在本地检查；跟踪可能包含 URL、头部、页面内容和其他敏感数据，因此请限制访问和保留。
如何修复最常见的 Playwright 代理错误？
修复 ERR_PROXY_CONNECTION_FAILED
确认 server 包含支持的方案和正确的端口。http://host:port 表示 Playwright 连接到 HTTP 代理；socks5://host:port 表示 SOCKS5。裸露的 host:port 被视为 HTTP，但明确的方案更易于审核。
测试实际运行时的 DNS 和连通性。在 Docker 中，127.0.0.1 和 localhost 指的是容器本身，而不是主机计算机。使用一个明确可达的服务名称或经过批准的主机网关，而不是将仅限主机的地址复制到容器中。
修复 HTTP 407 代理身份验证所需
407 响应意味着代理已到达但未接受凭据。重新复制生成的用户名，如果可能泄露，则更换密码，并确认凭据仍然有效。不要在紧密循环中重试被拒绝的密码，因为这会模糊日志并可能触发帐户保护。
Playwright 接受用户名和密码作为单独的值。避免手动构建 http://user:pass@host 字符串，特别是在密码中包含保留字符时。
诊断 403 和 429 响应
403 或 429 通常来自目标，而不是代理。在跟踪或头部中确认响应的来源，减少请求速率，保持稳定的会话，检查是否允许访问。代理轮换不能代替授权，且不应用于规避阻止或速率限制。
修复超时和部分页面加载
首先测试一个小的端点。如果快速，那么记录真实页面上失败的子资源。然后在识别合法的慢操作后再增加超时；更大的数字不会修复死网关或无效凭据。
限制并发，而不是打开无限数量的上下文。每个上下文可以创建多个连接和后台请求，因此名义上的页面并发低估了实际负载。仅在临时连接和超时故障的情况下使用重试，设定低上限和退避。
修复证书错误
不要将 ignoreHTTPSErrors: true 作为默认解决方案。证书错误可能表示拦截的企业代理、私有证书颁发机构或意外的端点。在运行时信任存储中安装经过批准的 CA，并在信任之前验证其所有权。
为什么 HTTPS_PROXY 无法修复 Playwright 页面流量？
HTTPS_PROXY 可以配置通过 npx playwright install 执行的浏览器下载；这与 Playwright 的运行时 proxy 选项不同。官方浏览器安装代理指南 使用这种模式：
HTTPS_PROXY="http://download-proxy.example:8080" \
npx playwright install chromium
如果下载代理使用经过批准的私有证书颁发机构，可以在安装过程中将 Node.js 指向其 CA 文件：
NODE_EXTRA_CA_CERTS="/path/to/approved-root-ca.pem" \
HTTPS_PROXY="http://download-proxy.example:8080" \
npx playwright install chromium
安装后，使用 chromium.launch({ proxy })、browser.newContext({ proxy }) 或 Playwright Test 的 use.proxy 配置页面流量。将下载连通性和浏览器运行时连通性视为两个单独的检查。
绕过规则如何影响代理测试？
可选的 bypass 值是一个以逗号分隔的域名列表，这些域名应该直接连接。一个广泛或意外的条目可能会让 IP 检查看起来没有变化，即使代理已正确配置其他主机：
proxy: {
server: process.env.PROXY_SERVER,
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD,
bypass: 'localhost,127.0.0.1,.internal.example',
}
保持 bypass 规则的狭窄，并记录每个主机需要直接访问的原因。对本指南的实时验证确认被 bypass 的控制目标直接返回，而未 bypass 的请求通过代理。
如何在不破坏浏览器会话的情况下旋转代理？
在逻辑会话之间旋转，而不是在一个浏览器工作流内部的请求之间旋转。一个实用的映射是一个代理会话对应一个浏览器上下文：cookies、本地存储、缓存和出站连接在上下文关闭之前保持一致。
如果需要新的路由，关闭旧的上下文，生成下一个批准的会话配置，然后创建一个新的上下文。保持提供者和目标的并发限制，为瞬时故障增加退避，并仅记录诊断所需的非敏感标识符。IP 轮换指南解释了随机轮换和粘性会话之间的区别，而 HTTP 代理指南涵盖了隧道和身份验证的基础。
什么时候 Nstproxy 是 Playwright 的实用选择？
Nstproxy Residential Prime Proxies 是一个实用的选项，当授权的浏览器测试或公共网络采集需要住宅路由和管理的会话控制时。Playwright 可以通过其标准的代理对象使用生成的 HTTP、HTTPS 或 SOCKS5 网关，因此不需要特定于提供商的浏览器 SDK。一个 Channel 将代理配置与应用代码分开，而生成的位置和会话参数使操作员能够从当前仪表板中选择所需的路由行为。粘性会话的连续性可以映射到一个浏览器上下文，当下一个上下文启动时可以发生轮换。在规模化生产工作负载之前，请在经过身份验证的仪表板中确认当前可用性、目标、套餐和会话选项。
- 标准 Playwright 集成： 使用生成的网关与启动级、上下文级或 Playwright 测试代理设置。
- 会话控制： 对于一个逻辑流，保持生成的会话值稳定，然后在需要轮换时为下一个批准上下文更改它。
- 位置配置： 在仪表板中选择当前可用的目标，以便于合法本地化、广告验证或区域质量保证。
- 凭证分离： 将 Channel 凭证存储在秘密管理器中，而不是嵌入测试文件或痕迹中。
Nstproxy 不会改变网站的条款、访问规则或隐私义务。仅在公共或授权目标上使用，最小化个人数据，并在目标或帐户所有者撤回权限时停止。
最快速的 Playwright 代理故障排除工作流程是什么？
- 使用 curl 从相同运行时验证主机、端口、方案和凭证。
- 针对一个小的授权端点运行一个页面的 Playwright 脚本。
- 确认出站 IP 发生了变化，然后将其从共享输出中删除。
- 使用预期的启动、上下文或 Playwright 测试范围重现。
- 启用请求失败日志记录并保留一次失败运行的踪迹。
- 将代理失败与目标 HTTP 响应（如 403 或 429）分开。
- 检查容器 DNS、防火墙、证书、旁路规则和资源限制。
- 只有在故障类别已知后才添加有限的重试。
这个工作流程避免了最常见的错误：在不知道哪个层失败的情况下，同时更改浏览器标志、超时和代理提供商。
结论
当 Playwright 代理无法工作时，从范围和传输开始：使用启动代理用于整个浏览器，使用上下文代理用于隔离的会话，或 use.proxy 用于 Playwright 测试。独立验证网关，将凭证保存在不同字段中，并使用请求事件加上踪迹来区分连接失败与目标响应。当前 Playwright 支持上下文级代理，而没有启动占位符，同时浏览器安装的 HTTPS_PROXY 仍然是一个单独的问题。一旦最小的授权请求工作，将真实页面、受控并发和会话轮换逐层添加。
使用 Nstproxy 设置 Playwright 代理
创建一个 Channel，复制当前生成的网关和凭证，并在运行完整浏览器工作流程之前验证一个小的授权请求。
常见问题
问：为什么我的 Playwright 代理服务器不工作，而 curl 却可以？
Playwright 可能使用了不同的凭据、不同的代理方案、意外的绕过规则或错误的配置范围。比较确切的值，运行一个最小的浏览器脚本，并在测试完整页面之前记录 requestfailed 事件。
可以。在 server 中放入代理 URL，并在启动、上下文或 Playwright 测试级别提供 username 和 password 作为单独的字段。
问：每个 Playwright 上下文可以使用不同的代理吗？
可以。为每个上下文创建自己的 proxy 对象。当前的 Playwright 在上下文级别的代理配置之前不需要在浏览器启动时使用虚拟代理。
问：Playwright 支持 SOCKS5 代理吗？
支持。使用如 socks5://proxy.example:1080 的服务器值，并确认网关和认证方法支持所选择的协议。
问：为什么 Playwright 显示 HTTP 407？
HTTP 407 意味着代理拒绝了认证。检查生成的用户名、密码、账户或频道状态，以及密钥是否被截断或在复制时带有空格。
问：为什么设置 HTTPS_PROXY 不改变浏览器 IP？
Playwright 文档中的 HTTPS_PROXY 用于在代理后下载浏览器二进制文件。通过 launch({ proxy })、newContext({ proxy }) 或 Playwright 测试中的 use.proxy 分别配置运行时页面流量。
问：我应该在每个 Playwright 请求中轮换代理吗？
不应该。在逻辑浏览器上下文的持续时间内保持一个代理会话，然后在创建下一个上下文时进行轮换。这样可以保持 cookies、存储、导航和服务器端会话状态的一致性。
立即访问住宅、数据中心、IPv6 与 ISP 高质量代理池。
