Autenticação de Proxy SOCKS5 no Playwright: Por Que Falha, 4 Soluções

O Playwright aceita um servidor socks5:// e então recusa seu nome de usuário e senha. A limitação é do Chromium, não do Playwright, e está aberta desde 2021 — aqui estão as quatro maneiras de contorná-la, classificadas.

A autenticação de proxy SOCKS5 no Playwright não existe, e saber disso de antemão economiza uma noite. Passe um servidor socks5:// junto com um nome de usuário e senha e o Playwright recusa antes mesmo do navegador navegar. A solicitação de recurso que todos encontram, microsoft/playwright#10567, foi aberta em novembro de 2021, ainda está aberta e ainda carrega o rótulo P3-collecting-feedback. A limitação não é do Playwright para corrigir: ela reside no Chromium. Este post mostra as cadeias de erro exatas, explica por que nenhuma extensão ou flag de configuração te salva, e dá quatro soluções — a troca de HTTP em uma linha, a lista branca de IP, um retransmissor local e o Firefox.

O erro que você está procurando

Cada versão deste problema produz uma das duas cadeias. Em Node você recebe Error: Browser does not support socks5 proxy authentication; em Python, versões mais antigas prefixam com playwright._impl._api_types.Error: e as mais novas com playwright._impl._errors.Error:. A mensagem é a mesma, e é lançada no início, não na navegação:

const { chromium } = require('playwright');

// Fails immediately — no page is ever created
const browser = await chromium.launch({
  proxy: {
    server: 'socks5://gate.quantumproxies.io:PORT',
    username: 'USER',
    password: 'PASS',
  },
});
// Error: Browser does not support socks5 proxy authentication

// Python raises the same thing:
// playwright._impl._errors.Error: Browser does not support
// socks5 proxy authentication

Existe uma variante mais silenciosa. Se você omitir os campos de credenciais e os inserir na string do servidor — socks5://USER:PASS@host:1080 — nada é lançado. O Chromium simplesmente ignora a parte de informações do usuário da URL, tenta um handshake não autenticado, e o gateway o rejeita. Você então vê net::ERR_SOCKS_CONNECTION_FAILED ou um simples timeout no primeiro goto(), o que leva as pessoas a procurar bugs de rede que não estão lá.

Onde a autenticação de proxy SOCKS5 no Playwright realmente quebra

A própria documentação do Playwright é explícita: os campos username e password na opção de proxy são descritos como credenciais a serem usadas "se o proxy HTTP exigir autenticação". SOCKS é suportado apenas como um esquema. Por baixo, o Chromium nunca implementou a sub-negociação de nome de usuário/senha do RFC 1929 para SOCKS5, razão pela qual a entrada do rastreador de problemas do Chromium sobre autenticação SOCKS5 (40323993) coletou anos de comentários, por que a extensão SwitchyOmega avisa os usuários no momento em que selecionam SOCKS5 com credenciais, e por que o Brave e o Edge se comportam de maneira idêntica. É um motor, uma lacuna, herdada por tudo construído sobre ele.

Isso também explica por que o truque que resgata usuários do Selenium não ajuda aqui. Uma extensão Manifest V3 pode responder a um desafio de proxy através de chrome.webRequest.onAuthRequired, mas esse gancho dispara em respostas HTTP 407 Proxy Authentication Required. Um handshake SOCKS5 é uma negociação em nível de byte no socket antes de qualquer HTTP existir, então não há evento para interceptar. E não confunda a opção de contexto httpCredentials com autenticação de proxy: ela responde a desafios 401 do site que você está visitando, nunca do proxy. Para uma visão completa sobre frameworks stealth, nosso mapa de proxies autenticados em frameworks anti-detect cobre quem suporta o quê.

Solução 1: use o endpoint HTTP do mesmo gateway

Esta é a solução para cerca de nove em cada dez usuários, e é uma linha. Provedores sérios expõem o mesmo pool de IPs em ambos os protocolos em portas diferentes — todo plano da QuantumProxies oferece endpoints HTTP e SOCKS5 com as mesmas credenciais e a mesma sintaxe de sessão. Troque o esquema e a porta, mantenha todo o resto, e os campos de credenciais nativos do Playwright fazem seu trabalho:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        # was: "socks5://gate.quantumproxies.io:SOCKS_PORT"
        "server": "http://gate.quantumproxies.io:PORT",
        "username": "USER",
        "password": "PASS",
    })
    page = browser.new_page()
    page.goto("https://httpbin.org/ip")
    print(page.text_content("body"))   # must be the proxy exit IP
    browser.close()

