Modo UC do SeleniumBase com Proxy Não Funciona: Causas e Soluções

A reclamação é sempre a mesma: o Modo UC supera o Cloudflare sem um proxy e falha com um, ou o IP simplesmente nunca muda. Ambos os sintomas têm causas concretas — e nenhum é um bug do SeleniumBase.

Pesquise seleniumbase uc mode proxy e você encontrará as mesmas três páginas: uma pergunta no Stack Overflow onde o IP nunca muda em três serviços de proxy diferentes, o problema no GitHub seleniumbase/SeleniumBase#3046 ("Modo UC não funciona com proxy", registrado em agosto de 2024 na versão 4.29.9, fechado como não reproduzível), e um tópico de discussão onde a resposta do mantenedor tem duas frases: proxies com autenticação precisam de uma extensão do Chrome, e você pode simplesmente ter um proxy ruim. Ambas as partes dessa resposta estão corretas, e juntas explicam quase todas as falhas. Aqui está a versão longa, além da ordem de depuração que encontra a causa.

Duas falhas diferentes que parecem idênticas

Antes de mudar qualquer coisa, descubra qual problema você tem, porque as soluções não compartilham nada. Falha A: o IP de saída nunca muda. Seu script roda, as páginas carregam, e o alvo vê seu endereço real — o proxy nunca esteve no caminho. Falha B: o proxy funciona e o site bloqueia você. O Modo UC passa pelo Cloudflare sem proxy, mas enfrenta um loop de desafio no momento em que você adiciona um, que é exatamente o que o problema #3046 descreve. A Falha A é um problema de configuração. A Falha B é um problema de reputação de IP. Tratar uma como a outra é o motivo pelo qual esses tópicos se estendem por páginas.

Por que proxies autenticados precisam de uma extensão — e por que isso importa no Modo UC

O Chrome não tem uma maneira de fornecer credenciais de proxy pela linha de comando. A flag --proxy-server descarta silenciosamente qualquer user:pass@ que você embutir, e o desafio 407 resultante aparece como um diálogo nativo que o WebDriver não pode tocar. Então, quando você passa uma string de proxy contendo credenciais, o SeleniumBase gera uma pequena extensão do Chrome na hora, escreve-a em uma pasta temporária e a carrega no lançamento para que possa responder ao desafio por você. Esse é o mecanismo ao qual o mantenedor se refere, e o mesmo descrito em nosso guia sobre proxies autenticados no Selenium.

O Modo UC adiciona partes móveis em torno disso: ele lança o Chrome primeiro, anexa um chromedriver modificado depois, e desconecta o driver durante ações furtivas. A extensão tem que ser carregada antes de qualquer uma dessas ações, e se não for, nada gera uma exceção — o Chrome navega diretamente, e você obtém a Falha A. A causa usual é a divergência de versão. O Chrome 137 mudou o comportamento das extensões o suficiente para quebrar a autenticação de proxy até que o SeleniumBase lançasse uma atualização, então uma versão antiga fixada mais um Chrome atual falha silenciosamente todas as vezes. Atualize primeiro, depure depois.

Formatos de proxy do Modo UC do SeleniumBase que realmente funcionam

Erros de formato representam uma parcela surpreendente dos relatos de "proxy ignorado". O SeleniumBase aceita o proxy como uma string simples, com ou sem credenciais, tanto nos gerenciadores Driver quanto SB e na linha de comando:

from seleniumbase import Driver, SB

# Authenticated: SeleniumBase builds a proxy-auth extension for this
driver = Driver(uc=True, proxy="USER:PASS@gate.quantumproxies.io:PORT")

# IP-whitelisted: no credentials, no extension
with SB(uc=True, proxy="gate.quantumproxies.io:PORT") as sb:
    sb.uc_open_with_reconnect("https://httpbin.org/ip", 4)
    print(sb.get_text("body"))     # must NOT be your own IP

# Same thing from pytest:
#   pytest test_x.py --uc --proxy=USER:PASS@gate.quantumproxies.io:PORT

