Instalando e configurando o Puppeteer: como resolver problemas comuns de dependências e Chromium

Quer automatizar o Chrome ou Chromium com facilidade? Puppeteer é uma biblioteca do Node.js que simplifica a automação de navegadores, perfeita para tarefas como testes e scraping. Veja o que você aprenderá:

• Integração direta na Latenode: Saiba como a Latenode aprimora fluxos de scraping da web com uma integração direta ao navegador headless baseado em Puppeteer e recursos voltados à automação. Não é preciso pré-configurar nada: basta adicionar o nó e usá-lo na automação de fluxos!
• Requisitos de configuração: Use Node.js 18+ e verifique se o sistema atende às dependências específicas do sistema operacional.
• Opções de instalação: Instale o Puppeteer com npm i puppeteer (inclui o Chrome for Testing) ou npm i puppeteer-core (use seu próprio navegador).
• Dicas de solução de problemas: Corrija erros de inicialização do Chromium, bibliotecas ausentes e conflitos de dependências.
• Configurações avançadas: Otimize o desempenho, configure proxies e gerencie variáveis de ambiente.

Antes de compartilharmos um guia completo sobre problemas de configuração do Puppeteer, você deve saber que pode simplesmente ignorá-lo e usar um nó de integração direta pronto na Latenode! Confira:

Não Configure o Puppeteer: Use Nossa Integração Pronta na Latenode

A Latenode funciona perfeitamente com o Puppeteer para simplificar a automação de navegadores. A seguir, vamos explorar os recursos da Latenode e como usar uma integração direta com o Puppeteer para suas necessidades de automação.

Veja um resumo dos principais recursos da Latenode:

"O que mais gostei na Latenode em comparação com a concorrência foi a possibilidade de escrever código e criar nós personalizados." — Germaine H., Fundadora de Tecnologia da Informação [3]

Ferramentas da Latenode

A Latenode oferece integração com o nó de navegador headless, baseado no Puppeteer, que permite adicionar código diretamente no editor e usá-lo em tarefas como extrair todas as informações disponíveis de um site, tirar capturas de tela de páginas, preencher formulários e, em geral, fazer tudo o que o Puppeteer suporta.

Para encontrar essa integração, basta acessar a pasta Code Integrations na biblioteca de nós, onde você encontrará o nó de navegador headless. Adicione-o ao seu script, clique nele e um editor será aberto, permitindo adicionar códigos de qualquer complexidade e extensão. Além disso, você pode especificar o endereço, login e senha do seu Proxy nas configurações.

Conectando o Navegador Headless Baseado em Puppeteer a Outras Integrações

Mas um nó não é suficiente para a automação. Para uma personalização maior, adicione um gatilho e outra ação. Por exemplo, um gatilho de webhook e uma resposta para monitorar alterações nas taxas de câmbio do Banco da Inglaterra, como mostramos no guia acima. Veja um fluxo:

FLUXO

Por Que Escolher a Integração da Latenode em Vez de uma Solução Baseada em VPS?

"A Latenode supera a concorrência com 99% de uptime, preços acessíveis baseados em execução e uma interface fácil de usar." — Hammad Hafeez [3]

Os preços da Latenode são baseados no tempo de execução, e não em tarefas individuais, tornando-a uma opção econômica para automações do Puppeteer em grande escala. Essa plataforma permite que desenvolvedores se concentrem na criação de fluxos robustos sem se preocupar com custos excessivos.

Para maximizar a eficiência, você pode usar a integração da Latenode com JavaScript, além de mais de 300 integrações com bancos de dados, CRM, ferramentas de gerenciamento de projetos e modelos de IA como Claude, ChatGPT e Gemini. Há muitos casos de uso em potencial: prospecção automatizada, gerenciamento de banco de dados, scraping da web etc. Ao combinar Latenode e Puppeteer, você pode centralizar e otimizar seus processos de automação.

sbb-itb-23997f1

Se você ainda quiser um guia para corrigir problemas do Puppeteer, confira a análise abaixo.