Você não perde nada mensurável. Para o tráfego do navegador, um proxy HTTP abre um túnel CONNECT e carrega os mesmos bytes criptografados que um túnel SOCKS5 carregaria; as diferenças entre os dois protocolos importam para tráfego UDP e não-HTTP, não para o carregamento de uma página. Nossa análise de SOCKS5 versus proxies HTTP tem o detalhe. E como o objeto de proxy também é aceito por newContext(), as mesmas credenciais oferecem rotação por contexto exatamente como descrito em nosso guia de integração de proxy no Playwright.

Solução 2: lista branca de IP mantém socks5:// vivo

Se você realmente precisa do esquema SOCKS5 — um proxy que só fala SOCKS, uma cadeia de ferramentas que o assume — autentique a máquina em vez da solicitação. Registre o IP público do scraper com seu provedor, remova as credenciais, e o Chromium fica feliz porque não há nada para negociar:

const { chromium } = require('playwright');

const browser = await chromium.launch({
  proxy: { server: 'socks5://gate.quantumproxies.io:PORT' }, // no creds
});
const page = await browser.newPage();
await page.goto('https://httpbin.org/ip');
console.log(await page.textContent('body'));
await browser.close();

A lista branca autentica uma máquina, não um script, e esse é todo o trade-off. Um VPS ou uma saída de escritório com um endereço estável funciona perfeitamente; runners de CI efêmeros, contêineres com escalonamento automático e qualquer coisa por trás de um NAT rotativo falharão no momento em que o endereço mudar. Verifique a saída antes de confiar em uma execução — uma conexão direta silenciosa parece exatamente como um proxy funcionando até que seu alvo comece a bloquear seu próprio IP. Nosso verificador de qualidade de IP gratuito informa qual é realmente a saída, não apenas que ela respondeu.

Comparação de quatro soluções para autenticação de proxy SOCKS5 no Playwright: endpoint HTTP, lista branca de IP, retransmissor local e Firefox — A troca de endpoint HTTP custa uma linha e nenhuma capacidade. Tudo à direita disso compra o esquema socks5:// a um preço.

Solução 3: um retransmissor local que remove as credenciais

Quando o IP não pode ser listado na lista branca e o provedor não tem porta HTTP, coloque um tradutor na frente do navegador. O padrão é sempre o mesmo: um ouvinte local sem autenticação encaminha para o endpoint SOCKS5 upstream com credenciais anexadas. Com gost, isso é um único comando:

# Local no-auth HTTP listener -> authenticated upstream SOCKS5
gost -L=http://127.0.0.1:8080 \
     -F=socks5://USER:PASS@gate.quantumproxies.io:PORT

# Playwright then points at the local hop, with no credentials:
#   proxy: { server: 'http://127.0.0.1:8080' }

Duas regras. Vincule o ouvinte a 127.0.0.1, nunca 0.0.0.0 — um proxy sem autenticação acessível da internet é um retransmissor aberto que será encontrado e abusado em poucas horas. E trate o retransmissor como um processo que você deve supervisionar: se ele morrer, o Chromium volta a um erro de conexão em vez de uma solicitação direta, o que é pelo menos barulhento. Essa abordagem se tornou comum o suficiente para que praticantes publiquem pequenos retransmissores construídos para esse fim; comparamos as opções em nosso guia de ferramentas de retransmissão de autenticação SOCKS5.

Solução 4: execute o Firefox em vez do Chromium

O Firefox implementa autenticação de nome de usuário/senha SOCKS5 nativamente, que é a diferença que o tópico de problemas do Playwright continua apontando. Troque o tipo de navegador e o erro desaparece:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.firefox.launch(proxy={
        "server": "socks5://gate.quantumproxies.io:PORT",
        "username": "USER",
        "password": "PASS",
    })
    page = browser.new_page()
    page.goto("https://httpbin.org/ip")
    print(page.text_content("body"))   # confirm the exit before trusting it
    browser.close()

