Como Usar um Proxy com o Playwright: O Guia Essencial

TL;DR:

• Playwright controla um proxy a partir de uma opção de configuração. O parâmetro proxy recebe um servidor, nome de usuário e senha, e a mesma estrutura funciona tanto para um navegador local quanto para uma conexão com um remoto.
• Uma saída residencial é o que faz o tráfego headless ser lido como humano. As faixas de IP de datacenter e a impressão digital de automação padrão são os dois sinais que os sites públicos verificam primeiro; rotear através de endereços residenciais reais remove o primeiro.
• O Scrapeless Scraping Browser fala o Protocolo Chrome DevTools. Playwright se conecta a ele com chromium.connectOverCDP(endpoint), assim os proxies residenciais e a anti-detecção funcionam do lado da nuvem enquanto seu script permanece como Playwright normal.
• proxyCountry fixa a região de saída; sessionName mais sessionTTL mantêm um IP ao longo das navegações. Direcionamento geográfico e sessões fixas são parâmetros de consulta na string de conexão, não código adicional de aplicação.
• Execuções paralelas escalam através de sessões independentes. Abra várias conexões ao mesmo tempo e cada uma recebe seu próprio IP residencial, sem limite de assento concorrente.
• Gratuito para começar. Novas contas Scrapeless incluem tempo de execução gratuito do Scraping Browser — inscreva-se em app.scrapeless.com.

Introdução: Proxies do Playwright e onde a configuração bruta para.

Playwright controla Chromium, Firefox e WebKit a partir de uma única API, e sua espera automática torna as navegações menos quebradiças do que a geração anterior de ferramentas de automação. Duas coisas ainda podem bloquear um script Playwright. O navegador embarca uma impressão digital de automação que scripts de detecção leem, e se conecta a partir do IP que a máquina host possui — geralmente um endereço de nuvem ou datacenter que sites públicos limitam ou geo-restrigem. Um proxy residencial responde à metade da rede desse problema; um navegador anti-deteção responde à metade da impressão digital.

Este guia começa com o suporte a proxy do próprio Playwright, uma vez que essa é a opção que todos os proxies conectam. Em seguida, mostra onde a configuração bruta do proxy não é mais suficiente e como passar os casos mais complicados para um navegador em nuvem ao qual o Playwright se conecta através do mesmo protocolo que já usa para o Chromium.

Pré-requisitos

• Node.js 18 ou mais recente
• Uma conta Scrapeless e chave API — inscreva-se em app.scrapeless.com
• Playwright instalado (npm install playwright)
• Familiaridade básica com npm e variáveis de ambiente do Node.js

Instalação

1. Adicione o Playwright ao seu projeto

Se você ainda não tem o Playwright, instale-o:

npm install playwright

Isso puxa a biblioteca Playwright para os três mecanismos de navegador.

2. Defina sua chave API do Scrapeless

Armazene a chave como uma variável de ambiente para que ela nunca chegue ao controle de versão:

export SCRAPELESS_API_KEY="sua_chave_api_aqui"

3. Nenhum SDK de empacotamento exigido

Playwright se conecta ao Scrapeless Scraping Browser através do Protocolo Chrome DevTools, portanto não há nenhum pacote extra a instalar além do próprio Playwright.

Configure o proxy integrado do Playwright

Playwright aceita configurações de proxy em launch() e em newContext(). Aponte server para seu gateway proxy e passe as credenciais:

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

(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://seu-host-proxy:8080', // seu gateway proxy
      username: 'seu-usuario-proxy',
      password: 'sua-senha-proxy',
    },
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());

  await browser.close();
})();

Essa é toda a interface de nível de biblioteca, e funciona da mesma forma em Chromium, Firefox e WebKit. Duas coisas que não faz: assume que você já tem um pool de endereços residenciais para apontar server e deixa a impressão digital de automação do navegador inalterada. A configuração bruta de proxy move seu tráfego para um novo IP; não muda como a página lê o cliente.

Obtenha sua chave API no plano gratuito: app.scrapeless.com

Onde a configuração bruta de proxy para — impressões digitais e fontes de IP

Dois gaps existem entre launch({ proxy }) e uma execução de automação que sites públicos atendem de forma limpa: a origem e rotação de uma verdadeira rede residencial, e a impressão digital que o navegador apresenta ao chegar. O Scrapeless Scraping Browser fecha ambos. É um navegador de nuvem contra detecção, projetado para crawlers da web e agentes de IA, e como fala o Protocolo Chrome DevTools, o Playwright se conecta a ele com uma linha. Para o Playwright especificamente, ele traz:

