Cómo ejecutar Puppeteer en Docker sin incluir Chrome en tu aplicación

TL;DR:

• Las implementaciones de Puppeteer en Docker fallan cuando el paquete de Node, el ejecutable de Chrome y el tiempo de ejecución de Linux se tratan como una dependencia invisible. Haga que cada límite sea explícito.
• La imagen oficial es la línea base completa más rápida. Empaqueta Puppeteer, Chrome for Testing y las bibliotecas requeridas bajo una etiqueta de lanzamiento conocida.
• Una imagen de sistema-Chrome le da control sobre el sistema operativo, pero hace que la instalación y compatibilidad de Chrome sean su responsabilidad. Fije ambos lados y ejecute una verificación básica de lanzamiento durante la construcción.
• puppeteer-core contiene el cliente sin descargar Chrome. Combínelo con un navegador operado por separado cuando la imagen de la aplicación deba permanecer libre de navegadores.
• Scraping Browser sin raspar permite que el contenedor de la aplicación se conecte a un navegador en la nube gestionado. El ciclo de vida de Chrome, las dependencias del navegador y la salida del navegador abandonan la imagen de Node.js.
• Gratis para empezar. Nuevas cuentas de Scrapeless incluyen tiempo de ejecución gratuito de Scraping Browser: regístrese en app.scrapeless.com.

Introducción: Puppeteer Necesita un Contrato de Navegador

npm install puppeteer no es toda la implementación. Puppeteer también necesita un ejecutable de Chrome compatible, bibliotecas compartidas de Linux, fuentes, un directorio de perfil escribible, suficiente memoria y un modelo de proceso que cierre los procesos hijos limpiamente.

Docker hace que esas dependencias sean reproducibles solo cuando están escritas. Una imagen oficial las escribe por usted. Una imagen personalizada mueve el contrato a su Dockerfile. Un diseño de navegador remoto mantiene el contrato fuera de la imagen de la aplicación y deja puppeteer-core como el cliente.

Esta guía utiliza Puppeteer Core 25.8.0 y Scrapeless SDK 1.11.0, ambos instalados durante la verificación. El paquete local lanzó un ejecutable de Chrome proporcionado fuera de su paquete npm y devolvió el título de página esperado.

Por qué Puppeteer Necesita Más Que npm Install en Docker

Puppeteer y Puppeteer Core resuelven diferentes problemas de empaquetado.

La elección del paquete no configura el PID 1, la memoria compartida, la caja de arena del navegador, las fuentes, los certificados o los límites de recursos del contenedor. Esas siguen siendo responsabilidades de implementación.

Requisitos Previos

• Node.js 20 para el contenedor de la aplicación.
• Docker para los patrones de imagen oficial y sistema-Chrome.
• Puppeteer Core 25.8.0 para el patrón de aplicación libre de navegador.
• Una cuenta de Scrapeless y clave API para el navegador en la nube gestionado.
• Un objetivo público o autorizado explícitamente.

Nota: Docker no está disponible en el entorno de verificación, por lo que las construcciones de imágenes y los comandos docker run están etiquetados como brechas de requisitos previos. Puppeteer Core 25.8.0 fue instalado y lanzado contra un ejecutable de Chrome fuera del paquete; el SDK de Scrapeless cargó y expuso su función de conexión de Puppeteer, pero no había clave disponible para una sesión en la nube.

Opción 1 — Comenzar Desde la Imagen Oficial de Puppeteer

La imagen oficial incluye Chrome para Pruebas, sus dependencias del sistema y una versión de Puppeteer coincidente. la guía de Docker de Puppeteer documenta la imagen y sus requisitos de ejecución orientados a la caja de arena.

Fije la imagen en lugar 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"]

La imagen documentada ejecuta Chrome con su caja de arena, por lo que el tiempo de ejecución del contenedor debe proporcionar la capacidad requerida. También necesita un proceso de inicialización para gestionar los hijos del navegador:

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

Otorgue capacidades solo después de revisar la carga de trabajo y el tiempo de ejecución. La guía de seguridad de contenedores de NIST separa el riesgo de imagen, riesgo de registro, controles de orquestador, controles de tiempo de ejecución y controles del host.

Opción 2 — Instalar Chrome del Sistema Usted Mismo

Una imagen de sistema-Chrome personalizada es apropiada cuando la organización ya gestiona un repositorio de navegadores, cadena de certificados, fuentes o imagen base.

La aplicación debe señalar a Puppeteer Core el ejecutable 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();

La verificación ejecutada utilizó un ejecutable de Chrome externo e imprimió Chrome outside the npm package. Eso confirma que puppeteer-core no necesitaba enviar el navegador que controlaba.

Su Dockerfile ahora es propietario de la instalación y compatibilidad de Chrome. Fije el paquete del navegador, afirme su versión durante la construcción de la imagen y ejecute el script de lanzamiento antes de publicar la imagen.

Cinco Fallos de Contenedor para Diagnosticar Por Separado

Los fallos de contenedor de Puppeteer se vuelven más fáciles de resolver cuando el error se asigna a un límite.

Los espacios de nombres de Linux aíslan las vistas de procesos, montajes, usuarios y recursos de red. el manual de espacios de nombres de Linux describe esos primitivos de aislamiento. El sandbox del navegador y el límite del contenedor se complementan entre sí; uno no reemplaza al otro.

Comienza a raspar con Scrapeless

¡Potencia tu flujo de trabajo de raspado web y automatización con Scrapeless!
Regístrate hoy y obtén $5 en crédito gratuito — sin necesidad de tarjeta de crédito.

Reclama tu crédito gratuito ahora en el Tablero de Scrapeless.

Mueve Chrome fuera del contenedor de la aplicación

