Integração de Proxy com Puppeteer e Playwright: guia completo com exemplos de código

Puppeteer e Playwright são ferramentas populares para automação de navegador e web scraping. Ao trabalhar com grandes volumes de solicitações ou scraping de sites protegidos, o uso de proxies se torna criticamente importante para evitar bloqueios por IP. Neste guia, abordaremos todas as maneiras de integrar proxies em ambas as ferramentas, desde a configuração básica até cenários avançados com rotação e tratamento de erros.

Fundamentos do uso de proxies em navegadores headless

Puppeteer e Playwright controlam navegadores reais (Chromium, Firefox, WebKit) através do DevTools Protocol. Isso significa que o proxy é configurado no nível de inicialização do navegador, e não em solicitações individuais. Ambas as ferramentas suportam proxies HTTP, HTTPS e SOCKS5, mas têm APIs diferentes para sua configuração.

As principais diferenças em relação a bibliotecas HTTP comuns (axios, fetch):

• Proxy é definido na inicialização do navegador — não é possível mudar o proxy em tempo real dentro de uma única sessão do navegador
• Suporte a JavaScript e renderização — o proxy se aplica a todos os recursos da página (imagens, scripts, XHR)
• Tratamento automático de redirecionamentos e cookies — o navegador se comporta como um usuário real
• Fingerprinting — mesmo com proxies, os sites podem identificar a automação com base nas características do navegador

Configuração de proxy no Puppeteer

Puppeteer é uma biblioteca do Google para controlar o Chrome/Chromium. O proxy é configurado através de argumentos de inicialização do navegador usando a flag --proxy-server.

Configuração básica de proxy HTTP/HTTPS

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true,
    args: [
      '--proxy-server=http://proxy.example.com:8080'
    ]
  });

  const page = await browser.newPage();
  
  // Verificando o endereço IP
  await page.goto('https://api.ipify.org?format=json');
  const content = await page.content();
  console.log('IP atual:', content);

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

Este código inicia o navegador através do servidor proxy. Todas as solicitações HTTP e HTTPS passarão pelo proxy especificado. Para verificar a funcionalidade, é utilizado o serviço ipify, que retorna o endereço IP externo.

Configuração de proxy SOCKS5

const browser = await puppeteer.launch({
  headless: true,
  args: [
    '--proxy-server=socks5://proxy.example.com:1080'
  ]
});

// O restante do código é semelhante

Proxies SOCKS5 operam em um nível mais baixo e suportam tráfego UDP, o que pode ser útil para algumas aplicações web. A sintaxe é idêntica à do proxy HTTP, apenas o protocolo no URL é alterado.

Uso de proxy para domínios específicos

const browser = await puppeteer.launch({
  args: [
    '--proxy-server=http://proxy1.example.com:8080',
    '--proxy-bypass-list=localhost;127.0.0.1;*.internal.com'
  ]
});

// Solicitações locais e solicitações para *.internal.com irão diretamente
// Todas as outras — através do proxy

A flag --proxy-bypass-list permite excluir determinados domínios da proxy. Isso é útil quando é necessário combinar solicitações diretas e proxy.

Configuração de proxy no Playwright

Playwright é uma biblioteca mais moderna da Microsoft, que suporta Chromium, Firefox e WebKit. O proxy é configurado através de um objeto de configuração, o que torna a API mais clara e tipada.

Configuração básica de proxy

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

(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://proxy.example.com:8080'
    }
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  
  await page.goto('https://api.ipify.org?format=json');
  const ip = await page.textContent('body');
  console.log('IP através do proxy:', ip);

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

Playwright utiliza o objeto proxy em vez de argumentos de linha de comando. Isso proporciona uma melhor tipagem em TypeScript e um código mais limpo.

Configuração de proxy no nível do contexto

const browser = await chromium.launch();

// Contexto 1 - com proxy
const context1 = await browser.newContext({
  proxy: {
    server: 'http://proxy1.example.com:8080'
  }
});

// Contexto 2 - com outro proxy
const context2 = await browser.newContext({
  proxy: {
    server: 'http://proxy2.example.com:8080'
  }
});

const page1 = await context1.newPage();
const page2 = await context2.newPage();

// Cada página usa seu próprio proxy!

Uma das principais vantagens do Playwright é a capacidade de criar vários contextos de navegador com proxies diferentes dentro de um único processo. Isso economiza recursos ao trabalhar com vários endereços IP.

