¿El proxy de Playwright no funciona? Guías completas de configuración en 2026.
TL;DR
Un proxy de Playwright generalmente falla porque su servidor, credenciales, protocolo o alcance son incorrectos—no porque Playwright carezca de soporte para proxies.
Coloca un proxy en chromium.launch({ proxy }) para todo el navegador, o en browser.newContext({ proxy }) para un contexto aislado. La versión actual de Playwright no requiere un proxy de nivel de lanzamiento falso antes de un proxy de contexto.
En Playwright Test, configura el tráfico en tiempo de ejecución con use.proxy; HTTPS_PROXY para npx playwright install solo controla el proceso de descarga del navegador.
Un HTTP 407 significa que el proxy rechazó la autenticación. Una respuesta objetivo como 403 o 429 generalmente significa que la conexión del proxy funcionó y el destino rechazó o limitó la solicitud.
Verifica la ruta en capas: prueba la puerta de enlace, carga un pequeño endpoint autorizado, luego inspecciona las solicitudes fallidas de la página real y realiza un trazado.
Mantén una sesión de proxy por contexto lógico del navegador, almacena las credenciales fuera del código fuente y usa solo objetivos públicos o autorizados.
¿Por qué no funciona tu proxy de Playwright?
Es muy probable que tu proxy de Playwright no funcione porque la configuración del proxy está mal formada, se aplica en el alcance incorrecto, es inalcanzable desde el tiempo de ejecución, o es rechazada durante la autenticación. Playwright actualmente admite servidores proxy HTTP, HTTPS y SOCKS5 a nivel de navegador o contexto de navegador, como se documenta en la guía de red oficial de Playwright. El mismo objeto de proxy estándar puede conectarse a una puerta de enlace de proxy residencial Nstdata generada sin un SDK de navegador específico del proveedor.
Comienza clasificando el síntoma en lugar de cambiar repetidamente el código:
Síntoma
Capa más probable
Primera comprobación
ERR_PROXY_CONNECTION_FAILED
Ruta de red
Host, puerto, DNS, alcanzabilidad del contenedor
ERR_TUNNEL_CONNECTION_FAILED
Túnel de proxy
Protocolo, capacidad de la puerta de enlace, política upstream
HTTP 407
Autenticación de proxy
Nombre de usuario, contraseña, estado de la cuenta
HTTP 403 o 429
Respuesta del destino
Permisos del objetivo, tasa, consistencia de la sesión
La página se carga pero la IP no cambia
Alcance de configuración o bypass
Configuración de lanzamiento/contexto y reglas de bypass
Tiempo de espera de navegación
Calidad del proxy o activos de la página
Un endpoint simple, fallos en solicitudes, trazado
Error de autoridad de certificación
Inspección de TLS o CA privada
Cadena de certificados y configuración de CA confiable
Esta distinción es importante: un 407 es un error de proxy, mientras que un 403 devuelto por el sitio web no es prueba de que Playwright ignoró el proxy. El resto de esta guía construye una configuración conocida y luego aísla cada capa.
¿Qué necesitas antes de configurar un proxy de Playwright?
Utiliza un entorno de ejecución de Node.js actual, una versión actual de Playwright y un conjunto completo de credenciales de proxy. Las comprobaciones en vivo para esta guía utilizaron Node.js 22.23.2 con Playwright 1.62.1 y Python 3.12 con Playwright 1.62.0 el 6 de agosto de 2026. El paquete npm actual requiere Node.js 20 o una versión más nueva.
Para Node.js, crea un proyecto limpio e instala Playwright:
Para cada proxy, recolecta estos valores por separado:
servidor: el esquema, host y puerto, como http://proxy.ejemplo:8000
nombre de usuario: la cuenta de proxy o el nombre de usuario de sesión generado
contraseña: el secreto correspondiente
bypass: hosts opcionales separados por comas que deberían conectarse directamente
No pegues el nombre de usuario y la contraseña en servidor. Playwright expone campos de credenciales separados, y mantenerlos separados evita fallos en el análisis de URL cuando una contraseña contiene @, :, o /.
Echa un vistazo rápido
Genera una credencial actual de canal Nstdata, pruébala contra un pequeño endpoint autorizado y luego aplica la misma configuración de proxy a Playwright.
Establezca las tres variables de entorno a través del mecanismo de secretos del despliegue. Registre el estado HTTP para diagnóstico, pero oculte la IP devuelta y nunca imprima la contraseña. Un punto final de IP pública es útil para una verificación de ruta de una sola solicitud; no debería convertirse en un chequeo de salud de alta frecuencia.
La configuración equivalente de Nstdata utiliza la puerta de enlace en `PROXY_SERVER` y los valores de Canal generados en `PROXY_USERNAME` y `PROXY_PASSWORD`. Cópielos desde el panel de control autenticado porque los parámetros de ubicación y sesión pueden estar incrustados en el nombre de usuario generado.
## ¿Cómo se configura un proxy en Playwright Test?
Utilice `use.proxy` en `playwright.config.js` cuando las pruebas deban compartir un proxy en tiempo de ejecución. La <a href="https://playwright.dev/docs/test-use-options" rel="nofollow noopener"><strong>referencia de opciones de uso de Playwright Test</strong></a> documenta esta configuración:
```javascript
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',
},
});
Luego ejecute el conjunto con secretos proporcionados por el shell o la plataforma CI:
PROXY_SERVER="http://proxy.example:8000"\PROXY_USERNAME="tu-nombre-de-usuario-generado"\PROXY_PASSWORD="tu-secreto"\npx playwright test
Esta configuración se cargó con Playwright Test 1.62.1 durante la verificación. Mantenga el archivo de configuración libre de credenciales activas para que se pueda comprometer de forma segura.
¿Necesita un marcador de lanzamiento un proxy a nivel de contexto de Playwright?
No. El Playwright actual puede lanzar Chromium sin un proxy y aplicar un proxy directamente a browser.newContext(). La API del proxy Browser.newContext documenta explícitamente la opción de contexto y sus campos server, username, password y bypass.
Este comportamiento exacto también se probó localmente con Playwright 1.62.1, un proxy HTTP con autenticación básica y un objetivo HTTP controlado: la solicitud de contexto devolvió 200 a través del proxy sin ningún marcador de lanzamiento. Los tutoriales de terceros más antiguos que requieren un proxy de lanzamiento per-context no son una descripción confiable de la API actual.
El enrutamiento a nivel de contexto es útil cuando un proceso necesita varias identidades o regiones aisladas. Cree un contexto por sesión lógica y ciérrelo después de esa sesión. No cambie un proxy a mitad de un inicio de sesión o un flujo de varios pasos porque las cookies, la reputación de IP y el estado de sesión del lado del servidor pueden ya no estar de acuerdo.
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("Estado HTTP:", response.status if response elseNone)print(page.text_content("body")) browser.close()
El patrón de Python se ejecutó en vivo con Playwright 1.62.0 contra un proxy local controlado y devolvió un HTTP 200 a través de ese proxy. Si ya se está utilizando Python asíncrono, aplique el mismo diccionario proxy a async_playwright().chromium.launch() y espere cada operación.
¿Cómo verificar que Playwright está utilizando realmente el proxy?
Verifica la ruta en tres etapas para que una página complicada no oculte la verdadera falla.
1. Prueba el proxy de forma independiente
Usa curl desde la misma máquina o contenedor que ejecuta Playwright:
Si curl no puede conectarse, arregla el nombre de host, puerto, cortafuegos, credenciales o cuenta antes de depurar el código del navegador. Si curl tiene éxito pero Playwright falla, compara el esquema exacto y los valores de credenciales utilizados por ambos procesos.
2. Carga un pequeño punto final autorizado
Ejecuta el ejemplo mínimo de lanzamiento y verifica tanto el estado HTTP como la IP de salida reportada. Compárala con una solicitud directa, pero redacta ambos valores de los registros compartidos. Una IP diferente más HTTP 200 confirma el enrutamiento; no confirma que una aplicación completa funcionará.
3. Inspecciona las subsolicitudes de la página real
Las páginas modernas pueden renderizar HTML mientras que scripts, APIs, fuentes o imágenes fallan. Añade oyentes temporales:
Estos eventos revelan si la falla es a nivel de transporte o una respuesta HTTP. Retén un rastro de Playwright en caso de falla e inséctalo localmente; los rastros pueden contener URLs, cabeceras, contenido de la página y otros datos sensibles, así que restringe el acceso y la retención.
¿Cómo solucionas los errores más comunes de proxy en Playwright?
Soluciona ERR_PROXY_CONNECTION_FAILED
Confirma que server incluya un esquema soportado y el puerto correcto. http://host:port significa que Playwright se conecta a un proxy HTTP; socks5://host:port significa SOCKS5. Un simple host:port se trata como HTTP, pero un esquema explícito es más fácil de auditar.
Prueba DNS y conectividad desde el entorno de ejecución real. En Docker, 127.0.0.1 y localhost se refieren al propio contenedor, no a la computadora anfitriona. Usa un nombre de servicio explícitamente accesible o una puerta de enlace de host aprobada en lugar de copiar una dirección solo de host en el contenedor.
Soluciona HTTP 407 Proxy Authentication Required
Una respuesta 407 significa que se llegó al proxy pero no aceptó las credenciales. Re-copia el nombre de usuario generado, rota la contraseña si puede haber sido filtrada, y confirma que la credencial siga activa. No intentes de nuevo una contraseña rechazada en un bucle apretado porque eso oscurece los registros y puede activar protecciones de cuenta.
Playwright acepta nombre de usuario y contraseña como valores separados. Evita construir manualmente cadenas http://user:pass@host, especialmente cuando los secretos contienen caracteres reservados.
Diagnostica respuestas 403 y 429
Una 403 o 429 generalmente proviene del destino, no del proxy. Confirma el origen de la respuesta en el rastro o las cabeceras, reduce la tasa de solicitudes, mantiene una sesión estable y verifica si se permite el acceso. La rotación de proxies no es un sustituto de la autorización y no debe usarse para evadir un bloqueo o límite de tasa.
Soluciona tiempos de espera y cargas parciales de páginas
Primero prueba un pequeño punto final. Si es rápido, registra los subrecursos fallidos en la página real. Luego aumenta el tiempo de espera solo después de identificar un trabajo lento legítimo; un número más grande no solucionará una puerta de enlace muerta o credenciales inválidas.
Limita la concurrencia en lugar de abrir un número ilimitado de contextos. Cada contexto puede crear múltiples conexiones y solicitudes en segundo plano, por lo que la concurrencia nominal de la página subestima la carga real. Usa reintentos solo para fallos de conexión y tiempo de espera transitorios, con un límite bajo y retroceso.
Soluciona errores de certificado
No hagas de ignoreHTTPSErrors: true la solución predeterminada. Un error de certificado puede indicar un proxy corporativo que intercepta, una autoridad certificadora privada o un punto final inesperado. Instala la CA aprobada en el almacén de confianza del entorno de ejecución y verifica su propiedad antes de confiar en ella.
¿Por qué HTTPS_PROXY no soluciona el tráfico de páginas en Playwright?
HTTPS_PROXY puede configurar la descarga del navegador realizada por npx playwright install; no es lo mismo que la opción de proxy en tiempo de ejecución de Playwright. La guía oficial de proxy para la instalación del navegador utiliza este patrón:
Después de la instalación, configura el tráfico de páginas con chromium.launch({ proxy }), browser.newContext({ proxy }), o use.proxy de Playwright Test. Trata la conectividad de descarga y la conectividad en tiempo de ejecución del navegador como dos verificaciones separadas.
¿Cómo afectan las reglas de bypass a las pruebas de proxy?
El valor opcional bypass es una lista separada por comas de dominios que deben conectarse directamente. Una entrada amplia o accidental puede hacer que una verificación de IP parezca sin cambios, incluso cuando el proxy está correctamente configurado para otros hosts:
Mantenga las reglas de bypass reducidas y documente por qué cada host necesita acceso directo. La verificación en vivo para esta guía confirmó que un objetivo controlado omitido devolvía directamente mientras que las solicitudes no omitidas atravesaban el proxy.
¿Cómo deberías rotar proxies sin romper sesiones de navegador?
Rote entre sesiones lógicas, no entre solicitudes dentro de un flujo de trabajo de navegador. Un mapeo práctico es una sesión de proxy a un contexto de navegador: las cookies, el almacenamiento local, la caché y la salida permanecen alineadas hasta que se cierra el contexto.
Si se necesita una nueva ruta, cierre el contexto antiguo, genere la próxima configuración de sesión aprobada y cree un nuevo contexto. Mantenga la concurrencia dentro de los límites del proveedor y el objetivo, agregue un retroceso para fallos transitorios y registre solo identificadores no sensibles necesarios para el diagnóstico. La guía de rotación de IP explica la diferencia entre rotación aleatoria y sesiones adhesivas, mientras que la guía de proxy HTTP cubre los fundamentos de túneles y autenticación.
¿Cuándo es Nstdata una opción práctica para Playwright?
Nstdata Residential Prime Proxies son una opción práctica cuando la prueba de navegador autorizada o la recopilación web pública necesitan enrutamiento residencial y controles de sesión gestionados. Playwright puede usar el gateway HTTP, HTTPS o SOCKS5 generado a través de su objeto proxy estándar, por lo que no se requiere un SDK específico del proveedor para el navegador. Un Canal separa la configuración del proxy del código de la aplicación, mientras que los parámetros de ubicación y sesión generados permiten a un operador seleccionar el comportamiento de enrutamiento requerido desde el panel actual. La continuidad de sesión adhesiva se puede mapear a un contexto de navegador, y la rotación puede ocurrir cuando comienza el siguiente contexto. Confirme la disponibilidad actual, la orientación, los paquetes y las opciones de sesión en el panel autenticado antes de dimensionar una carga de trabajo de producción.
Integración estándar de Playwright: Use el gateway generado con la configuración de proxy a nivel de lanzamiento, a nivel de contexto o de Playwright Test.
Control de sesión: Mantenga un valor de sesión generado estable para un flujo lógico, luego cámbielo para el siguiente contexto aprobado cuando se requiera rotación.
Configuración de ubicación: Elija la orientación disponible actual en el panel para localización legítima, verificación de anuncios o QA regional.
Separación de credenciales: Almacene las credenciales del Canal en un gestor de secretos en lugar de incrustarlas en archivos de prueba o trazas.
Nstdata no cambia los términos, reglas de acceso u obligaciones de privacidad de un sitio web. Úselo para objetivos públicos o autorizados, minimice los datos personales y deténgase cuando un destino o propietario de cuenta retire el permiso.
¿Cuál es el flujo de trabajo más rápido para solucionar problemas de proxy en Playwright?
Utilice esta secuencia desde el borde de la red hacia adentro:
Valide el host, el puerto, el esquema y las credenciales con curl desde el mismo entorno de ejecución.
Ejecute un script de Playwright de una sola página contra un pequeño punto final autorizado.
Confirme que la IP de salida cambió, luego ocúltela de la salida compartida.
Repita con el lanzamiento, el contexto o el alcance de Playwright Test previstos.
Active el registro de fallos en solicitudes y conserve una traza para una ejecución fallida.
Separe los fallos del proxy de las respuestas HTTP del objetivo, como 403 o 429.
Verifique DNS del contenedor, firewall, certificados, reglas de bypass y límites de recursos.
Agregue reintentos limitados solo después de que se conozca la clase de fallo.
Este flujo de trabajo evita el error más común: cambiar simultáneamente las banderas del navegador, los tiempos de espera y los proveedores de proxy sin saber qué capa falló.
Conclusión
Cuando un proxy de Playwright no funciona, comience con el alcance y el transporte: use el proxy de lanzamiento para todo el navegador, el proxy de contexto para sesiones aisladas, o use.proxy para Playwright Test. Verifique el gateway de manera independiente, mantenga las credenciales en campos separados y use eventos de solicitud más trazas para distinguir las fallas de conexión de las respuestas del destino. La actual Playwright admite proxies a nivel de contexto sin un marcador de lanzamiento, mientras que HTTPS_PROXY para la instalación del navegador sigue siendo una preocupación separada. Una vez que una solicitud autorizada mínima funcione, agregue la página real, la concurrencia controlada y la rotación de sesión una capa a la vez.
Configure un proxy de Playwright con Nstdata
Cree un Canal, copie el gateway y las credenciales generadas actuales y verifique una pequeña solicitud autorizada antes de ejecutar el flujo de trabajo completo del navegador.
P: ¿Por qué mi servidor proxy de Playwright no funciona aunque curl sí?
Playwright puede estar utilizando credenciales diferentes, un esquema de proxy diferente, una regla de bypass no intencionada o el alcance de configuración incorrecto. Compara los valores exactos, ejecuta un script de navegador mínimo y registra los eventos requestfailed antes de probar la página completa.
P: ¿Puede Playwright usar un proxy autenticado?
Sí. Coloca la URL del proxy en server y suministra username y password como campos separados en el nivel de lanzamiento, contexto o Prueba de Playwright.
P: ¿Puede cada contexto de Playwright usar un proxy diferente?
Sí. Crea cada contexto con su propio objeto proxy. La versión actual de Playwright no requiere un proxy ficticio al iniciar el navegador antes de la configuración del proxy a nivel de contexto.
P: ¿Playwright soporta proxies SOCKS5?
Sí. Usa un valor de servidor como socks5://proxy.example:1080, y confirma que la puerta de enlace y el método de autenticación soporten el protocolo elegido.
P: ¿Por qué Playwright muestra HTTP 407?
HTTP 407 significa que el proxy rechazó la autenticación. Verifica el nombre de usuario, contraseña, estado de la cuenta o canal generados, y si un secreto fue truncado o copiado con espacios en blanco.
P: ¿Por qué establecer HTTPS_PROXY no cambia la IP del navegador?
Playwright documenta HTTPS_PROXY para descargar binarios del navegador detrás de un proxy. Configura el tráfico de página en tiempo de ejecución por separado con launch({ proxy }), newContext({ proxy }), o use.proxy de la Prueba de Playwright.
P: ¿Debo rotar el proxy en cada solicitud de Playwright?
No. Mantén una sesión de proxy durante la duración de un contexto lógico del navegador, y luego rota al crear el siguiente contexto. Esto preserva la consistencia en cookies, almacenamiento, navegación y estado de sesión del lado del servidor.
Marcus Chen
Aug. 10th 2026
Prueba Nstdata - Empieza tu prueba gratis hoy
110M+ IP reales con 99.9% de acceso exitoso
Acceso inmediato a pools premium de proxies residenciales, datacenter, IPv6 e ISP.
Respuesta media ultrarrapida ~0.5s para tareas de alta concurrencia
