Como Usar Proxies Residenciais no Puppeteer (Incluindo page.authenticate)

Proxies no Puppeteer: o proxy vai nos launch args, as credenciais no page.authenticate, rotação geográfica por página através de um único gateway, e bloqueio de recursos.

O Puppeteer controla um Chromium real, o que é exatamente o que você quer quando um alvo renderiza seu conteúdo com JavaScript, bloqueia dados atrás de interações ou identifica qualquer coisa que não seja um navegador de verdade. Adicionar um proxy residencial é questão de algumas linhas, mas o Puppeteer divide essa tarefa entre dois lugares diferentes de um jeito que engana quase todo mundo na primeira vez: o endereço do proxy vai nos argumentos de inicialização, e as credenciais vão em outro lugar completamente diferente.

Este é o guia de Puppeteer que acompanha proxies residenciais com Playwright; se você quer clientes HTTP simples em vez de um navegador completo, veja proxies em Node.js. Aqui focamos nas armadilhas específicas de navegador.

Tudo abaixo usa o gateway residencial da Shifter: um único endpoint, p.shifter.io:443, com toda a segmentação codificada no nome de usuário. Troque o host e as credenciais para usar outro provedor; a estrutura é a mesma.

O modelo de gateway em um parágrafo

O nome de usuário do proxy carrega sua autenticação e sua segmentação. Você não troca de endpoint para mudar o país ou a sessão, você muda a string do nome de usuário:

customer-USERNAME-country-us-sid-abc123-ttl-600

country-us direciona para os Estados Unidos, sid fixa uma sessão persistente, ttl mantém esse IP por N segundos. Omita sid/ttl e cada nova conexão faz a rotação. A senha permanece constante. No Puppeteer, o host vai em uma flag de inicialização e esse nome de usuário vai em page.authenticate.

A configuração: proxy nos argumentos de inicialização, credenciais em page.authenticate

O Chromium recebe o servidor proxy como uma flag de linha de comando, --proxy-server, passada pelos args do Puppeteer. Ele não aceita user:pass@host ali, o Chromium não lê credenciais dessa flag. Em vez disso, você as fornece por página com page.authenticate, que responde ao desafio 407 do proxy com o Proxy-Authorization correto.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  args: ['--proxy-server=http://p.shifter.io:443'],   // apenas o host, sem credenciais
});

const page = await browser.newPage();
await page.authenticate({
  username: `${process.env.SHIFTER_USER}-country-us`,  // a segmentação vive aqui
  password: process.env.SHIFTER_PASS,
});

await page.goto('https://api.ipify.org');
console.log(await page.evaluate(() => document.body.innerText));   // um IP residencial dos EUA
await browser.close();

Duas coisas para internalizar. O nome de usuário inclui as flags de segmentação (-country-us), porque a geolocalização vive ali, não na URL. E page.authenticate não é opcional para um proxy autenticado, sem isso toda navegação morre em um 407. Essa divisão, host na flag e credenciais em page.authenticate, é o erro mais comum com proxies no Puppeteer.

Rotacionando geo e sessões através de um único gateway

Aqui está a consequência útil desse design. O host do proxy é fixado na inicialização do navegador e você não pode alterá-lo por página, mas você não precisa disso. Como a segmentação vive no nome de usuário e page.authenticate é definido por página, dar a cada página um nome de usuário diferente a direciona por uma identidade diferente no mesmo gateway. Um navegador, muitas geos, sem reiniciar.

async function pageFor(browser, country, sid) {
  const page = await browser.newPage();
  const user = `${process.env.SHIFTER_USER}-country-${country}`
    + (sid ? `-sid-${sid}-ttl-600` : '');
  await page.authenticate({ username: user, password: process.env.SHIFTER_PASS });
  return page;
}

const de = await pageFor(browser, 'de', 'job-42');   // sessão persistente na Alemanha
const us = await pageFor(browser, 'us', null);        // rotação nos EUA

Dê a cada unidade lógica de trabalho seu próprio sid e faça a rotação entre unidades, não no meio de uma sessão (o sticky vs rotating cobre essa distinção), e mapeie o trabalho para identidades da forma descrita no post sobre balanceamento de carga. Para isolamento de cookies e armazenamento entre identidades, coloque cada uma em seu próprio contexto de navegador:

const context = await browser.createBrowserContext();  // cookies/armazenamento isolados
const page = await context.newPage();
await page.authenticate({ username: userFor('gb'), password: pass });

Note o nome: versões recentes do Puppeteer chamam isso de createBrowserContext(), versões mais antigas chamavam de createIncognitoBrowserContext(). Mesma ideia, renomeada.

Armadilha 1: reutilize o navegador, nunca inicie um por requisição

Iniciar o Chromium é pesado, um navegador novo por requisição custa centenas de milissegundos de inicialização mais memória real toda vez, a sobrecarga que o guia de latência existe para eliminar. Inicie um navegador na inicialização e reutilize-o, abrindo páginas ou contextos para trabalho concorrente e fechando-os quando terminar. Um pool de páginas sob um navegador de longa duração é o formato correto.

Armadilha 2: bloqueie os recursos que você não precisa