Exclusão de domínios da proxy

const browser = await chromium.launch({
  proxy: {
    server: 'http://proxy.example.com:8080',
    bypass: 'localhost,127.0.0.1,*.internal.com'
  }
});

// Solicitações para localhost e *.internal.com irão diretamente

Autenticação por login e senha

A maioria dos proxies comerciais requer autenticação. Ambas as ferramentas suportam autorização, mas a implementam de maneiras diferentes.

Autenticação no Puppeteer

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://proxy.example.com:8080']
});

const page = await browser.newPage();

// Definindo as credenciais para o proxy
await page.authenticate({
  username: 'your_username',
  password: 'your_password'
});

await page.goto('https://httpbin.org/ip');
const content = await page.content();
console.log(content);

O método page.authenticate() define as credenciais para todas as solicitações subsequentes nesta página. É importante chamá-lo ANTES do primeiro page.goto().

Autenticação no Playwright

const browser = await chromium.launch({
  proxy: {
    server: 'http://proxy.example.com:8080',
    username: 'your_username',
    password: 'your_password'
  }
});

const page = await browser.newPage();
await page.goto('https://httpbin.org/ip');

O Playwright permite especificar as credenciais diretamente no objeto de configuração do proxy — isso é mais conveniente e seguro, pois não requer chamadas de métodos adicionais.

Método alternativo: credenciais na URL

// Funciona em ambos os frameworks
const proxyUrl = 'http://username:password@proxy.example.com:8080';

// Puppeteer
const browser = await puppeteer.launch({
  args: [`--proxy-server=${proxyUrl}`]
});

// Playwright
const browser = await chromium.launch({
  proxy: { server: proxyUrl }
});

Este método funciona, mas não é recomendado para produção — as credenciais podem acabar nos logs. Use variáveis de ambiente para armazenar dados sensíveis.

Rotação de proxies e gerenciamento de pool de IPs

Para scraping em grande escala, é necessário trocar regularmente os endereços IP. Como o proxy é definido na inicialização do navegador, a rotação requer a reinicialização da sessão do navegador.

Rotação simples com um array de proxies (Puppeteer)

const puppeteer = require('puppeteer');

const proxyList = [
  'http://user1:pass1@proxy1.example.com:8080',
  'http://user2:pass2@proxy2.example.com:8080',
  'http://user3:pass3@proxy3.example.com:8080'
];

async function scrapeWithRotation(urls) {
  for (let i = 0; i < urls.length; i++) {
    const proxyUrl = proxyList[i % proxyList.length];
    
    const browser = await puppeteer.launch({
      args: [`--proxy-server=${proxyUrl}`]
    });

    try {
      const page = await browser.newPage();
      await page.goto(urls[i], { waitUntil: 'networkidle0' });
      
      const data = await page.evaluate(() => {
        return {
          title: document.title,
          url: window.location.href
        };
      });
      
      console.log(`URL ${i + 1}:`, data);
    } catch (error) {
      console.error(`Erro em ${urls[i]}:`, error.message);
    } finally {
      await browser.close();
    }
  }
}

const urlsToScrape = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3',
  'https://example.com/page4'
];

scrapeWithRotation(urlsToScrape);

Este código percorre ciclicamente os proxies da lista e inicia um novo navegador para cada URL. O método i % proxyList.length garante a rotação cíclica.

Rotação com pool de contextos (Playwright)

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

const proxyList = [
  { server: 'http://proxy1.example.com:8080', username: 'user1', password: 'pass1' },
  { server: 'http://proxy2.example.com:8080', username: 'user2', password: 'pass2' },
  { server: 'http://proxy3.example.com:8080', username: 'user3', password: 'pass3' }
];

async function scrapeWithContextPool(urls) {
  const browser = await chromium.launch();
  
  // Criando um pool de contextos com diferentes proxies
  const contexts = await Promise.all(
    proxyList.map(proxy => browser.newContext({ proxy }))
  );

  for (let i = 0; i < urls.length; i++) {
    const context = contexts[i % contexts.length];
    const page = await context.newPage();
    
    try {
      await page.goto(urls[i], { waitUntil: 'networkidle' });
      const title = await page.title();
      console.log(`URL ${i + 1} (proxy ${i % contexts.length}):`, title);
    } catch (error) {
      console.error(`Erro em ${urls[i]}:`, error.message);
    } finally {
      await page.close();
    }
  }

  await browser.close();
}