Una imagen de aplicación sin navegador instala puppeteer-core, abre una sesión de navegador remoto, realiza el trabajo de página aprobado y cierra la conexión. El servicio del navegador se escala y actualiza de manera independiente.

Instala los paquetes exactos utilizados en el proyecto de verificación:

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

Nota: La siguiente conexión requiere tu clave de API de Scrapeless. La exportación del SDK instalado fue verificada localmente, pero el entorno sin credenciales no pudo abrir el navegador en la nube.

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();

Scrapeless Scraping Browser es la capa de navegador en este patrón. Revisa el inicio rápido del navegador de raspado, página del producto y precios antes de adoptarlo en CI.

Compón la aplicación alrededor del límite remoto

El contenedor de la aplicación ya no necesita un servicio Chrome en el mismo proyecto de Docker Compose. Solo necesita el código de Node.js, su archivo de bloqueo, el cliente de Puppeteer Core y un secreto suministrado en tiempo de ejecución.

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

Este archivo de Docker Compose expresa el límite de la aplicación, no el navegador en la nube. La clave de API proviene del almacén de secretos de implementación. El trabajador tiene un sistema de archivos raíz de solo lectura y un directorio temporal limitado.

La configuración de ejecución de Open Container Initiative define el proceso, el entorno, los montajes y los recursos de Linux que las ejecuciones traducen en el proceso del contenedor.

Elige el patrón correcto

Usa la imagen oficial cuando un artefacto completo de Puppeteer y Chrome coincido sea más valioso que una imagen pequeña. Instala Chrome del sistema cuando tu equipo de plataforma ya tenga la distribución del navegador y la política del sistema operativo. Usa Puppeteer Core con Scrapeless Scraping Browser cuando la aplicación no deba enviar o operar Chrome.

La decisión puede variar según el trabajo. El renderizado de PDF para una plantilla interna puede permanecer en una imagen local fija. La extracción de web pública que necesita salida de navegador regional puede pertenecer a un navegador en la nube gestionado. Mantén ambos bajo el mismo contrato de trabajo para que los llamadores no dependan de la ubicación del navegador.

El ejemplo de Puppeteer del navegador en la nube de Scrapeless muestra la conexión gestionada en un flujo de trabajo de automatización más amplio.

Lista de verificación de operaciones

• Fija las versiones de Puppeteer, Chrome, imagen base y archivo de bloqueo.
• Ejecuta un lanzamiento de navegador y una afirmación de título antes de publicar la imagen.
• Usa un proceso de inicialización y cierra las sesiones del navegador en finally.
• Preserva el sandbox del navegador para páginas no confiables.
• Establece límites explícitos de CPU, memoria, IPC y almacenamiento temporal.
• Coloca las claves de API en el almacén de secretos de ejecución, nunca en las capas de imagen.
• No mantengas más de tres trabajadores concurrentes por host de destino a menos que el propietario apruebe otro límite.
• Registra el paquete, el navegador, la imagen, la región y la revisión del trabajo con la salida.

Conclusión: Desacopla el cliente de Chrome

Puppeteer se vuelve más fácil de operar cuando el paquete del cliente y el runtime del navegador son decisiones separadas y visibles. La imagen oficial los agrupa. Una imagen personalizada permite a su equipo poseer ambos. Puppeteer Core y Scrapeless Scraping Browser los dividen a través de una conexión administrada.

Elija un contrato por tipo de trabajo, fíjelo y pruebe el límite del navegador antes de que comience la carga de trabajo de la aplicación.

¿Listo para ejecutar Puppeteer sin Chrome en la imagen de la aplicación?

Únase a nuestra comunidad para reclamar un plan gratuito y conectarse con desarrolladores que separan las cargas de trabajo del navegador de los servicios de Node.js: Discord · Telegram.

Regístrese en app.scrapeless.com para obtener el runtime gratuito de Scraping Browser y probar el patrón de trabajador sin navegador.

FAQ

P: ¿Incluye Puppeteer Core Chrome?

Puppeteer Core no descarga ni gestiona Chrome. Necesita una ruta ejecutable explícita o una conexión a un navegador remoto.

P: ¿Es la imagen oficial de Puppeteer más segura que una imagen personalizada?

La imagen oficial proporciona una base de datos documentada de navegador y dependencias, pero la seguridad aún depende del origen de la imagen, capacidades de runtime, identidad del usuario, políticas de sandbox, controles del host y las páginas que se abren.

P: ¿Por qué Chrome falla solo dentro de Docker?

El contenedor puede carecer del ejecutable, una biblioteca vinculada, soporte de sandbox, memoria compartida, fuentes o un proceso init adecuado. Inspeccione el límite fallido en lugar de cambiar el código de navegación primero.

P: ¿Necesita un navegador Puppeteer remoto un proxy?

El navegador remoto necesita una política de salida que coincida con el trabajo. Scrapeless Scraping Browser admite proxies residenciales en más de 195 países; fije el país aprobado para una ejecución constante.

P: ¿Qué debería suceder cuando cambian los selectores?

Vuelva a verificar la página renderizada y actualice los selectores contra roles, atributos o estructuras de datos estables. Mover Chrome fuera de Docker no congela el DOM objetivo.

P: ¿Cuánta concurrencia debería usar un trabajador de Puppeteer?

No mantenga más de tres trabajadores por host objetivo a menos que el propietario apruebe otro límite. La capacidad de la flota del navegador y la concurrencia del host objetivo son controles separados.

P: ¿Puede Puppeteer Core conectarse sin un agente de IA?

Sí. Puppeteer Core y el SDK de Scrapeless son interfaces directas de Node.js. Un agente de IA es opcional y no debería cambiar las reglas de acceso, concurrencia o manejo de secretos.