Faça a etapa de verificação, toda vez. O Playwright não lançar não é prova de que as credenciais foram usadas — apenas um eco de IP é. E seja claro sobre o que você está comprando: um motor de renderização diferente, uma superfície de impressão digital diferente e um ecossistema stealth que tende fortemente ao Chromium. Se seu alvo já aceita o Firefox, isso é gratuito. Se você escolheu o Chromium por razões anti-bot, mudar de motor para resolver um problema de proxy é a troca errada — adote a solução 1 e mantenha seu navegador.

A decisão, em uma linha cada

Provedor tem uma porta HTTP: use-a. Uma linha, autenticação nativa, mesmas saídas, sem processo extra.
IP público fixo: liste-o na lista branca e mantenha socks5:// sem credenciais.
Nenhum dos dois: execute um retransmissor local vinculado ao loopback e aponte o Playwright para 127.0.0.1.
Já no Firefox: passe as credenciais e verifique o IP de saída uma vez.
Nunca: credenciais dentro da string server. O Chromium as descarta sem uma palavra.

Lista de verificação de configurações de proxy SOCKS5 no Playwright que funcionam no Chromium versus configurações que lançam ou falham silenciosamente — O Chromium aceita o esquema SOCKS5 e nunca as credenciais. Tudo à direita desta lista falha — metade sem um erro.

Perguntas frequentes

O Playwright suporta autenticação de proxy SOCKS5?

Não com o Chromium. A opção de proxy do Playwright documenta nome de usuário e senha como credenciais HTTP(S), e o Chromium não tem implementação de nome de usuário/senha SOCKS5 para entregá-las, então o lançamento falha. O Firefox no Playwright suporta. O problema de rastreamento, microsoft/playwright#10567, está aberto desde novembro de 2021 sem correção agendada.

O que significa 'Browser does not support socks5 proxy authentication'?

Significa que você passou credenciais junto a um servidor socks5:// para um lançamento do Chromium. O Playwright valida a combinação e recusa em vez de abrir um navegador que as ignoraria silenciosamente. Ou mude para a porta HTTP do gateway e mantenha os campos de credenciais, ou autentique por lista branca de IP e remova-os completamente.

Como uso um proxy SOCKS5 com o Playwright em Python?

Passe proxy={"server": "socks5://host:port"} sem nome de usuário ou senha, e faça o provedor autorizar o IP público da sua máquina. Se o IP não for estável, use o endpoint HTTP do mesmo gateway com credenciais, ou encaminhe através de um retransmissor local. Sempre confirme a saída contra um endpoint de eco de IP.

Uma extensão do Chrome pode adicionar autenticação SOCKS5?

Não. O truque de extensão usado para proxies HTTP autenticados depende de chrome.webRequest.onAuthRequired, que dispara em respostas HTTP 407. O SOCKS5 autentica durante o handshake do socket, antes de qualquer solicitação HTTP existir, então nenhuma API de extensão pode vê-lo. Extensões de troca de proxy avisam sobre essa limitação pelo mesmo motivo.

O SOCKS5 é mais rápido que o HTTP para scraping com o Playwright?

Não de forma significativa. O tráfego HTTPS através de um proxy HTTP usa um túnel CONNECT, então ambos os protocolos carregam o mesmo fluxo criptografado com sobrecarga comparável. As verdadeiras vantagens do SOCKS5 são o suporte a UDP e a neutralidade de protocolo, nenhuma das quais um carregamento de página do navegador usa. Escolha o endpoint que autentica de forma limpa.

A versão curta: pare de tentar fazer o Chromium fazer algo que nunca fez. Mova o trabalho para o endpoint HTTP, ou liste na lista branca e remova as credenciais — e se você precisar manter socks5:// com uma saída rotativa, coloque um retransmissor no meio em vez de uma solução alternativa no seu código. Uma vez que a autenticação esteja fora do caminho, o que decide se a execução será bem-sucedida é o pool por trás dela: saídas residenciais em mais de 200 países, com rotação por solicitação ou sessões fixas quando um fluxo precisa de uma identidade.

Obtenha endpoints HTTP e SOCKS5 em um único plano