Patchright 代理设置：启动、上下文、认证和 Docker
Patchright 在浏览器启动前修补了 Playwright 的 CDP 泄漏。它不会影响您的 IP 信誉——其推荐的隐身设置悄然改变了您旋转代理的方式。
Patchright 是一个经过修补的、未检测到的 Playwright 构建，作为替代品使用：更改导入，保持代码不变。补丁在浏览器进程启动之前应用——它们移除了自动化标志和 Chrome DevTools 协议调用，这些调用会在 Playwright 会话的最初几毫秒内让网站识别。它们不触及的是网络。每个 Patchright 代理问题都回到这种分裂，以及 README 掩盖的一个细节：项目推荐的最大隐身设置是持久上下文，这悄然改变了您旋转出口的方式。这是一个以代理为重点的指南——启动与上下文、认证网关、Docker，以及对上限的诚实描述。
安装和替代代理
Patchright 支持 Python、Node 和 .NET，仅修补 Chromium——明确不支持 Firefox 和 WebKit。安装它并拉取真实的 Google Chrome 而不是捆绑的 Chromium，这是项目推荐的隐身方式：
pip install patchright
patchright install chrome
# Node: npm i patchright && npx patchright install chrome代理 API 是 Playwright 的，未更改，因为代理是 Patchright 故意不动的少数几个东西之一。凭证放在专用字段中，绝不放在服务器 URL 内——这就是为什么认证代理在这里不需要扩展补丁，不像 Selenium 或原始 Puppeteer：
from patchright.sync_api import sync_playwright
PROXY = {
"server": "http://gate.quantumproxies.io:PORT",
"username": "USER",
"password": "PASS",
}
with sync_playwright() as p:
browser = p.chromium.launch(channel="chrome", proxy=PROXY)
page = browser.new_page()
page.goto("https://httpbin.org/ip")
print(page.text_content("body")) # the exit IP
browser.close()这就是“Patchright 是否支持代理”的完整答案：是的，与上游 Playwright 完全相同，包括bypass列表和 Chromium 的一个怪癖，即回环地址完全跳过代理——因此对本地模拟服务器的测试总是看起来像代理被忽略。如果您对底层模型不熟悉，我们的Playwright 代理集成指南涵盖了基本行为，反检测框架代理地图比较了哪些堆栈本身接受凭证。
每上下文代理和全局存根
上下文是廉价的旋转单元：独立的 cookie、存储和缓存，在毫秒内创建，而不是浏览器启动所需的几秒。每个都采用自己的proxy选项，因此单个进程可以同时持有美国身份和德国身份。这里有一个记录在案的 Playwright 陷阱让人们困惑——浏览器必须以全局代理启动，以便每上下文代理在 Chromium 上工作。如果每个上下文都覆盖它，全局值将永远不会被使用，可以是任何占位符字符串：
const { chromium } = require('patchright');
(async () => {
// the global proxy is never used — it only enables the per-context option
const browser = await chromium.launch({
channel: 'chrome',
proxy: { server: 'http://per-context' },
});
for (const job of jobs) {
const context = await browser.newContext({
proxy: {
server: 'http://gate.quantumproxies.io:PORT',
username: 'USER-country-' + job.country, // geo in the username
password: 'PASS',
},
});
const page = await context.newPage();
try {
await page.goto(job.url, { timeout: 30000 });
// ...extract...
} finally {
await context.close(); // burns the cookies with the exit
}
}
await browser.close();
})();指向旋转网关，每个上下文从 90M+ 住宅池中的不同地址离开，您的端无需列表管理——这就是旋转代理在服务器端的作用。注意片段中地理和会话控制的位置：在用户名中，而不是自定义头中。这在 Patchright 中比在普通 Playwright 中更重要，因为项目本身的指导是避免自定义头和用户代理覆盖，因为注入的值本身就是检测面。用户名参数控制保持浏览器的请求形状不变。
持久上下文的权衡
Patchright 推荐的隐身配置不是launch()。而是launch_persistent_context()，使用真实的 Chrome 通道、用户数据目录、无视口覆盖和有头模式——并明确没有自定义头或伪造的用户代理。该设置还会保留挑战提供的任何清除 cookie，因此解决的挑战可以在运行之间重复使用。代理的结果是结构性的：持久上下文就是上下文。没有newContext()来挂载第二个代理，因此一个进程等于一个出口身份。
from patchright.sync_api import sync_playwright
with sync_playwright() as p:
ctx = p.chromium.launch_persistent_context(
user_data_dir="profiles/it-01", # one profile per identity
channel="chrome",
headless=False,
no_viewport=True,
proxy={
"server": "http://gate.quantumproxies.io:PORT",
"username": "USER-country-it-session-it01", # sticky, pinned to the profile
"password": "PASS",
},
# do NOT pass user_agent or extra_http_headers here
)
page = ctx.new_page()
page.goto("https://example.com")
ctx.close()因此旋转成为一个进程级别的决策：每个身份一个配置文件目录，一个粘性会话固定在上面，并使用工作池而不是上下文循环。保持配对稳定——一个在意大利出口后累积了 cookie 的配置文件然后在巴西出口后重新出现是一个没有 CDP 补丁可以隐藏的矛盾。实用规则：以会话 ID 命名目录，烧掉会话时删除目录，永远不要在两个出口之间共享一个配置文件。
在代理后面的 Docker 中运行 Patchright
将隐身浏览器容器化有两个陷阱，且都与代理有关。第一个是--no-sandbox：通常用于修复 Chrome 作为 root 启动失败的问题，而反机器人供应商乐于读取的标志。改为以非 root 用户身份运行。第二个是无头模式——项目推荐有头模式，因此使用虚拟显示而不是使用无头开关：
# Dockerfile
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
xvfb ca-certificates && rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir patchright \
&& patchright install --with-deps chrome
RUN useradd -m app
USER app
WORKDIR /home/app
COPY --chown=app:app scrape.py .
# headed under a virtual display: no --no-sandbox, no HeadlessChrome tell
CMD ["xvfb-run", "-a", "python", "scrape.py"]
# build & run:
# docker build -t patchright-worker .
# docker run --ipc=host --shm-size=1g patchright-worker--ipc=host和更大的/dev/shm是 Chromium-in-Docker 的标准修复，用于在负载下防止标签崩溃，直接来自 Playwright 容器文档。一个特定于代理的陷阱：如果您运行本地中继以向 SOCKS5 端点添加凭证，容器内的127.0.0.1是容器，而不是您的主机。要么将中继放在同一容器中，明确指定主机地址，或在共享网络上将中继作为 sidecar 运行。如果您使用持久上下文，请将配置文件目录放在卷上，否则每次容器重启都会丢弃您通过带宽获得的清除 cookie。
补丁覆盖的内容，以及它们永远不会覆盖的内容
了解您购买的内容是值得的。Patchright 的头条修复是Runtime.enable泄漏——它在隔离的执行上下文中运行 JavaScript，而不是启用暴露游戏的域。它禁用 Console API 以关闭Console.enable（因此page.on("console")日志记录消失了，这在调试代理故障时是一个真正的成本）。它重写了 Playwright 的默认标志：添加--disable-blink-features=AutomationControlled，移除--enable-automation，并恢复--disable-popup-blocking、--disable-component-update、--disable-default-apps和--disable-extensions。它还使用普通定位器进入关闭的阴影根。
也将该标志列表视为带宽项目。恢复组件更新和默认应用意味着浏览器在后台拨打电话——通过您的计量出口。在扩展之前测量会话的传输，并在上下文中阻止图像、字体和媒体资源类型以降低每页成本。这些都不触及另一面墙：在烧毁的数据中心 IP 上的修补浏览器仍然是烧毁的 IP，并且请求在任何这些聪明才智被评估之前因信誉而被拒绝。在您得出补丁失败的结论之前，请使用免费的IP 质量检查器检查地址，并在浏览器下放置住宅代理，以便两层解决不同的问题。
常见问题解答
如何在 Patchright 中设置代理？
与 Playwright 中完全相同：将proxy={"server": "http://host:port", "username": "USER", "password": "PASS"}传递给chromium.launch()、launch_persistent_context()或new_context()。Patchright 不修补代理层，因此每个上游行为——绕过列表、回环例外——均不变。
Patchright 支持 SOCKS5 代理认证吗？
不，这是 Chromium 的限制，而不是 Patchright 的：Chromium 没有 SOCKS 凭证机制，因此认证的 SOCKS5 端点会失败。使用同一网关的 HTTP 端口和用户名、密码字段，或通过 IP 白名单认证并保持 SOCKS5 方案——每个 QuantumProxies 计划都支持白名单作为用户：密码的替代方案。完整的解决方案集在我们的Playwright SOCKS5 认证指南中，这里不变。
Patchright 可以在每个上下文中使用不同的代理吗？
可以，如果您以全局代理值启动浏览器——即使是占位符——因为 Chromium 仅在启动时存在代理时启用每上下文代理。例外是 Patchright 推荐的隐身持久上下文设置：这给您一个单一上下文，因此旋转意味着一个具有自己配置文件目录的单独进程。
Patchright 仅限于 Chromium 吗？
是的。项目明确表示仅修补基于 Chromium 的浏览器；Firefox 和 WebKit 不受支持。如果您需要 Firefox 引擎隐身和从代理出口派生的地理位置，那是另一个工具——请参阅我们的Camoufox 代理和 geoip 指南。
使用 Patchright 仍会被阻止吗？
在硬目标上，是的。独立测试显示无头模式仍然泄露 HeadlessChrome 标志，以及修补浏览器到达但无法清除的挑战页面。补丁关闭了廉价的自动化检查；IP 信誉、TLS 指纹和挑战解决是需要单独答案的独立问题。
将 Patchright 视为它本身：一个非常好的修复特定泄漏类别的工具，无需您重写 Playwright 的一行代码。将其与清洁的出口配对，在身份重要时保持粘性，并在运行前验证——那么剩下的失败实际上是关于目标，而不是您的设置。这是技术指导，而不是法律建议：在法律和网站条款内自动化。