• Nós de saída residenciais em mais de 195 países, com a impressão digital de automação tratada na nuvem.
• Renderização de JavaScript do lado da nuvem — o navegador remoto executa a página, então o trabalho sai da sua máquina.
• Geo-targeting e sessões fixas como parâmetros de conexão — proxyCountry, sessionName e sessionTTL são incluídos na string de endpoint.
• Sem limite de assentos concorrentes — pague por uso e abra quantas sessões o run precisar.

A string de conexão carrega sua chave como o parâmetro token; a documentação em docs.scrapeless.com lista todas as opções. Obtenha sua chave de API no plano gratuito em app.scrapeless.com.

Conectar Playwright via CDP

Construa o endpoint WebSocket e, em seguida, conecte-se com chromium.connectOverCDP(). A partir daí, é o Playwright comum — o proxy e a impressão digital já estão aplicados no navegador remoto:

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

const token = process.env.SCRAPELESS_API_KEY;
const params = new URLSearchParams({
  token,
  proxyCountry: 'US',  // fixe a região de saída residencial
  sessionTTL: '300',   // mantenha a sessão ativa por 300 segundos
});
const wsEndpoint = `wss://browser.scrapeless.com/api/v2/browser?${params.toString()}`;

(async () => {
  const browser = await chromium.connectOverCDP(wsEndpoint);
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  console.log('Título:', await page.title());

  // Confirme que a saída é um IP residencial, não da máquina host
  const ipPage = await context.newPage();
  await ipPage.goto('https://api.ipify.org?format=json', { waitUntil: 'domcontentloaded' });
  console.log('Saída:', await ipPage.evaluate(() => document.body.innerText));

  await browser.close();
})();

Fixar um país e reutilizar um IP

Geo-targeting é o parâmetro proxyCountry. A fixação é sessionName mais um sessionTTL ativo: reutilize o mesmo nome dentro da janela e cada navegação sai do mesmo IP residencial, o que mantém um fluxo de login em uma única identidade.

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

const token = process.env.SCRAPELESS_API_KEY;

function endpoint({ country, session }) {
  const params = new URLSearchParams({
    token,
    proxyCountry: country,
    sessionName: session,  // mesmo nome + TTL ativo = mesmo IP de saída
    sessionTTL: '300',
  });
  return `wss://browser.scrapeless.com/api/v2/browser?${params.toString()}`;
}

(async () => {
  const browser = await chromium.connectOverCDP(endpoint({ country: 'US', session: 'demo-session' }));
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto('https://api.ipify.org?format=json', { waitUntil: 'domcontentloaded' });
  console.log('Primeiro:', await page.evaluate(() => document.body.innerText));

  await page.goto('https://api.ipify.org?format=json', { waitUntil: 'domcontentloaded' });
  console.log('Segundo:', await page.evaluate(() => document.body.innerText));

  await browser.close();
})();

Executar sessões em paralelo

Cada conexão é independente, então um pool de trabalhadores é Promise.all sobre vários endpoints com nomes de sessão distintos. Mantenha a concorrência a três por host para ser educado:

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

const token = process.env.SCRAPELESS_API_KEY;

function endpoint(session) {
  const params = new URLSearchParams({ token, proxyCountry: 'US', sessionName: session, sessionTTL: '180' });
  return `wss://browser.scrapeless.com/api/v2/browser?${params.toString()}`;
}

async function fetchIp(session) {
  const browser = await chromium.connectOverCDP(endpoint(session));
  try {
    const page = await browser.newContext().then(c => c.newPage());
    await page.goto('https://api.ipify.org?format=json', { waitUntil: 'domcontentloaded' });
    return { session, ip: JSON.parse(await page.evaluate(() => document.body.innerText)).ip };
  } finally {
    await browser.close();
  }
}