Um navegador busca tudo o que um navegador real busca: imagens, fontes, mídia, folhas de estilo, análises. Se você só quer o HTML ou alguns campos, isso é largura de banda que você está pagando e tempo que você está esperando. O Puppeteer permite interceptar requisições e abortar as que você não precisa, o que reduz substancialmente tanto o tempo de carregamento da página quanto a sua conta de largura de banda.

await page.setRequestInterception(true);
page.on('request', (req) => {
  const blocked = ['image', 'font', 'media', 'stylesheet'];
  if (blocked.includes(req.resourceType())) req.abort();
  else req.continue();
});

Seja seletivo: alguns sites não renderizam o conteúdo que você quer sem o CSS deles ou um script específico, então bloqueie de forma agressiva e depois confirme que os dados ainda aparecem. Quando aparecem, essa é a otimização de velocidade mais barata disponível em um navegador headless.

Armadilha 3: o navegador é apenas metade de não ser bloqueado

Um IP residencial cuida da metade de rede de parecer humano, mas o Puppeteer ainda está controlando o Chromium headless, e os sites também identificam o navegador, navigator.webdriver, peculiaridades específicas do modo headless e sinais de automação. Um IP limpo com boa reputação mantém você fora de muitos desafios, mas não disfarça um navegador claramente automatizado. Use uma versão atual do Puppeteer e do Chromium para obter o modo headless moderno em vez do antigo, facilmente detectável, mantenha o viewport e o user-agent realistas, e conduza a página em um ritmo humano. Os erros que disparam detecção se aplicam à camada do navegador tanto quanto à camada de IP, e as duas precisam estar alinhadas.

Armadilha 4: limite sua concorrência

Cada página aberta é uma aba de navegador real ocupando memória real, então você não pode abrir milhares da forma que poderia disparar requisições HTTP. Mantenha um pool limitado de páginas ou contextos e reutilize-os, e limite o trabalho em andamento por host de destino para que um site frágil não seja sobrecarregado enquanto um mais permissivo fica sem uso. Mais paralelismo além da tolerância de um alvo traz bloqueios e falhas por falta de memória, não vazão (como evitar ser bloqueado).

Verifique se você realmente está no proxy

Antes de fazer benchmark ou depurar qualquer outra coisa, confirme o IP de saída de dentro da página:

await page.goto('http://ip-api.com/json');
console.log(await page.evaluate(() => document.body.innerText));  // espere o país segmentado

Seu próprio IP significa que a flag --proxy-server não foi aplicada. Uma travada em um diálogo 407 significa que page.authenticate está ausente ou as credenciais estão erradas. Uma travada geral significa que a saída local está bloqueada. Os três casos são cobertos no guia de diagnóstico de timeout.

Perguntas frequentes

Por que colocar user:pass@host em --proxy-server não funciona? O Chromium não lê credenciais de proxy da flag --proxy-server. Passe apenas o host ali e forneça as credenciais com page.authenticate({ username, password }), que lida com o desafio 407 do proxy. Como o gateway codifica a segmentação no nome de usuário, o nome de usuário completo (com -country-...) vai em page.authenticate.

Como uso um país diferente por página se o proxy é definido na inicialização? Você não muda o host do proxy, você muda o nome de usuário em page.authenticate. Como a segmentação vive no nome de usuário e o host do gateway é constante, cada página pode autenticar com um nome de usuário diferente e sair por uma identidade diferente. Um navegador atende muitas geos.

Posso rotacionar o proxy sem reiniciar o navegador? Sim, para identidade e geo, variando o nome de usuário em page.authenticate por página ou contexto. Você só reiniciaria se precisasse de um host de proxy genuinamente diferente, o que não é o caso com um único endpoint de gateway.

Como reduzo a largura de banda no Puppeteer? Ative a interceptação de requisições e aborte os tipos de recurso que você não precisa (imagens, fontes, mídia, muitas vezes folhas de estilo). Confirme que o alvo ainda renderiza os dados que você quer, e então mantenha os bloqueios. É a maior alavanca isolada tanto de velocidade quanto de custo em um navegador headless.

Puppeteer ou Playwright? Ambos controlam navegadores reais e ambos funcionam bem com proxies residenciais. O Playwright recebe o proxy (com credenciais) diretamente em suas opções de contexto; o Puppeteer o divide entre a flag de inicialização mais page.authenticate. Escolha com base no ecossistema e no código existente; os conceitos de proxy são os mesmos.

Conclusão

Puppeteer mais proxies residenciais é simples uma vez que a divisão faz sentido: o host do proxy vai em --proxy-server na inicialização, e as credenciais, carregando sua segmentação no nome de usuário, vão em page.authenticate por página. Faça a rotação de geo e sessões variando esse nome de usuário em vez de reiniciar, isole identidades com contextos de navegador, reutilize um navegador de longa duração, bloqueie os recursos que você não precisa, e lembre-se de que a impressão digital do navegador precisa parecer tão humana quanto o IP.

Acerte isso e o Puppeteer lida com os alvos ricos em JavaScript que clientes HTTP simples não conseguem. Aponte-o para o gateway residencial, e lembre-se de que a qualidade do pool decide o quanto você é desafiado, no geral (reputação de IP). A página de preços tem os planos por GB para testar contra seus próprios alvos.