Falha ao Iniciar o Chromium em uma VPS? Instale as Dependências Ausentes do Puppeteer na VPS

Antes de Começar

Antes de instalar o Puppeteer, verifique se sua configuração atende às dependências necessárias para garantir uma instalação e operação sem problemas.

Configuração do Node.js

O Puppeteer exige o Node.js para funcionar. As versões mais recentes do Puppeteer são compatíveis com o Node.js versão 18 ou superior, alinhado à versão LTS atual.

Para verificar sua versão do Node.js, use este comando:

node --version

Se sua versão for inferior à 18, atualize o Node.js antes de continuar. É altamente recomendável usar a versão LTS mais recente. Após confirmar sua versão do Node.js, verifique os requisitos do sistema operacional.

Requisitos do Sistema

Os requisitos de sistema do Puppeteer dependem do sistema operacional que você usa. Veja um resumo:

Ao instalar o Puppeteer, ele fará o download automático de uma versão compatível do Chrome for Testing. O tamanho do download varia conforme o sistema operacional (~280MB para Windows, ~170MB para macOS e ~282MB para Debian/Ubuntu Linux) [1].

Para usuários de Linux, especialmente Debian/Ubuntu, será necessário instalar algumas bibliotecas adicionais. Use o seguinte comando:

apt-get install -y libx11-xcb1 libxcomposite1 libxcursor1 libxdamage1 libxi6 libxtst6 libnss3 libcups2 libxss1 libxrandr2 libasound2 libatk1.0-0 libgtk-3-0

Confira algumas dicas adicionais para ambientes específicos:

• AWS EC2 Amazon Linux: Habilite o repositório EPEL e instale o Chromium antes de configurar o Puppeteer.
• Ambientes Docker: Adicione as bibliotecas compartilhadas necessárias e o pacote Chromium ao seu Dockerfile.
• Projetos em TypeScript: use o TypeScript versão 4.7.4 ou superior para acessar as definições de tipos mais recentes do Puppeteer e melhorar o suporte da IDE.

Etapas Básicas de Instalação

Depois de confirmar a configuração do Node.js e os requisitos do sistema, você poderá instalar o Puppeteer usando npm.

Guia de Instalação com npm

Há duas formas de instalar o Puppeteer via npm:

• Instalação padrão: Esta opção faz o download automático do Chrome for Testing:

  npm i puppeteer
  

• Instalação Core: Use esta opção se quiser gerenciar os navegadores separadamente e não baixar o Chrome for Testing:

  npm i puppeteer-core
  

Com a instalação padrão, o Chrome for Testing e o binário chrome-headless-shell são baixados para $HOME/.cache/puppeteer. Consulte a seção Requisitos do Sistema para obter detalhes sobre os tamanhos de download.

Após a instalação, você estará pronto para testar sua configuração.

Testando Sua Configuração

Comece criando um arquivo chamado test.js e adicione o seguinte script:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com');
  console.log('Page title:', await page.title());
  await browser.close();
})();

Execute o script com:

node test.js

Se o script for executado com sucesso e exibir o título da página, sua instalação está funcionando corretamente.

Dicas de Solução de Problemas

• Usuários de Linux: Use seu gerenciador de pacotes para garantir que todas as dependências necessárias estejam instaladas.
• Usuários de Windows: Verifique se as permissões do sandbox do Chrome estão configuradas corretamente.
• Se o Chrome não for encontrado em seu local padrão, defina a variável de ambiente PUPPETEER_CACHE_DIR para apontar ao diretório de instalação correto.

"Executar sem um sandbox é fortemente desaconselhado. Considere configurar um sandbox." [2]

Para ter mais estabilidade e facilitar a manutenção, você pode criar um arquivo .puppeteerrc.cjs para configurar o comportamento do Puppeteer, em vez de passar argumentos diretamente ao método launch.

Corrigindo Problemas do Chromium

Problemas com o Chromium geralmente decorrem de bibliotecas ausentes ou configurações incorretas.

Usando o Chromium Local

