Configuração de Proxy Patchright: Lançamento, Contextos, Autenticação e Docker

Patchright corrige os vazamentos do CDP que expõem o Playwright antes do navegador iniciar. Ele não afeta a reputação do seu IP — e sua configuração furtiva recomendada muda silenciosamente como você rotaciona proxies.

Patchright é uma versão corrigida e indetectável do Playwright que funciona como um substituto direto: altere a importação, mantenha o código. Os patches são aplicados antes do processo do navegador iniciar — eles removem as flags de automação e as chamadas do Chrome DevTools Protocol que permitem que um site identifique uma sessão do Playwright em seus primeiros milissegundos. O que eles não tocam é a rede. Toda questão de proxy Patchright volta a essa divisão, e a um detalhe que o README esconde: a configuração que o projeto recomenda para máxima furtividade é um contexto persistente, que muda silenciosamente como você rotaciona saídas. Este é o guia focado em proxy — lançamento versus contexto, gateways autenticados, Docker, e uma descrição honesta do limite.

Instalação e o proxy substituto

Patchright é distribuído para Python, Node e .NET, e apenas corrige o Chromium — Firefox e WebKit são explicitamente não suportados. Instale-o e baixe o Google Chrome real em vez do Chromium incluído, que o projeto recomenda para furtividade:

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

A API de proxy é a do Playwright, inalterada, porque proxies são uma das poucas coisas que Patchright deliberadamente deixa inalteradas. As credenciais vão em campos dedicados, nunca dentro da URL do servidor — é por isso que proxies autenticados não precisam de uma extensão aqui, ao contrário do Selenium ou do Puppeteer puro:

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()

Essa é toda a resposta para "o Patchright suporta proxies": sim, idêntico ao Playwright original, incluindo a lista de bypass e a peculiaridade do Chromium de que endereços de loopback ignoram completamente o proxy — então testar contra um servidor local simulado sempre parecerá que o proxy está sendo ignorado. Se você é novo no modelo subjacente, nosso guia de integração de proxy Playwright cobre o comportamento básico, e o mapa de proxy de frameworks anti-detecção compara quais pilhas aceitam credenciais nativamente.

Proxies por contexto e o stub global

Contextos são a unidade de rotação barata: cookies, armazenamento e cache separados, criados em milissegundos em vez dos segundos que um lançamento de navegador custa. Cada um leva sua própria opção de proxy, então um único processo pode manter uma identidade dos EUA e uma identidade alemã ao mesmo tempo. Há uma pegadinha documentada do Playwright que confunde as pessoas aqui — o navegador deve ser lançado com um proxy global para que proxies por contexto funcionem no Chromium. Se cada contexto o substituir, o valor global nunca é usado e pode ser qualquer string de espaço reservado:

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();
})();

Apontado para um gateway rotativo, cada contexto sai de um endereço diferente em um pool residencial de mais de 90 milhões sem gerenciamento de lista do seu lado — é isso que proxies rotativos fazem no lado do servidor. Observe onde os controles de geo e sessão estão nesse trecho: no nome de usuário, não em um cabeçalho personalizado. Isso importa mais no Patchright do que no Playwright puro, porque a orientação do projeto é evitar cabeçalhos personalizados e substituições de user-agent, já que valores injetados são, por si mesmos, uma superfície de detecção. O controle por parâmetro de nome de usuário mantém a forma do pedido do navegador intacta.

O equilíbrio do contexto persistente

A configuração de furtividade recomendada pelo Patchright não é launch(). É launch_persistent_context() com um canal Chrome real, um diretório de dados do usuário, sem substituição de viewport e modo com interface — e explicitamente sem cabeçalhos personalizados ou um user agent falsificado. Essa configuração também persiste quaisquer cookies de liberação que um desafio lhe entregue, então um desafio resolvido é reutilizável em execuções. A consequência do proxy é estrutural: um contexto persistente é o contexto. Não há newContext() para pendurar um segundo proxy, então um processo equivale a uma identidade de saída.

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()

Então a rotação se torna uma decisão a nível de processo: um diretório de perfil por identidade, uma sessão fixa presa a ele, e um pool de trabalhadores em vez de um loop de contexto. Mantenha o emparelhamento estável — um perfil que acumulou cookies atrás de uma saída italiana e depois reaparece atrás de uma brasileira é uma contradição que nenhum patch de CDP pode esconder. Regra prática: nomeie o diretório após o id da sessão, exclua o diretório quando você queimar a sessão, e nunca compartilhe um perfil entre duas saídas.

Executando Patchright no Docker atrás de um proxy

Containerizar um navegador furtivo tem duas armadilhas, e ambas têm consequências de proxy. A primeira é --no-sandbox: a correção usual para o Chrome se recusar a iniciar como root, e uma flag que os fornecedores anti-bot leem com prazer. Execute como um usuário não-root em vez disso. A segunda é o modo headless — o projeto recomenda com interface, então use uma exibição virtual em vez de recorrer ao modo headless:

# 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

Os --ipc=host e o maior /dev/shm são as correções padrão do Chromium-no-Docker para falhas de aba sob carga, direto dos documentos de contêiner do Playwright. Uma armadilha específica de proxy: se você executar um relé local para adicionar credenciais a um endpoint SOCKS5, 127.0.0.1 dentro do contêiner é o contêiner, não seu host. Ou coloque o relé no mesmo contêiner, enderece o host explicitamente, ou execute o relé como um sidecar em uma rede compartilhada. E mantenha o diretório de perfil em um volume se você estiver usando contextos persistentes, caso contrário, cada reinício do contêiner descarta os cookies de liberação que você pagou largura de banda para ganhar.

O que os patches cobrem, e o que nunca cobrirão

Vale a pena saber exatamente o que você está comprando. A correção principal do Patchright é o vazamento Runtime.enable — ele executa JavaScript em contextos de execução isolados em vez de habilitar o domínio que entrega o jogo. Ele desativa a API do Console para fechar Console.enable (então o registro page.on("console") desaparece, o que é um custo real quando você está depurando uma falha de proxy). Ele reescreve as flags padrão do Playwright: adiciona --disable-blink-features=AutomationControlled, remove --enable-automation, e coloca de volta --disable-popup-blocking, --disable-component-update, --disable-default-apps e --disable-extensions. Ele também alcança raízes de sombra fechadas com localizadores comuns.

Leia essa lista de flags como um item de linha de largura de banda também. Restaurar atualizações de componentes e aplicativos padrão significa um navegador que se comunica em segundo plano — através da sua saída medida. Meça a transferência de uma sessão antes de escalar, e bloqueie tipos de recursos de imagem, fonte e mídia no contexto para manter o custo por página baixo. Nada disso toca na outra parede: um navegador corrigido em um IP de datacenter queimado ainda é um IP queimado, e o pedido é recusado por reputação antes que qualquer uma dessas inteligências seja avaliada. Verifique um endereço com o verificador de qualidade de IP gratuito antes de concluir que os patches falharam, e coloque proxies residenciais sob o navegador para que as duas camadas estejam resolvendo problemas diferentes.

Perguntas frequentes

Como configuro um proxy no Patchright?

Exatamente como no Playwright: passe proxy={"server": "http://host:port", "username": "USER", "password": "PASS"} para chromium.launch(), launch_persistent_context() ou new_context(). Patchright não corrige a camada de proxy, então todo comportamento original — a lista de bypass, a exceção de loopback — se aplica inalterado.

O Patchright suporta autenticação de proxy SOCKS5?

Não, e é uma limitação do Chromium em vez de uma do Patchright: o Chromium não tem mecanismo para credenciais SOCKS, então endpoints SOCKS5 autenticados falham. Use a porta HTTP do mesmo gateway com os campos de nome de usuário e senha, ou autentique por lista de permissões de IP e mantenha o esquema SOCKS5 — todo plano da QuantumProxies suporta lista de permissões como alternativa ao usuário:senha. O conjunto completo de soluções alternativas está em nosso guia de autenticação SOCKS5 no Playwright, que se aplica inalterado aqui.

O Patchright pode usar um proxy diferente por contexto?

Sim, se você lançou o navegador com um valor de proxy global — mesmo que seja um espaço reservado — porque o Chromium só habilita proxies por contexto quando um está presente no lançamento. A exceção é a configuração de contexto persistente que o Patchright recomenda para furtividade: isso lhe dá um único contexto, então a rotação significa um processo separado com seu próprio diretório de perfil.

O Patchright é apenas para Chromium?

Sim. O projeto afirma claramente que apenas navegadores baseados em Chromium são corrigidos; Firefox e WebKit não são suportados. Se você precisa de furtividade no motor Firefox com geo derivado da saída do proxy, essa é uma ferramenta diferente — veja nosso guia de proxy e geoip Camoufox.

Ainda sou bloqueado com o Patchright?

Em alvos difíceis, sim. Testes independentes mostram que o modo headless ainda vaza um indicativo de HeadlessChrome, e páginas de desafio que um navegador corrigido alcança mas não consegue limpar. Os patches fecham as verificações de automação baratas; reputação de IP, impressões digitais de TLS e resolução de desafios são problemas separados que precisam de respostas separadas.

Trate o Patchright pelo que ele é: uma solução muito boa para uma classe específica de vazamento, entregue sem pedir que você reescreva uma linha de Playwright. Emparelhe-o com saídas que sejam limpas, fixas onde a identidade importa, e verificadas antes da execução — então as falhas restantes são realmente sobre o alvo, não sobre sua configuração. Este é um guia técnico, não um conselho legal: automatize dentro da lei e dos termos do site.

Coloque o Patchright em saídas residenciais limpas