(async () => {
  const workers = ['worker-1', 'worker-2', 'worker-3'];
```javascript
const resultados = await Promise.all(trabalhadores.map(buscarIp));
console.log(resultados);
})();

O Que Você Recebe de Volta

Cada sessão relata uma saída residencial distinta, e uma sessão persistente relata a mesma duas vezes. A execução paralela acima retorna um registro por trabalhador:

// Exemplo ilustrativo — o esquema é exato; o valor do IP é ilustrativo e varia por sessão.
[
  { "sessão": "trabalhador-1", "ip": "72.188.194.89" },
  { "sessão": "trabalhador-2", "ip": "172.56.218.152" },
  { "sessão": "trabalhador-3", "ip": "73.135.52.138" }
]

Notas sobre o esquema:

• proxyCountry: 'US' fixa cada saída a um endereço residencial nos EUA; altere o código para direcionar outra região.
• Dentro de um sessionName e um sessionTTL ativo, o IP permanece constante nas navegações; um novo nome traz um endereço novo.
• Os seletores devem corresponder à marcação atual do site-alvo — aperte-os quando o DOM mudar.
• O navegador remoto renderiza JavaScript por padrão, então o conteúdo do lado do cliente está presente antes de você ler o DOM.

Resolução de Problemas

A conexão cai durante uma execução longa

Causa: sessionTTL expirou antes do término do fluxo de trabalho.

Solução: Defina sessionTTL para cobrir todo o fluxo antecipadamente — é a duração da sessão em segundos, então dimensione para a cadeia de navegação mais longa que você espera.

O site ainda serve uma página "Acesso Negado"

Causa: Um IP residencial limpo não é o único sinal; uma sessão fria que salta direto para uma URL profunda ainda parece automatizada.

Solução: Aqueça a sessão carregando a página inicial do site primeiro no mesmo contexto, fixe proxyCountry a uma região que corresponda ao público e ofereça opções realistas para o contexto (userAgent, Accept-Language).

A extração retorna campos vazios

Causa: Os seletores não correspondem mais à marcação renderizada.

Solução: Reinspecione a página e aperte os seletores; proteja campos opcionais para que um elemento ausente retorne nulo em vez de gerar um erro.

Conclusão: uma camada de proxy que se mantém fora do seu código de aplicativo

Uma execução do Playwright com proxy se resume a alguns movimentos: construa o endpoint, conecte-se via CDP, fixe o país e escreva o mesmo Playwright que você já conhece. O launch({ proxy }) nativo cobre os casos em que você possui o pool; o Scraping Browser cobre os casos em que você precisa de saídas residenciais reais e uma impressão digital que suporte. Fixe a saída com proxyCountry, mantenha uma identidade com sessionName mais um sessionTTL ativo, limite a concorrência a três por host e trate campos ausentes como anuláveis. Para uma visão mais ampla sobre estratégias de rotação, veja best-rotating-proxies-2026.

Pronto para Automatizar em Escala Com Playwright e Proxies?

Junte-se à nossa comunidade para reclamar um plano gratuito e conectar-se com desenvolvedores que estão construindo automação com Playwright: Discord · Telegram.

Inscreva-se em app.scrapeless.com para obter um tempo de execução gratuito do Scraping Browser, revise preços e adapte os padrões acima às regiões e sites que sua automação necessita.

FAQ

Q: É legal realizar scraping com Playwright?

Realizar scraping de dados publicamente visíveis é amplamente permitido, mas as regras variam de acordo com a jurisdição e os termos de serviço do site. Revise os termos do alvo, evite dados por trás de um login que você não está autorizado a usar e consulte um advogado para tudo que for sensível.

Q: Eu preciso de um proxy?

Você precisa de um sempre que o alvo bloquear IPs de datacenter ou aplicar restrições geográficas, o que cobre a maioria dos sites públicos em escala. Uma saída residencial permite que a solicitação chegue como tráfego de usuário comum; sem isso, um IP em nuvem é fácil de bloquear.

Q: Recebo uma página "Acesso Negado" — como consigo uma renderização limpa?

Carregue primeiro a página inicial do site no mesmo contexto para aquecer a sessão, fixe proxyCountry a uma região que se encaixe no público e defina opções realistas de contexto como userAgent e Accept-Language. Um acesso a uma URL profunda de um contexto frio é o gatilho habitual.

Q: Posso executar muitas sessões do Playwright ao mesmo tempo?

Sim. Cada conexão CDP é independente e utiliza seu próprio IP residencial, então um pool de trabalhadores é Promise.all sobre vários endpoints com valores de sessionName distintos. Mantenha a concorrência em três por host para que você fique dentro dos limites apropriados.

Q: Como mudo o país de saída?

Altere o parâmetro proxyCountry e abra uma nova conexão. O país é fixo quando a sessão é criada, então uma região diferente significa uma nova string de endpoint e não uma alteração em meio à sessão.

Q: Isso funciona em sites pesados em JavaScript?

Sim. O navegador remoto executa a página antes que você a leia, então o conteúdo renderizado pelo cliente já está no DOM quando page.goto() é resolvido. Use waitUntil: 'domcontentloaded' mais um curto período de estabilização em sites cuja rede nunca fica ociosa.

P: O que acontece quando a marcação do site muda?

Seletores ligados a uma classe ou estrutura específica quebram quando um site lança um redesign. Extraia âncoras a partir do sinal mais estável disponível — um atributo de dados ou um padrão de URL durável em uma classe CSS hashed — e re-verifique os seletores quando os campos começarem a voltar vazios.