Alterar idioma
Português English Русский Deutsch Español Français Italiano Українська Tiếng Việt Türkçe Bahasa Indonesia हिन्दी 日本語 中文
Menu
Preços
Proxies
TIPOS DE PROXY
Soluções
Recursos

Como usar um proxy com o Playwright

Dê ao Playwright um endereço ISP estático, ao iniciar o navegador ou para um único contexto. Os exemplos foram executados em Chromium, Firefox e WebKit contra um proxy local antes de serem publicados.

Em resumo: Passe proxy com server, username e password para chromium.launch, ou para browser.new_context para limitá-lo a um contexto. Em HTTP, os três motores se autenticam com esses campos. Em SOCKS5, nenhum deles aceita usuário e senha: o Playwright se recusa a iniciar. Coloque o seu IP na lista de IPs permitidos do proxy e informe apenas o servidor socks5://.

O Playwright controla Chromium, Firefox e WebKit com uma única API, e o proxy faz parte de como um navegador ou um contexto é criado. Isso facilita usar vários endereços em um mesmo script, e é também onde está o seu único limite rígido: SOCKS5 com senha.

Proxy no Playwright com Python

O exemplo em Python inicia o Chromium com o proxy para o navegador inteiro; o exemplo por contexto o limita a um único contexto. Trocar de motor é trocar chromium por firefox ou webkit; o objeto proxy continua o mesmo.

Autenticação de proxy no Playwright

Os três motores respondem ao 407 do proxy com o usuário e a senha do objeto proxy quando o proxy fala HTTP. Um proxy SOCKS5 não recebe essa resposta de nenhum deles, e é por isso que o exemplo de SOCKS5 não leva credenciais e depende da lista de IPs permitidos.

Proxy por página no Playwright, e bypass

Não é possível anexar um proxy a uma única página. A unidade é o contexto: crie um contexto por endereço e abra dentro dele as páginas que devem compartilhar esse endereço. No Playwright, contextos são baratos, então um script que confere uma loja a partir de três países mantém três contextos, cada um construído a partir do seu próprio pedido.

O objeto proxy também aceita um campo bypass, uma lista de hosts separados por vírgula que devem ser acessados diretamente. Use-o para os seus serviços internos ou um servidor de testes local, de modo que apenas o tráfego destinado ao mundo externo saia pelo endereço que você paga.

Configurar um proxy no Playwright

  1. Copie host, porta, usuário e senha

    Em Meus Proxies no painel ou no pedido pela API. Cada endereço vem com os seus próprios quatro valores.

  2. Escolha o escopo

    Em launch, o navegador inteiro usa o proxy. Em new_context, só esse contexto o usa, então um mesmo script pode executar vários contextos por endereços diferentes.

  3. Passe o objeto proxy

    {"server": "http://HOST:PORT", "username": "USERNAME", "password": "PASSWORD"}. As credenciais vão em campos próprios, nunca dentro da URL do servidor.

  4. Vai usar SOCKS5? Retire as credenciais

    O Playwright não consegue fazer login em um proxy SOCKS5, então mude o pedido para SOCKS5, admita o IP da sua máquina com a chamada da lista de IPs permitidos nas abas de código e mantenha apenas socks5://HOST:PORT, com a nova porta. Enquanto uma lista de IPs permitidos estiver definida, o proxy admite apenas os endereços listados e o usuário e a senha deixam de funcionar para esse pedido; enviar uma lista vazia desativa a lista de IPs permitidos e o login com senha volta a funcionar.

  5. Confirme o endereço de saída

    Abra Qual é o meu IP em uma página desse navegador ou contexto uma vez, antes da execução real.

# pip install playwright && playwright install chromium
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        "server": "http://HOST:PORT",
        "username": "USERNAME",
        "password": "PASSWORD",
    })
    page = browser.new_page()
    page.goto("https://example.com/")
    print(page.title())
    browser.close()
// npm i playwright && npx playwright install chromium
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://HOST:PORT',
      username: 'USERNAME',
      password: 'PASSWORD',
    },
  });
  const page = await browser.newPage();
  await page.goto('https://example.com/');
  console.log(await page.title());
  await browser.close();
})();
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    # The proxy belongs to this context only; another context can use
    # a different address, or none.
    context = browser.new_context(proxy={
        "server": "http://HOST:PORT",
        "username": "USERNAME",
        "password": "PASSWORD",
    })
    page = context.new_page()
    page.goto("https://example.com/")
    print(page.title())
    browser.close()
# Switch the proxy to SOCKS5 and put your machine's IP on its allowlist:
# Chromium cannot send a SOCKS5 username and password.
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={"server": "socks5://HOST:PORT"})
    page = browser.new_page()
    page.goto("https://example.com/")
    print(page.title())
    browser.close()