const urls = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3'
];

scrapeWithContextPool(urls);

O Playwright permite criar vários contextos em um único navegador, cada um com seu proxy. Isso economiza memória e tempo de inicialização em comparação com a reinicialização completa do navegador.

Rotação inteligente com rastreamento de erros

class ProxyRotator {
  constructor(proxyList) {
    this.proxyList = proxyList;
    this.currentIndex = 0;
    this.failedProxies = new Set();
  }

  getNext() {
    const availableProxies = this.proxyList.filter(
      (_, index) => !this.failedProxies.has(index)
    );

    if (availableProxies.length === 0) {
      throw new Error('Todos os proxies estão indisponíveis');
    }

    const proxy = this.proxyList[this.currentIndex];
    this.currentIndex = (this.currentIndex + 1) % this.proxyList.length;
    
    return { proxy, index: this.currentIndex - 1 };
  }

  markFailed(index) {
    this.failedProxies.add(index);
    console.log(`Proxy ${index} marcado como indisponível`);
  }

  resetFailed() {
    this.failedProxies.clear();
  }
}

// Uso
const rotator = new ProxyRotator(proxyList);

async function scrapeWithSmartRotation(url, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const { proxy, index } = rotator.getNext();
    
    const browser = await chromium.launch({ proxy });
    const page = await browser.newPage();

    try {
      await page.goto(url, { timeout: 30000 });
      const data = await page.content();
      await browser.close();
      return data;
    } catch (error) {
      console.error(`Erro com o proxy ${index}:`, error.message);
      rotator.markFailed(index);
      await browser.close();
      
      if (attempt === maxRetries - 1) {
        throw new Error(`Não foi possível carregar ${url} após ${maxRetries} tentativas`);
      }
    }
  }
}

Esta classe rastreia proxies que não funcionam e os exclui da rotação. Em caso de erro, ela alterna automaticamente para o próximo proxy da lista.

Tratamento de erros e verificação de funcionalidade

Ao trabalhar com proxies, surgem erros específicos: timeouts de conexão, negação de autorização, bloqueio de IP pelo site de destino. O tratamento correto de erros é crítico para a operação estável do scraper.

Erros típicos e seu tratamento

async function safePageLoad(page, url, options = {}) {
  const defaultOptions = {
    timeout: 30000,
    waitUntil: 'networkidle0',
    maxRetries: 3,
    retryDelay: 2000
  };

  const config = { ...defaultOptions, ...options };

  for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
    try {
      await page.goto(url, {
        timeout: config.timeout,
        waitUntil: config.waitUntil
      });
      
      return { success: true, attempt };
    } catch (error) {
      console.error(`Tentativa ${attempt} falhou:`, error.message);

      // Analisando o tipo de erro
      if (error.message.includes('ERR_PROXY_CONNECTION_FAILED')) {
        throw new Error('Proxy indisponível');
      }
      
      if (error.message.includes('ERR_TUNNEL_CONNECTION_FAILED')) {
        throw new Error('Erro de tunelamento do proxy');
      }

      if (error.message.includes('407')) {
        throw new Error('Erro de autorização do proxy (407)');
      }

      if (error.message.includes('Navigation timeout')) {
        console.log(`Timeout de carregamento, repetindo em ${config.retryDelay}ms`);
        await new Promise(resolve => setTimeout(resolve, config.retryDelay));
        continue;
      }

      // Se esta for a última tentativa - propague o erro
      if (attempt === config.maxRetries) {
        throw error;
      }
    }
  }
}

Verificação de funcionalidade do proxy

async function testProxy(proxyConfig) {
  const browser = await chromium.launch({ proxy: proxyConfig });
  const page = await browser.newPage();

  const result = {
    working: false,
    ip: null,
    responseTime: null,
    error: null
  };

  const startTime = Date.now();

  try {
    await page.goto('https://api.ipify.org?format=json', { timeout: 10000 });
    const content = await page.textContent('body');
    const data = JSON.parse(content);
    
    result.working = true;
    result.ip = data.ip;
    result.responseTime = Date.now() - startTime;
  } catch (error) {
    result.error = error.message;
  } finally {
    await browser.close();
  }

  return result;
}