Três regras derivam disso. Não envolva a string em http:// e credenciais ao mesmo tempo, a menos que você tenha verificado que sua versão lida com isso — USER:PASS@HOST:PORT é o formato documentado. Não espere que SOCKS5 com credenciais funcione de forma alguma: isso é uma limitação do Chromium, idêntica à que cobrimos para autenticação SOCKS5 no Playwright, e nenhum framework contorna isso. E se sua senha contiver @ ou :, altere-a para algo alfanumérico em vez de depurar um analisador.

A correção que remove toda a classe de falhas

Se a máquina que executa seu scraper tem um IP público estável, autentique-o em vez da solicitação. Registre o endereço com seu provedor — todo plano da QuantumProxies suporta a lista branca de IPs junto com user:pass — e então passe um simples host:port. Sem credenciais significa sem extensão: um componente a menos que quebra em uma atualização do Chrome, um arquivo a menos carregado em um navegador que você quer manter discreto. Em um VPS, essa é a mudança de maior valor neste post.

O limite é topológico, não técnico: a lista branca autentica uma máquina, então contêineres com escalonamento automático, runners de CI e qualquer coisa por trás de um NAT rotativo ainda precisam de credenciais. Para esses, mantenha o caminho da extensão e mantenha o SeleniumBase atualizado.

Verifique o IP de saída antes de culpar o Modo UC

Este é o passo zero e a maioria das pessoas o ignora. Prove que o tráfego sai pelo proxy, isoladamente, antes de mexer em uma configuração stealth. Teste as mesmas credenciais fora do navegador primeiro — se curl não puder usá-las, nenhum framework poderá:

# 1. Does the proxy work at all, outside any browser?
curl -x http://USER:PASS@gate.quantumproxies.io:PORT https://httpbin.org/ip

# 2. Is the toolchain current? (Chrome 137+ broke older extension handling)
pip install -U seleniumbase && sbase get chromedriver

# 3. Does the proxy work WITHOUT the stealth patches?
python -c "from seleniumbase import Driver; \
d=Driver(proxy='USER:PASS@gate.quantumproxies.io:PORT'); \
d.get('https://httpbin.org/ip'); \
print(d.find_element('tag name','body').text); d.quit()"

Se o passo 1 falhar, o problema é o proxy ou as credenciais. Se o passo 1 passar e o passo 3 falhar, o problema é a extensão ou a versão do Chrome. Se ambos passarem e apenas uc=True falhar, então — e somente então — é uma interação do Modo UC. Saber qual saída você realmente obteve importa tanto quanto saber que você obteve uma: nosso verificador de qualidade de IP gratuito relata o endereço, seu tipo e sua reputação, que é a diferença entre "o proxy funciona" e "o proxy passará".

Quando o proxy funciona e o Cloudflare ainda vence

Esta é a Falha B, e não é um bug em nada. O Modo UC faz o navegador parecer humano; ele não pode fazer a rede parecer residencial. Roteie um navegador stealth através de um sub-rede de datacenter que centenas de outros scrapers já queimaram e você obtém a versão difícil do desafio — aquela que nunca se resolve, não importa quantas vezes você clique. Nenhum framework de navegador resolve isso, porque o veredicto é feito antes mesmo de a impressão digital ser lida. Nossas notas sobre erro 1020 do Cloudflare e sobre evitar CAPTCHAs enquanto faz scraping chegam ao mesmo ponto: o CAPTCHA é um sintoma, a reputação do IP é a causa.

Três coisas mudam o resultado. Mude para IPs residenciais: endereços reais de residências em mais de 200 países carregam uma reputação que uma faixa de datacenter não pode. Use uma sessão persistente para qualquer coisa com login ou carrinho, já que a rotação no meio do fluxo é lida como sequestro de sessão, e saídas rotativas para rastreamentos amplos sem estado. E combine o país de saída com o local que você emula — uma saída alemã com um local en-US e um fuso horário de Nova York é marcada como uma anomalia.