Se preferir usar uma instalação existente do Chromium em vez de baixar uma nova, o Puppeteer pode ser configurado para funcionar com seu navegador local. Esse método é útil caso você precise de uma versão específica do Chromium ou gerencie manualmente as instalações do navegador.

Para conectar o Puppeteer ao seu Chromium local, ajuste suas configurações de inicialização desta forma:

const browser = await puppeteer.launch({ executablePath: '/usr/bin/chromium-browser' });

Verifique se todas as bibliotecas necessárias estão instaladas. No Linux, você pode identificar bibliotecas ausentes com:

ldd chrome | grep not

Se usar uma instalação local não for uma opção, considere instalar o Chromium separadamente seguindo as etapas abaixo.

Instalando o Chromium Separadamente

A partir do Puppeteer v20.0.0, o Chrome for Testing é baixado em vez do Chromium.

Visão geral da compatibilidade:

Se você encontrar o erro "Failed to launch chrome", tente estas soluções:

1. Verifique as dependências: Instale bibliotecas ausentes em sistemas baseados em Debian:

   sudo apt-get install -y libasound2 libatk1.0-0 libgbm-dev
   

2. Ajuste as configurações de memória: Em ambientes Docker, aumente o tamanho de /dev/shm ou use a flag --disable-dev-shm-usage:

   const browser = await puppeteer.launch({
     args: ['--disable-dev-shm-usage']
   });
   

3. Defina tempos limite de navegação: Evite travamentos definindo um tempo limite de navegação personalizado, como 60 segundos:

   await page.setDefaultNavigationTimeout(60000); // 60 seconds
   

"O Chrome headless precisa de muitas dependências para funcionar, e o Puppeteer não instala todas elas." — savebreach.com

Para ambientes como GitLab CI ou casos em que o sandbox está desabilitado (não recomendado), inclua argumentos específicos de inicialização:

const browser = await puppeteer.launch({
  args: ['--no-sandbox', '--disable-setuid-sandbox']
});

Para ignorar avisos relacionados a HTTPS nas versões recentes do Chrome, desabilite o recurso HttpsFirstBalancedModeAutoEnable:

const browser = await puppeteer.launch({
  args: ['--disable-features=HttpsFirstBalancedModeAutoEnable']
});

Gerenciando Dependências

Gerenciar dependências de forma eficaz é essencial para evitar falhas na inicialização e comportamentos imprevisíveis. Esta seção aborda como resolver conflitos de versão e manter pacotes atualizados para prevenir erros em tempo de execução.

Corrigindo Conflitos de Pacotes

Conflitos de pacotes geralmente levam a erros como "Cannot find module 'puppeteer-core/internal/...'" ou problemas ao iniciar o Chrome. Veja como resolver esses problemas:

// Example: Resolving version conflicts using package.json overrides
{
  "overrides": {
    "ws": "^8.17.1",
    "debug": "^4.3.4"
  }
}

Etapas para solucionar problemas:

• Verifique a versão do Node.js: Certifique-se de usar Node.js 18 ou superior. Versões mais antigas podem causar problemas de compatibilidade.
• Verifique as bibliotecas do sistema: No Linux, garanta que todas as bibliotecas de sistema necessárias estejam instaladas. Consulte a lista de dependências na seção Requisitos do Sistema.
• Revise as políticas do Chrome: As políticas do Chrome podem entrar em conflito com a flag padrão --disable-extensions do Puppeteer. Tente iniciar sem ela:

const browser = await puppeteer.launch({
  ignoreDefaultArgs: ['--disable-extensions']
});

Depois que os conflitos forem resolvidos, atualize seus pacotes para garantir estabilidade contínua.

Mantendo os Pacotes Atualizados

Atualizar dependências regularmente reduz riscos de segurança e garante a compatibilidade. Veja como gerenciar esse processo:

• Acompanhe as dependências

Use uma tabela simples para monitorar versões de pacotes, datas de atualização e sua importância:

• Gerenciamento de versões

