# Patchright 代理设置：启动、上下文、认证和 Docker

Patchright 在浏览器启动前修补了 Playwright 的 CDP 泄漏。它不会影响您的 IP 信誉——其推荐的隐身设置悄然改变了您旋转代理的方式。

Patchright 是一个经过修补的、未检测到的 Playwright 构建，作为替代品使用：更改导入，保持代码不变。补丁在**浏览器进程启动之前**应用——它们移除了自动化标志和 Chrome DevTools 协议调用，这些调用会在 Playwright 会话的最初几毫秒内让网站识别。它们不触及的是网络。每个 Patchright 代理问题都回到这种分裂，以及 README 掩盖的一个细节：项目推荐的最大隐身设置是持久上下文，这悄然改变了您旋转出口的方式。这是一个以代理为重点的指南——启动与上下文、认证网关、Docker，以及对上限的诚实描述。

## 安装和替代代理

Patchright 支持 Python、Node 和 .NET，仅修补 Chromium——明确不支持 Firefox 和 WebKit。安装它并拉取真实的 Google Chrome 而不是捆绑的 Chromium，这是项目推荐的隐身方式：

```bash
pip install patchright
patchright install chrome
# Node: npm i patchright && npx patchright install chrome
```

代理 API 是 Playwright 的，未更改，因为代理是 Patchright 故意不动的少数几个东西之一。凭证放在专用字段中，绝不放在服务器 URL 内——这就是为什么认证代理在这里不需要扩展补丁，不像 Selenium 或原始 Puppeteer：

```python
from patchright.sync_api import sync_playwright

PROXY = {
    "server": "http://residentialpremium.quantumproxies.io:8080",
    "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 代理集成指南](https://quantumproxies.io/blog/playwright-proxy-integration)涵盖了基本行为，[反检测框架代理地图](https://quantumproxies.io/blog/anti-detect-frameworks-authenticated-proxies-map)比较了哪些堆栈本身接受凭证。

## 每上下文代理和全局存根

上下文是廉价的旋转单元：独立的 cookie、存储和缓存，在毫秒内创建，而不是浏览器启动所需的几秒。每个都采用自己的`proxy`选项，因此单个进程可以同时持有美国身份和德国身份。这里有一个记录在案的 Playwright 陷阱让人们困惑——浏览器必须以全局代理启动，以便每上下文代理在 Chromium 上工作。如果每个上下文都覆盖它，全局值将永远不会被使用，可以是任何占位符字符串：

```js
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://residentialpremium.quantumproxies.io:8080',
        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+ 住宅池中的不同地址离开，您的端无需列表管理——这就是[旋转代理](https://quantumproxies.io/rotating-proxies)在服务器端的作用。注意片段中地理和会话控制的位置：在用户名中，而不是自定义头中。这在 Patchright 中比在普通 Playwright 中更重要，因为项目本身的指导是避免自定义头和用户代理覆盖，因为注入的值本身就是检测面。用户名参数控制保持浏览器的请求形状不变。

![在 Patchright 中使用代理的两种方式：启动浏览器后为每个上下文分配独立代理，以便快速轮换；或使用项目为隐身推荐的持久上下文，它只有一个上下文，因此每个进程只有一个出口。卡片注明了按上下文设置代理时所需的全局代理占位配置。](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785776555/blog/generated/qp-b10-009-diag1.png)
*没有人说出的权衡：快速旋转存在于上下文中，最大隐身存在于持久配置文件中——而持久配置文件只有一个上下文。*

## 持久上下文的权衡

Patchright 推荐的隐身配置不是`launch()`。而是`launch_persistent_context()`，使用真实的 Chrome 通道、用户数据目录、无视口覆盖和有头模式——并明确没有自定义头或伪造的用户代理。该设置还会保留挑战提供的任何清除 cookie，因此解决的挑战可以在运行之间重复使用。代理的结果是结构性的：持久上下文*就是*上下文。没有`newContext()`来挂载第二个代理，因此一个进程等于一个出口身份。

```python
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://residentialpremium.quantumproxies.io:8080",
            "username": "USER-country-it-sid-it01-ttl-30m",   # 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 用户身份运行。第二个是无头模式——项目推荐有头模式，因此使用虚拟显示而不是使用无头开关：

```bash
# 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 质量检查器](https://quantumproxies.io/ip-checker)检查地址，并在浏览器下放置[住宅代理](https://quantumproxies.io/residential-proxies)，以便两层解决不同的问题。

![Patchright 的补丁通过堵住 Runtime.enable 泄漏并改写启动参数来通过自动化检测，但信誉已受损的出口 IP 在这些内容被读取之前就会因信誉而被拒绝。卡片把两项职责分开：补丁决定浏览器自称是什么，代理决定它看起来来自哪里。](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785776555/blog/generated/qp-b10-009-diag2.png)
*补丁决定浏览器对自身的描述。代理决定它看起来来自哪里。修复一个而忽略另一个仍然会导致阻止。*

## 常见问题解答

### 如何在 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 认证指南](https://quantumproxies.io/blog/playwright-socks5-proxy-authentication)中，这里不变。

### Patchright 可以在每个上下文中使用不同的代理吗？

可以，如果您以全局代理值启动浏览器——即使是占位符——因为 Chromium 仅在启动时存在代理时启用每上下文代理。例外是 Patchright 推荐的隐身持久上下文设置：这给您一个单一上下文，因此旋转意味着一个具有自己配置文件目录的单独进程。

### Patchright 仅限于 Chromium 吗？

是的。项目明确表示仅修补基于 Chromium 的浏览器；Firefox 和 WebKit 不受支持。如果您需要 Firefox 引擎隐身和从代理出口派生的地理位置，那是另一个工具——请参阅我们的[Camoufox 代理和 geoip 指南](https://quantumproxies.io/blog/camoufox-proxy-geoip)。

### 使用 Patchright 仍会被阻止吗？

在硬目标上，是的。独立测试显示无头模式仍然泄露 HeadlessChrome 标志，以及修补浏览器到达但无法清除的挑战页面。补丁关闭了廉价的自动化检查；IP 信誉、TLS 指纹和挑战解决是需要单独答案的独立问题。

将 Patchright 视为它本身：一个非常好的修复特定泄漏类别的工具，无需您重写 Playwright 的一行代码。将其与清洁的出口配对，在身份重要时保持粘性，并在运行前验证——那么剩下的失败实际上是关于目标，而不是您的设置。这是技术指导，而不是法律建议：在法律和网站条款内自动化。

[在干净的住宅出口上使用 Patchright](https://quantumproxies.io/residential-proxies)