Como Executar Puppeteer no Docker Sem Enviar o Chrome em Seu App

TL;DR:

• Os deployments do Puppeteer no Docker falham quando o pacote Node, o executável do Chrome e o runtime do Linux são tratados como uma dependência invisível. Faça cada limite explícito.
• A imagem oficial é a base completa mais rápida. Ela empacota Puppeteer, Chrome para Testes e bibliotecas necessárias sob uma tag de lançamento conhecida.
• Uma imagem do Chrome do sistema dá controle do sistema operacional, mas torna a instalação e compatibilidade do Chrome de sua responsabilidade. Defina os dois lados e execute um teste de fumaça durante a construção.
• puppeteer-core contém o cliente sem baixar o Chrome. Combine-o com um navegador operado separadamente quando a imagem do aplicativo deve permanecer livre de navegadores.
• Scrapeless Scraping Browser permite que o contêiner do aplicativo se conecte a um navegador em nuvem gerenciado. O ciclo de vida do Chrome, dependências do navegador e egressos do navegador deixam a imagem do Node.js.
• Grátis para começar. Novas contas Scrapeless incluem um runtime gratuito do Scraping Browser — inscreva-se em app.scrapeless.com.

Introdução: Puppeteer Precisa de um Contrato de Navegador

npm install puppeteer não é toda a implantação. Puppeteer também precisa de um executável do Chrome compatível, bibliotecas compartilhadas do Linux, fontes, um diretório de perfil gravável, memória suficiente e um modelo de processo que feche os processos filhos de forma limpa.

O Docker torna essas dependências reproduzíveis apenas quando estão anotadas. Uma imagem oficial as anota para você. Uma imagem personalizada move o contrato para seu Dockerfile. Um design de navegador remoto mantém o contrato fora da imagem do aplicativo e deixa puppeteer-core como cliente.

Este guia usa Puppeteer Core 25.8.0 e Scrapeless SDK 1.11.0, ambos instalados durante a verificação. O pacote local lançou um executável do Chrome fornecido fora de seu pacote npm e retornou o título da página esperado.

Por que Puppeteer Precisa de Mais do que npm Install no Docker

Puppeteer e Puppeteer Core resolvem problemas de empacotamento diferentes.

A escolha do pacote não configura PID 1, memória compartilhada, o sandbox do navegador, fontes, certificados ou limites de recursos do contêiner. Estes permanecem como responsabilidades de implantação.

Pré-requisitos

• Node.js 20 para o contêiner de aplicativos.
• Docker para os padrões de imagem oficial e Chrome do sistema.
• Puppeteer Core 25.8.0 para o padrão de aplicativo livre de navegador.
• Uma conta Scrapeless e chave API para o navegador em nuvem gerenciado.
• Um alvo público ou explicitamente autorizado.

Nota: O Docker não está disponível no ambiente de verificação, por isso as construções de imagem e os comandos docker run são rotulados como lacunas de pré-requisitos. O Puppeteer Core 25.8.0 foi instalado e lançado contra um executável do Chrome fora do pacote; o SDK Scrapeless carregou e expôs sua função de conexão do Puppeteer, mas nenhuma chave estava disponível para uma sessão na nuvem.

Opção 1 — Começar a partir da Imagem Oficial do Puppeteer

A imagem oficial inclui o Chrome para Testes, suas dependências do sistema e uma versão correspondente do Puppeteer. o guia do Puppeteer Docker documenta a imagem e seus requisitos de runtime orientados ao sandbox.

Fixe a imagem em vez de usar latest:

FROM ghcr.io/puppeteer/puppeteer:25.8.0

WORKDIR /home/pptruser/app
COPY --chown=pptruser:pptruser package.json package-lock.json ./
RUN npm ci
COPY --chown=pptruser:pptruser . .

CMD ["node", "capture.mjs"]

A imagem documentada executa o Chrome com seu sandbox, então o runtime do contêiner deve fornecer a capacidade necessária. Também precisa de um processo de init para gerenciar os filhos do navegador:

docker build -t puppeteer-job:25.8.0 .
docker run --rm --init --cap-add=SYS_ADMIN puppeteer-job:25.8.0

