Configuración de Proxy Patchright: Lanzamiento, Contextos, Autenticación y Docker

Patchright corrige las filtraciones de CDP que exponen Playwright antes de que el navegador comience. No afecta la reputación de tu IP, y su configuración sigilosa recomendada cambia silenciosamente cómo rotas proxies.

Patchright es una versión parcheada y no detectada de Playwright que funciona como un reemplazo directo: cambia la importación, mantén el código. Los parches se aplican antes de que el proceso del navegador comience: eliminan las banderas de automatización y las llamadas del Chrome DevTools Protocol que permiten a un sitio identificar una sesión de Playwright en sus primeros milisegundos. Lo que no tocan es la red. Cada pregunta sobre el proxy Patchright regresa a esa división y a un detalle que el README oculta: la configuración que el proyecto recomienda para el máximo sigilo es un contexto persistente, que cambia silenciosamente cómo rotas las salidas. Esta es la guía enfocada en el proxy: lanzamiento versus contexto, puertas de enlace autenticadas, Docker y un relato honesto del límite.

Instalación y el proxy directo

Patchright se distribuye para Python, Node y .NET, y solo parchea Chromium: Firefox y WebKit no son compatibles explícitamente. Instálalo y descarga Google Chrome real en lugar del Chromium incluido, que el proyecto recomienda para sigilo:

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

La API de proxy es la de Playwright, sin cambios, porque los proxies son una de las pocas cosas que Patchright deja deliberadamente intactas. Las credenciales van en campos dedicados, nunca dentro de la URL del servidor, por lo que los proxies autenticados no necesitan un complemento aquí, a diferencia de Selenium o Puppeteer sin modificar:

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

Esa es toda la respuesta a "¿Patchright soporta proxies?": sí, idéntico a Playwright original, incluyendo la lista de bypass y la peculiaridad de Chromium de que las direcciones de loopback omiten el proxy por completo, por lo que probar contra un servidor simulado local siempre parecerá que el proxy está siendo ignorado. Si eres nuevo en el modelo subyacente, nuestra guía de integración de proxy Playwright cubre el comportamiento básico, y el mapa de proxies de frameworks anti-detección compara qué pilas aceptan credenciales de forma nativa.

Proxies por contexto y el stub global

Los contextos son la unidad de rotación económica: cookies, almacenamiento y caché separados, creados en milisegundos en lugar de los segundos que cuesta un lanzamiento de navegador. Cada uno toma su propia opción de proxy, por lo que un solo proceso puede tener una identidad de EE.UU. y una identidad alemana al mismo tiempo. Hay un problema documentado de Playwright que confunde a la gente aquí: el navegador debe ser lanzado con un proxy global para que los proxies por contexto funcionen en Chromium. Si cada contexto lo sobrescribe, el valor global nunca se usa y puede ser cualquier cadena de marcador de posición:

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

Apuntado a una puerta de enlace rotativa, cada contexto sale desde una dirección diferente en un grupo residencial de más de 90 millones sin gestión de lista de tu parte: eso es lo que hacen los proxies rotativos del lado del servidor. Nota dónde viven los controles de geolocalización y sesión en ese fragmento: en el nombre de usuario, no en un encabezado personalizado. Eso importa más en Patchright que en Playwright simple, porque la propia guía del proyecto es evitar encabezados personalizados y sobrescrituras de user-agent, ya que los valores inyectados son en sí mismos una superficie de detección. El control de parámetros en el nombre de usuario mantiene la forma de la solicitud del navegador intacta.

El compromiso de contexto persistente

La configuración de sigilo recomendada por Patchright no es launch(). Es launch_persistent_context() con un canal de Chrome real, un directorio de datos de usuario, sin sobrescritura de viewport y en modo con interfaz gráfica, y explícitamente sin encabezados personalizados ni un user-agent falsificado. Esa configuración también persiste cualquier cookie de autorización que un desafío te entregue, por lo que un desafío resuelto es reutilizable en ejecuciones posteriores. La consecuencia del proxy es estructural: un contexto persistente es el contexto. No hay newContext() para colgar un segundo proxy, por lo que un proceso equivale a una identidad de salida.

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

Así que la rotación se convierte en una decisión a nivel de proceso: un directorio de perfil por identidad, una sesión fija vinculada a él, y un grupo de trabajadores en lugar de un bucle de contexto. Mantén el emparejamiento estable: un perfil que acumuló cookies detrás de una salida italiana y luego reaparece detrás de una brasileña es una contradicción que ningún parche de CDP puede ocultar. Regla práctica: nombra el directorio según el id de sesión, elimina el directorio cuando quemes la sesión, y nunca compartas un perfil entre dos salidas.

Ejecutando Patchright en Docker detrás de un proxy

Contenerizar un navegador sigiloso tiene dos trampas, y ambas tienen consecuencias para el proxy. La primera es --no-sandbox: la solución habitual para que Chrome se niegue a iniciar como root, y una bandera que los proveedores anti-bot leen con gusto. Ejecuta como un usuario que no sea root en su lugar. La segunda es el modo sin interfaz gráfica: el proyecto recomienda con interfaz gráfica, así que usa una pantalla virtual en lugar de recurrir al modo sin interfaz gráfica:

# 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

Las opciones --ipc=host y un /dev/shm más grande son las soluciones estándar de Chromium-en-Docker para los bloqueos de pestañas bajo carga, directamente de los documentos del contenedor de Playwright. Una trampa específica del proxy: si ejecutas un relé local para agregar credenciales a un endpoint SOCKS5, 127.0.0.1 dentro del contenedor es el contenedor, no tu host. O bien coloca el relé en el mismo contenedor, dirige al host explícitamente, o ejecuta el relé como un sidecar en una red compartida. Y mantén el directorio de perfil en un volumen si estás usando contextos persistentes, de lo contrario, cada reinicio del contenedor desecha las cookies de autorización que pagaste con ancho de banda para ganar.

Qué cubren los parches, y qué nunca cubrirán

Vale la pena saber exactamente qué estás comprando. La corrección principal de Patchright es la filtración de Runtime.enable: ejecuta JavaScript en contextos de ejecución aislados en lugar de habilitar el dominio que revela el juego. Desactiva la API de la Consola para cerrar Console.enable (por lo que el registro de page.on("console") desaparece, lo cual es un costo real cuando estás depurando una falla de proxy). Reescribe las banderas predeterminadas de Playwright: agrega --disable-blink-features=AutomationControlled, elimina --enable-automation, y vuelve a poner --disable-popup-blocking, --disable-component-update, --disable-default-apps y --disable-extensions. También alcanza raíces de sombra cerradas con localizadores ordinarios.

Lee esa lista de banderas como un elemento de línea de ancho de banda también. Restaurar actualizaciones de componentes y aplicaciones predeterminadas significa un navegador que se comunica en segundo plano, a través de tu salida medida. Mide la transferencia de una sesión antes de escalar, y bloquea tipos de recursos de imagen, fuente y medios en el contexto para mantener el costo por página bajo. Nada de esto toca la otra pared: un navegador parcheado en una IP de centro de datos quemada sigue siendo una IP quemada, y la solicitud es rechazada por reputación antes de que se evalúe cualquiera de estas ingeniosidades. Verifica una dirección con el verificador de calidad de IP gratuito antes de concluir que los parches fallaron, y coloca proxies residenciales bajo el navegador para que las dos capas resuelvan diferentes problemas.

Preguntas frecuentes

¿Cómo configuro un proxy en Patchright?

Exactamente como en Playwright: pasa proxy={"server": "http://host:port", "username": "USER", "password": "PASS"} a chromium.launch(), launch_persistent_context() o new_context(). Patchright no parchea la capa de proxy, por lo que todo el comportamiento original, la lista de bypass, la excepción de loopback, se aplica sin cambios.

¿Patchright soporta autenticación de proxy SOCKS5?

No, y es una limitación de Chromium más que de Patchright: Chromium no tiene mecanismo para credenciales SOCKS, por lo que los endpoints SOCKS5 autenticados fallan. Usa el puerto HTTP de la misma puerta de enlace con los campos de nombre de usuario y contraseña, o autentica por lista blanca de IP y mantén el esquema SOCKS5: cada plan de QuantumProxies soporta la lista blanca como alternativa a usuario:contraseña. El conjunto completo de soluciones alternativas está en nuestra guía de autenticación de proxy SOCKS5 de Playwright, que se aplica sin cambios aquí.

¿Puede Patchright usar un proxy diferente por contexto?

Sí, si lanzaste el navegador con un valor de proxy global, incluso un marcador de posición, porque Chromium solo habilita proxies por contexto cuando uno está presente al inicio. La excepción es la configuración de contexto persistente que Patchright recomienda para sigilo: eso te da un solo contexto, por lo que la rotación significa un proceso separado con su propio directorio de perfil.

¿Patchright es solo para Chromium?

Sí. El proyecto declara claramente que solo los navegadores basados en Chromium están parcheados; Firefox y WebKit no son compatibles. Si necesitas sigilo con motor Firefox con geolocalización derivada de la salida del proxy, eso es una herramienta diferente: consulta nuestra guía de proxy y geoip de Camoufox.

¿Aún me bloquean con Patchright?

En objetivos difíciles, sí. Las pruebas independientes muestran que el modo sin interfaz gráfica aún filtra un indicio de HeadlessChrome, y páginas de desafío que un navegador parcheado alcanza pero no puede superar. Los parches cierran las verificaciones de automatización baratas; la reputación de IP, las huellas digitales TLS y la resolución de desafíos son problemas separados que necesitan respuestas separadas.

Trata a Patchright como lo que es: una muy buena solución para una clase específica de filtración, entregada sin pedirte que reescribas una línea de Playwright. Combínalo con salidas que sean limpias, fijas donde la identidad importa, y verificadas antes de la ejecución: entonces los fallos restantes son realmente sobre el objetivo, no sobre tu configuración. Esta es una guía técnica, no un consejo legal: automatiza dentro de la ley y los términos del sitio.

Pon Patchright en salidas residenciales limpias