// Testando a lista de proxies
async function validateProxyList(proxyList) {
  console.log('Verificando proxies...');
  
  const results = await Promise.all(
    proxyList.map(async (proxy, index) => {
      const result = await testProxy(proxy);
      console.log(`Proxy ${index + 1}:`, result.working ? `✓ ${result.ip} (${result.responseTime}ms)` : `✗ ${result.error}`);
      return { proxy, ...result };
    })
  );

  const workingProxies = results.filter(r => r.working);
  console.log(`\nProxies funcionais: ${workingProxies.length}/${proxyList.length}`);
  
  return workingProxies.map(r => r.proxy);
}

Esta função verifica cada proxy antes de usá-lo, mede o tempo de resposta e retorna apenas proxies funcionais. É recomendável executar a validação ao iniciar o aplicativo.

Monitoramento e registro

class ProxyMonitor {
  constructor() {
    this.stats = {
      totalRequests: 0,
      successfulRequests: 0,
      failedRequests: 0,
      proxyErrors: 0,
      averageResponseTime: 0,
      requestsByProxy: new Map()
    };
  }

  recordRequest(proxyIndex, success, responseTime, error = null) {
    this.stats.totalRequests++;
    
    if (success) {
      this.stats.successfulRequests++;
      this.stats.averageResponseTime = 
        (this.stats.averageResponseTime * (this.stats.successfulRequests - 1) + responseTime) / 
        this.stats.successfulRequests;
    } else {
      this.stats.failedRequests++;
      if (error && error.includes('proxy')) {
        this.stats.proxyErrors++;
      }
    }

    // Estatísticas para cada proxy
    if (!this.stats.requestsByProxy.has(proxyIndex)) {
      this.stats.requestsByProxy.set(proxyIndex, { success: 0, failed: 0 });
    }
    
    const proxyStats = this.stats.requestsByProxy.get(proxyIndex);
    success ? proxyStats.success++ : proxyStats.failed++;
  }

  getReport() {
    const successRate = (this.stats.successfulRequests / this.stats.totalRequests * 100).toFixed(2);
    
    return {
      ...this.stats,
      successRate: `${successRate}%`,
      averageResponseTime: `${this.stats.averageResponseTime.toFixed(0)}ms`
    };
  }
}

// Uso
const monitor = new ProxyMonitor();

async function monitoredScrape(url, proxyIndex) {
  const startTime = Date.now();
  try {
    // ... código de scraping ...
    const responseTime = Date.now() - startTime;
    monitor.recordRequest(proxyIndex, true, responseTime);
  } catch (error) {
    monitor.recordRequest(proxyIndex, false, 0, error.message);
    throw error;
  }
}

Cenários avançados: geolocalização e fingerprinting

Sistemas modernos anti-bot verificam não apenas o endereço IP, mas também a correspondência da geolocalização, fuso horário, idioma do navegador e outros parâmetros. Ao usar proxies de outro país, é importante configurar todos esses parâmetros corretamente.

Configuração de geolocalização e idioma para o proxy

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

async function createContextWithGeo(proxy, geoData) {
  const browser = await chromium.launch({ proxy });
  
  const context = await browser.newContext({
    locale: geoData.locale,           // 'pt-BR', 'de-DE', 'fr-FR'
    timezoneId: geoData.timezone,     // 'America/Sao_Paulo', 'Europe/Berlin'
    geolocation: {
      latitude: geoData.latitude,
      longitude: geoData.longitude
    },
    permissions: ['geolocation']
  });

  return { browser, context };
}

// Exemplo: proxy da Alemanha
const germanyProxy = {
  server: 'http://de-proxy.example.com:8080',
  username: 'user',
  password: 'pass'
};

const germanyGeo = {
  locale: 'de-DE',
  timezone: 'Europe/Berlin',
  latitude: 52.520008,
  longitude: 13.404954
};

const { browser, context } = await createContextWithGeo(germanyProxy, germanyGeo);
const page = await context.newPage();

await page.goto('https://www.google.com');
// O Google mostrará a versão alemã com resultados para Berlim

Este código configura o navegador para parecer um usuário real da Alemanha: idioma da interface em alemão, fuso horário de Berlim e coordenadas do centro de Berlim.

Configuração completa de fingerprint