# Put the public IPv4 address your code runs from on the proxy's
# allowlist. Replaces the list; an empty list turns allowlisting off
# and the proxy falls back to username and password.
curl -X PUT "https://api.proxyjam.com/public/v1/orders/ORDER_ID/whitelist" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whitelisted_ips": ["YOUR_IP"]}'

Código testado para o Playwright

Executado com o Playwright 1.64 para Python e para Node. Os exemplos HTTP enviam usuário e senha e precisam de um pedido sem lista de IPs permitidos definida; o de SOCKS5 depende da lista de IPs permitidos e exige que o proxy seja mudado antes para SOCKS5, o que gera uma nova porta. Substitua os valores em maiúsculas pelos do seu pedido.

Documentação completa da API

O que cada navegador do Playwright aceita

Testado em 2026-10-22 com o Playwright 1.64 para Python no macOS: cada motor foi iniciado contra um proxy local que exigia senha e contra outro que admitia um cliente da lista de IPs permitidos. Recusado significa que o Playwright parou na inicialização com um erro.
HTTP com senhaSOCKS5 com senhaSOCKS5, com IP permitido
ChromiumFuncionaRecusado na inicializaçãoFunciona
FirefoxFuncionaRecusado na inicializaçãoFunciona
WebKitFuncionaRecusado na inicializaçãoFunciona

O que dá errado com proxies no Playwright

Credenciais na string do servidor

O Playwright lê usuário e senha de campos próprios. Se forem escritos na URL do servidor, não são enviados de forma alguma: no nosso teste, a primeira navegação travou até estourar o tempo limite, sem nenhuma mensagem que apontasse para as credenciais.

Uma senha de SOCKS5

Todos os motores recusam a autenticação SOCKS5, e o erro surge na inicialização, antes de qualquer página abrir. A solução não é outra biblioteca: coloque na lista de IPs permitidos o IP de onde o seu script roda e retire as credenciais.

Esperar que new_page mude o endereço

As páginas compartilham o proxy do contexto, e os contextos compartilham o do navegador, a menos que tenham um próprio. Para usar dois endereços lado a lado, crie dois contextos, cada um com o seu proxy.

Pular a verificação de saída

Um erro de digitação na porta ou um proxy ainda em HTTP falha de forma evidente, mas um contexto criado sem o objeto proxy sai direto e em silêncio. Carregue uma página que mostre o IP uma vez para cada contexto que você configurar.

Como o endereço se encaixa no modelo do Playwright

Um contexto, um endereço
Cada contexto de navegador pode ter o seu próprio IP estático, de um pedido próprio
Login em HTTP
Campos username e password, aceitos por Chromium, Firefox e WebKit
Login em SOCKS5
Apenas por endereço IPv4 na lista de permitidos, definida pela API ou pelo MCP
Estabilidade
O IP permanece o mesmo entre execuções durante todo o período que você pagou

Próximos passos depois do Playwright

Perguntas sobre proxies no Playwright

Como configuro um proxy com autenticação no Playwright?

Passe um objeto com server, username e password, para launch ou para new_context. Com um proxy HTTP, Chromium, Firefox e WebKit enviam essas credenciais quando o proxy as solicita.

Posso usar um proxy SOCKS5 com senha no Playwright?

Não. O Playwright para na inicialização com um erro dizendo que o navegador não oferece suporte à autenticação de proxy SOCKS5, nos três motores. Coloque na lista de IPs permitidos o IP de onde o seu script roda e passe apenas o servidor socks5; a nossa lista de IPs permitidos vale tanto em SOCKS5 quanto em HTTP. SOCKS5

Como uso um proxy diferente para cada página?

Dê a cada contexto de navegador o seu próprio proxy e abra a página nesse contexto. As páginas de um mesmo contexto sempre compartilham o proxy dele, então um proxy por página significa um contexto por página.

A configuração é a mesma em Python e em Node?

O mesmo objeto com os mesmos três campos: o Python o escreve como dicionário e o Node como objeto literal. Os dois exemplos desta página foram executados com o Playwright 1.64.

Posso usar o proxy para scraping?

Testes das suas próprias páginas por região, verificações de qualidade, verificação de anúncios, pesquisa de preços e de mercado, monitoramento de SEO e proteção de marca podem ser feitos sem análise prévia conforme a nossa política de uso aceitável. A disponibilidade pública, por si só, não autoriza a coleta de dados, dados pessoais exigem uma base legal declarada, e a seção 5 da política proíbe usar o endereço em violação a CAPTCHAs, detecção de bots, limites de requisições ou bloqueios de contas. Política de Uso Aceitável

Contextos e endereços estáticos se correspondem um a um: um contexto por mercado ou por tarefa, cada um chegando ao destino pelo mesmo IP, sem mudanças, a cada execução do script. Compre quantos endereços você tiver de contextos em proxies ISP, compare os planos em preços e baixe páginas sem navegador com o guia de Python requests.

Fontes