Conceda capacidades apenas após revisar a carga de trabalho e o runtime. a orientação de segurança para contêineres do NIST separa risco da imagem, risco de registro, controles de orquestrador, controles de runtime e controles de host.

Opção 2 — Instalar o Chrome do Sistema Você Mesmo

Uma imagem do Chrome do sistema personalizada é apropriada quando a organização já gerencia um repositório de navegador, cadeia de certificados, fontes ou imagem base.

O aplicativo deve apontar o Puppeteer Core para o executável instalado:

import puppeteer from "puppeteer-core";

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

const page = await browser.newPage();
await page.setContent("<title>Chrome outside the npm package</title>");
console.log(await page.title());
await browser.close();

A verificação executada usou um executável externo do Chrome e imprimiu Chrome outside the npm package. Isso confirma que puppeteer-core não precisou enviar o navegador que controlava.

Seu Dockerfile agora é responsável pela instalação e compatibilidade do Chrome. Fique com o pacote do navegador, afirme sua versão durante a construção da imagem e execute o script de lançamento antes de publicar a imagem.

Cinco Falhas de Contêiner para Diagnosticar Separadamente

As falhas do contêiner do Puppeteer tornam-se mais fáceis de resolver quando o erro é mapeado para um limite.

Os namespaces do Linux isolam visões de processos, montagens, usuários e recursos de rede. o manual de namespaces do Linux descreve esses primitivos de isolamento. O sandbox do navegador e a fronteira do contêiner se complementam; um não substitui o outro.

Comece a Raspagem com Scrapeless

Potencialize seu fluxo de trabalho de raspagem e automação na web com Scrapeless!
Inscreva-se hoje e receba $5 em créditos gratuitos — sem necessidade de cartão de crédito.

Reivindique seu crédito gratuito agora no Painel do Scrapeless.

Mova o Chrome para Fora do Contêiner do Aplicativo

Uma imagem de aplicativo sem navegador instala puppeteer-core, abre uma sessão de navegador remoto, realiza o trabalho de página aprovado e fecha a conexão. O serviço do navegador escala e é atualizado de forma independente.

Instale os pacotes exatos usados no projeto de verificação:

npm install puppeteer-core@25.8.0 @scrapeless-ai/sdk@1.11.0

Nota: A conexão a seguir requer sua chave de API do Scrapeless. A exportação do SDK instalada foi verificada localmente, mas o ambiente sem credenciais não conseguiu abrir o navegador na nuvem.

import { Puppeteer } from "@scrapeless-ai/sdk";

const browser = await Puppeteer.connect({
  sessionName: "browser-free-app",
  sessionTTL: 300,
  proxyCountry: "US",
  defaultViewport: null,
});

const page = await browser.newPage();
await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
console.log(await page.title());
await browser.close();

O Scrapeless Scraping Browser é a camada do navegador neste padrão. Revise a introdução rápida ao Scraping Browser, a página do produto e preços antes de adotá-lo no CI.

Componha o Aplicativo em Torno da Fronteira Remota

O contêiner do aplicativo não precisa mais de um serviço Chrome no mesmo projeto Compose. Precisa apenas do código Node.js, seu arquivo lock, o cliente Puppeteer Core e um segredo fornecido em tempo de execução.

services:
  worker:
    build: .
    init: true
    environment:
      SCRAPELESS_API_KEY: ${SCRAPELESS_API_KEY}
    read_only: true
    tmpfs:
      - /tmp:size=64m

Este arquivo Compose expressa a fronteira do aplicativo, não o navegador na nuvem. A chave da API vem do armazenamento de segredos de implantação. O trabalhador possui um sistema de arquivos raiz somente leitura e um diretório temporário delimitado.

A configuração de runtime da Open Container Initiative define o processo, ambiente, montagens e recursos do Linux que os runtimes traduzem para o processo do contêiner.

Escolha o Padrão Certo

Use a imagem oficial quando um artefato completo e correspondente do Puppeteer e Chrome for mais valioso do que uma imagem pequena. Instale o Chrome do sistema quando sua equipe de plataforma já possuir a distribuição do navegador e a política do sistema operacional. Use o Puppeteer Core com o Scrapeless Scraping Browser quando o aplicativo não deve enviar ou operar o Chrome.