Ao atualizar, use intervalos de versionamento semântico com cuidado. Para dependências críticas, fixe versões exatas para evitar alterações inesperadas:

{
  "dependencies": {
    "puppeteer": "24.4.0",
    "puppeteer-core": "24.4.0"
  }
}

• Solução de problemas em atualizações

Gere um relatório detalhado de dependências com:

npm list --all > dependency-report.txt

Esse relatório ajuda a identificar conflitos e dependências aninhadas problemáticas.

Para ambientes como Docker ou GitLab CI, verifique se sua configuração inclui os pacotes de sistema necessários:

RUN apt-get update && apt-get install -y \
    chromium \
    libnss3 \
    libgconf-2-4 \
    libxss1

Configurações Adicionais

Ajuste o Puppeteer para configurações avançadas com estas configurações adicionais.

Variáveis de Ambiente

As variáveis de ambiente permitem ajustar o comportamento do Puppeteer e substituir configurações padrão.

Estas são algumas variáveis importantes:

Para instalações personalizadas do Chromium, defina o caminho do executável desta forma:

const browser = await puppeteer.launch({
  executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || puppeteer.executablePath()
});

Depois de definir as variáveis de ambiente, você pode configurar proxies para lidar com restrições de rede de forma eficaz.

Configuração de Proxy

Para usar um servidor proxy com o Puppeteer, aplique a seguinte configuração:

// Launch Puppeteer with a proxy server and authentication
const browser = await puppeteer.launch({
  args: ['--proxy-server=http://157.230.255.230:8118']
});

await page.authenticate({
  username: 'proxyUser',
  password: 'proxyPass'
});

// Optimize navigation with specific settings
await page.goto('https://example.com', {
  waitUntil: 'networkidle2',
  timeout: 30000
});

Inclua tratamento de erros para garantir um desempenho robusto em produção:

try {
  await page.goto(url);
} catch (error) {
  console.error('Proxy connection failed:', error.message);
  // Add fallback logic or retry mechanism
}

Para configurações corporativas, exporte as definições de proxy no terminal:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="https://proxy.company.com:8443"
export NO_PROXY="localhost,127.0.0.1,.company.internal"

Você também pode validar conexões de proxy programaticamente:

const validateProxy = async (page) => {
  try {
    await page.goto('https://api.ipify.org?format=json');
    const content = await page.content();
    return content.includes('ip');
  } catch {
    return false;
  }
};

Isso garante que sua configuração de proxy esteja funcionando corretamente antes de prosseguir.

Próximas Etapas

Checklist de Configuração

Antes de começar com a automação do Puppeteer, verifique se seu ambiente está configurado corretamente. Use o script abaixo para validar sua configuração:

// Validation script for environment setup
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.validateEnvironment();  // Custom validation
await browser.close();

Depois de verificar sua configuração, você pode se concentrar em melhorar seus fluxos para obter melhores resultados de automação.

Dicas para Começar

O sistema de PDF da Carriyo processou com eficiência 10.000 etiquetas de envio por dia, alcançando uma latência p95 de 365ms [4]. Para atingir níveis de desempenho semelhantes, considere estas estratégias:

• Gerenciamento de recursos: Desative recursos desnecessários para economizar recursos. Por exemplo, inicie o Puppeteer com configurações otimizadas:

  const browser = await puppeteer.launch({
    headless: true,
    args: ['--disable-dev-shm-usage'],
    defaultViewport: { width: 1920, height: 1080 }
  });
  

• Tratamento de erros: Use métodos robustos de recuperação de erros, como blocos try-catch e manipuladores de erro personalizados para problemas específicos.

• Otimização de desempenho: Aumente a velocidade ao:

  • Armazenar em cache dados usados com frequência
  • Interceptar solicitações de rede
  • Executar tarefas em paralelo
  • Usar o Chrome DevTools para monitorar o desempenho

Para automações mais avançadas, explore a plataforma de fluxos low-code da Latenode. Ela oferece preços baseados em execução e diversos recursos para simplificar implementações complexas do Puppeteer [3].