Dois detalhes do ambiente fecham o ciclo. O Modo UC é detectável no modo headless, então no Linux use a exibição virtual (xvfb=True) em vez de headless=True — é por isso que vários relatos de "funciona no Windows, falha no Ubuntu" se resolvem uma vez que a exibição é corrigida, e por que ajudantes baseados em PyAutoGUI como uc_gui_click_captcha() precisam de uma exibição para clicar em qualquer coisa. E teste incognito=True de ambas as formas com um proxy de autenticação: extensões e modo incógnito são uma combinação frágil, e suas credenciais viajam em uma extensão.

O checklist de depuração, em ordem

• Verifique se o IP de saída mudou. Carregue um endpoint de eco de IP e leia-o. Tudo abaixo é inútil até que isso passe.
• Teste o proxy fora do navegador com curl ou requests, usando as mesmas credenciais exatas.
• Atualize o SeleniumBase e o driver. As mudanças de extensão do Chrome 137 quebraram a autenticação de proxy em versões mais antigas.
• Remova temporariamente uc=True. Se o proxy funcionar no modo simples, você isolou a interação.
• Mude para a lista branca de IPs se a máquina tiver um endereço fixo — isso remove a extensão da imagem completamente.
• Use xvfb, não headless, no Linux; o Modo UC é detectável no modo headless e os ajudantes de CAPTCHA precisam de uma exibição.
• Só agora mude as configurações de stealth: alterne incógnito, aumente reconnect_time, depois mude o tipo de proxy.

O Modo CDP, o sucessor documentado do Modo UC simples, não muda nada disso: as restrições de proxy vêm do Chrome, não do framework, então o mesmo checklist se aplica. Para a visão cruzada de frameworks sobre quem suporta proxies autenticados, nosso mapa de proxies de frameworks anti-detecção apresenta isso lado a lado.

Perguntas frequentes

Por que meu IP não está mudando com o Modo UC do SeleniumBase?

Quase sempre porque a extensão de autenticação de proxy não foi carregada, então o Chrome navegou diretamente. Nada gera um erro quando isso acontece. Atualize o SeleniumBase, confirme que a string de proxy é USER:PASS@HOST:PORT, e teste as mesmas credenciais com curl. Se a máquina tiver um IP público estável, coloque-o na lista branca e remova as credenciais completamente.

Por que o Modo UC passa pelo Cloudflare sem um proxy, mas não com um?

Porque sua própria conexão tem uma reputação limpa e a saída do proxy não. Faixas compartilhadas de datacenter são fortemente sinalizadas, e um IP sinalizado recebe o desafio difícil que nenhuma automação pode limpar. Mude o trabalho para saídas residenciais ou móveis e teste novamente antes de alterar qualquer configuração stealth — o navegador nunca foi o problema.

O Modo UC do SeleniumBase funciona com proxies SOCKS5?

Sem credenciais, sim. Com credenciais, não — o Chromium nunca implementou autenticação SOCKS5 com nome de usuário/senha, então nenhum framework da família Selenium pode adicioná-la. Use o endpoint HTTP do mesmo gateway com credenciais, ou coloque seu IP na lista branca e mantenha o endpoint SOCKS5 sem autenticação.

Posso executar o Modo UC com um proxy no modo headless?

Você pode, mas não deveria. O Modo UC é detectável no modo headless, e os métodos de ajuda de CAPTCHA precisam de uma exibição real porque eles controlam o mouse através do PyAutoGUI. Em um servidor Linux, use xvfb=True para uma exibição virtual; essa combinação é o que os exemplos mantidos visam.

Como uso rotação de proxy com o SeleniumBase?

Aponte para um gateway rotativo em vez de gerenciar uma lista: cada nova conexão obtém uma saída diferente do pool, sem alterações de código. Para fluxos que devem manter uma identidade em várias páginas, solicite uma sessão persistente nos parâmetros de nome de usuário para que a saída se mantenha durante a janela da sessão, e inicie um driver novo por identidade.

O Modo UC não está lutando contra seu proxy. Ele está empilhando uma sequência de lançamento furtiva em cima de um mecanismo de credenciais que o Chrome nunca projetou para automação, e então um IP queimado finaliza o trabalho. Remova a extensão colocando na lista branca, verifique a saída antes de mexer em qualquer outra coisa, e dê ao navegador um IP que ainda não foi gasto.

Execute o Modo UC em IPs residenciais limpos