A decisão pode variar conforme o trabalho. A renderização de PDF para um modelo interno pode permanecer em uma imagem local fixada. A extração de web pública que necessita de egressos de navegador regional pode pertencer a um navegador na nuvem gerenciado. Mantenha ambos atrás do mesmo contrato de trabalho para que os chamadores não dependam da localização do navegador.

O exemplo de Puppeteer do navegador na nuvem do Scrapeless mostra a conexão gerenciada em um fluxo de trabalho de automação mais amplo.

Lista de Verificação de Operações

• Fixe as versões do Puppeteer, Chrome, imagem base e arquivo lock.
• Execute um lançamento do navegador e uma verificação de título antes de publicar a imagem.
• Use um processo de inicialização e feche sessões do navegador em finally.
• Preserve o sandbox do navegador para páginas não confiáveis.
• Defina limites de CPU, memória, IPC e armazenamento temporário explicitamente.
• Coloque chaves de API no armazenamento de segredos em tempo de execução, nunca nas camadas da imagem.
• Mantenha não mais que três trabalhadores simultâneos por host de destino, a menos que o proprietário aprove outro limite.
• Registre o pacote, navegador, imagem, região e revisão de trabalho com a saída.

Conclusão: Desacople o Cliente do Chrome

Puppeteer torna-se mais fácil de operar quando o pacote do cliente e o tempo de execução do navegador são decisões separadas e visíveis. A imagem oficial os agrupa. Uma imagem personalizada permite que sua equipe possua ambos. Puppeteer Core e Scrapeless Scraping Browser os dividem em uma conexão gerenciada.

Escolha um contrato por tipo de trabalho, fixe-o e teste o limite do navegador antes que a carga de trabalho do aplicativo comece.

Pronto para Executar Puppeteer Sem Chrome na Imagem do Aplicativo?

Junte-se à nossa comunidade para reivindicar um plano gratuito e conectar-se com desenvolvedores que separam as cargas de trabalho do navegador dos serviços Node.js: Discord · Telegram.

Inscreva-se em app.scrapeless.com para um tempo de execução gratuito do Scraping Browser e teste o padrão de trabalhador sem navegador.

FAQ

Q: O Puppeteer Core inclui o Chrome?

O Puppeteer Core não baixa ou gerencia o Chrome. Ele necessita de um caminho executável explícito ou de uma conexão de navegador remoto.

Q: A imagem oficial do Puppeteer é mais segura do que uma imagem personalizada?

A imagem oficial fornece uma base documentada de navegador e dependências, mas a segurança ainda depende da proveniência da imagem, capacidades de tempo de execução, identidade do usuário, política de sandbox, controles do host e das páginas sendo abertas.

Q: Por que o Chrome falha apenas dentro do Docker?

O contêiner pode estar sem o executável, uma biblioteca vinculada, suporte a sandbox, memória compartilhada, fontes ou um processo de inicialização adequado. Inspecione o limite que falha em vez de mudar o código de navegação primeiro.

Q: Um navegador Puppeteer remoto precisa de um proxy?

O navegador remoto precisa de uma política de saída que corresponda ao trabalho. O Scrapeless Scraping Browser suporta proxies residenciais em mais de 195 países; fixe o país aprovado para uma execução consistente.

Q: O que deve acontecer quando os seletores mudam?

Verifique novamente a página renderizada e atualize os seletores contra funções, atributos ou estruturas de dados estáveis. Mover o Chrome para fora do Docker não congela o DOM alvo.

Q: Quanta concorrência um trabalhador Puppeteer deve usar?

Mantenha não mais do que três trabalhadores por host alvo a menos que o proprietário aprove um limite diferente. A capacidade da frota do navegador e a concorrência do host alvo são controles separados.

Q: O Puppeteer Core pode se conectar sem um agente de IA?

Sim. Puppeteer Core e o Scrapeless SDK são interfaces diretas do Node.js. Um agente de IA é opcional e não deve alterar as regras de acesso, concorrência ou manipulação de segredos.