async function createStealthContext(proxy, profile) {
  const context = await chromium.launch({ proxy }).then(b => 
    b.newContext({
      locale: profile.locale,
      timezoneId: profile.timezone,
      userAgent: profile.userAgent,
      viewport: profile.viewport,
      deviceScaleFactor: profile.deviceScaleFactor,
      isMobile: profile.isMobile,
      hasTouch: profile.hasTouch,
      colorScheme: profile.colorScheme,
      geolocation: profile.geolocation,
      permissions: ['geolocation']
    })
  );

  return context;
}

// Perfil para Windows 10 + Chrome dos EUA
const desktopUSProfile = {
  locale: 'en-US',
  timezone: 'America/New_York',
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  viewport: { width: 1920, height: 1080 },
  deviceScaleFactor: 1,
  isMobile: false,
  hasTouch: false,
  colorScheme: 'light',
  geolocation: { latitude: 40.7128, longitude: -74.0060 }
};

// Perfil para iPhone do Reino Unido
const mobileUKProfile = {
  locale: 'en-GB',
  timezone: 'Europe/London',
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  colorScheme: 'light',
  geolocation: { latitude: 51.5074, longitude: -0.1278 }
};

A configuração completa de fingerprint reduz a probabilidade de detecção da automação. É importante que todos os parâmetros correspondam entre si: por exemplo, um User-Agent móvel deve vir acompanhado de uma resolução de tela móvel.

Evitando vazamento de WebRTC

// Puppeteer: bloqueando WebRTC
const browser = await puppeteer.launch({
  args: [
    '--proxy-server=http://proxy.example.com:8080',
    '--disable-webrtc',
    '--disable-webrtc-hw-encoding',
    '--disable-webrtc-hw-decoding'
  ]
});

// Playwright: redefinindo a API do WebRTC
const context = await browser.newContext({ proxy: proxyConfig });

await context.addInitScript(() => {
  // Bloqueando RTCPeerConnection
  window.RTCPeerConnection = undefined;
  window.RTCDataChannel = undefined;
  window.RTCSessionDescription = undefined;
  
  // Redefinindo getUserMedia
  navigator.mediaDevices.getUserMedia = undefined;
  navigator.getUserMedia = undefined;
});

O WebRTC pode revelar seu endereço IP real mesmo ao usar um proxy. Este código desativa completamente a API do WebRTC no navegador.

Comparação entre Puppeteer e Playwright para uso de proxies

Recomendações para escolha

Escolha Puppeteer se:

• Trabalha apenas com Chrome/Chromium
• Usa um proxy por vez
• Precisa de máxima compatibilidade com ferramentas existentes
• Já possui uma grande base de código em Puppeteer

Escolha Playwright se:

• Precisa trabalhar com Firefox ou Safari (WebKit)
• Requer o uso simultâneo de múltiplos proxies
• Importa desempenho ao escalar
• Está escrevendo em TypeScript
• Começa um novo projeto do zero

Desempenho na rotação de proxies

Teste: scraping de 100 páginas com rotação de 10 proxies em um MacBook Pro M1:

O Playwright com pool de contextos é quase duas vezes mais rápido devido à ausência de sobrecarga na inicialização do navegador. Isso é crítico ao fazer scraping de milhares de páginas.

Conclusão

A integração de proxies com Puppeteer e Playwright é uma prática padrão para web scraping, testes e automação. O Puppeteer oferece simplicidade e um ecossistema amplo, enquanto o Playwright oferece uma API moderna e melhor desempenho ao trabalhar com múltiplos proxies através de contextos de navegador.

Pontos-chave que abordamos:

• Configuração básica de proxies HTTP, HTTPS e SOCKS5 em ambas as frameworks
• Autenticação por login e senha
• Rotação de proxies para scraping em grande escala
• Tratamento de erros e validação de proxies antes do uso
• Configuração de geolocalização e fingerprint para contornar sistemas anti-bot
• Comparação de desempenho entre diferentes abordagens

Para soluções de produção, recomendamos combinar proxies de qualidade com uma configuração adequada de fingerprint, tratamento de erros e monitoramento. Isso garantirá a operação estável do scraper mesmo em sites protegidos.

Se você planeja fazer scraping de sites comerciais, marketplaces ou trabalhar com plataformas de publicidade, recomendamos usar proxies residenciais — eles oferecem máxima anonimidade e mínimo risco de bloqueios devido a endereços IP reais de usuários domésticos.