# 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](https://github.com/microsoft/playwright/issues/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:

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

// Fails immediately — no page is ever created
const browser = await chromium.launch({
  proxy: {
    server: 'socks5://residentialpremium.quantumproxies.io:1080',
    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](https://quantumproxies.io/blog/anti-detect-frameworks-authenticated-proxies-map) 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](https://quantumproxies.io/socks5-proxies) 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:

```python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        # was: "socks5://residentialpremium.quantumproxies.io:1080"
        "server": "http://residentialpremium.quantumproxies.io:8080",
        "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](https://quantumproxies.io/blog/socks5-vs-http-proxy-difference) 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](https://quantumproxies.io/blog/playwright-proxy-integration).

## 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:

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

const browser = await chromium.launch({
  proxy: { server: 'socks5://residentialboson.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](https://quantumproxies.io/ip-checker) gratuito informa qual é realmente a saída, não apenas que ela respondeu.

![As quatro correções para autenticação de proxy SOCKS5 no Playwright lado a lado: mudar para o endpoint HTTP do gateway, colocar o IP na lista branca, executar um retransmissor local ou iniciar o Firefox. O quadro mostra o preço de cada uma: a troca para HTTP custa uma linha, as outras exigem um IP fixo, um processo para supervisionar ou outro motor.](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785776550/blog/generated/qp-b10-003-diag1.png)
*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:

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

# 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](https://quantumproxies.io/blog/proxy-relay-socks5-auth-tools).

## 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:

```python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.firefox.launch(proxy={
        "server": "socks5://residentialpremium.quantumproxies.io:1080",
        "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.

![Configurações SOCKS5 do Playwright no Chromium: credenciais nos campos do proxy geram erro na inicialização, e credenciais dentro da string de servidor socks5:// falham silenciosamente com um erro de conexão SOCKS. O quadro lista o que funciona: o endpoint HTTP com usuário e senha, socks5:// com um IP na lista branca ou um retransmissor local.](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785776551/blog/generated/qp-b10-003-diag2.png)
*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](https://quantumproxies.io/residential-proxies) 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](https://quantumproxies.io/socks5-proxies)