Instalación y configuración de Puppeteer: Solución de problemas comunes de dependencias y Chromium

¿Quieres automatizar Chrome o Chromium con facilidad? Titiritero es un Node.js Biblioteca que simplifica la automatización del navegador, ideal para tareas como pruebas y scraping. Aprenderás lo siguiente:

Integración directa en Latenode: Aprende cómo Nodo tardío Mejora los flujos de trabajo de raspado web con un Integración directa con el navegador sin interfaz gráfica basado en Puppeteer Y funciones fáciles de automatizar. No es necesario preconfigurar nada, ¡solo agregue el nodo y úselo en la automatización del flujo de trabajo!
Requisitos de instalación:Utilice Node.js 18+ y asegúrese de que su sistema cumpla con las dependencias específicas del sistema operativo.
Opciones de instalación:Instalar Puppeteer con npm i puppeteer (incluye Chrome para pruebas) o npm i puppeteer-core (utilice su propio navegador).
Consejos para solucionar problemas: Corrige errores de inicio de Chromium, bibliotecas faltantes y conflictos de dependencia.
Configuraciones avanzadas:Optimice el rendimiento, configure servidores proxy y administre variables de entorno.

Antes de compartir una guía completa sobre los problemas de configuración de Puppeteer, debes saber que puedes omitirla y usar un nodo de integración directo y listo para usar en Latenode. Échale un vistazo:

Omitir la configuración de Puppeteer: utilice nuestra integración lista para usar en Nodo tardío

Latenode se integra a la perfección con Puppeteer para simplificar la automatización del navegador. A continuación, exploraremos las características de Latenode y cómo usar una integración directa con Puppeteer para sus necesidades de automatización.

A continuación se muestra un desglose de las características principales de Latenode:

Característica	Descripción	Beneficio
Navegador sin cabeza	Integración de la biblioteca Puppeteer	Control directo del navegador
Asistente de código AI	Generación de código automatizada	Acelera la depuración y la codificación.
Flexibilidad sin código	Más de 300 integraciones sin código para ajustes personalizados del flujo de trabajo	Amplía la funcionalidad de Puppeteer
Compatibilidad con paquetes NPM	Acceso a más de 1 millón de paquetes	Aumenta las capacidades de automatización

Lo que más me gustó de Latenode en comparación con la competencia es que pude escribir código y crear nodos personalizados. - Germaine H., Fundadora de Tecnología de la Información [ 3 ]

Nodo tardío Accesorios

Latenode ofrece integración con el nodo Headless Browser, que se basa en Puppeteer y le permite agregar código directamente en el editor y usarlo para tareas como extraer toda la información disponible de un sitio web, tomar capturas de pantalla de páginas, completar formularios y, en general, cualquier cosa que Puppeteer admita.

Para encontrar esta integración, simplemente dirígete a la carpeta "Integraciones de Código" en la biblioteca de nodos, donde encontrarás el nodo "Navegador Headless". Añádelo a tu script, haz clic en él y se abrirá un editor donde podrás añadir código de cualquier complejidad y longitud. Además, puedes especificar la dirección, el nombre de usuario y la contraseña de tu proxy en la configuración.

Conexión del navegador headless basado en Puppeteer con otras integraciones

Pero un solo nodo no es suficiente para la automatización. Para una mayor personalización, añada un disparador y otra acción. Por ejemplo, un disparador de webhook y una respuesta para monitorear las fluctuaciones del tipo de cambio en el Banco de Inglaterra, como se muestra en la guía anterior. A continuación, se muestra un escenario:

ESCENARIO

¿Por qué elegir la integración de Latenode en lugar de una solución basada en VPS?

Latenode supera a la competencia con un 99 % de tiempo de actividad, precios accesibles basados en la ejecución y una interfaz intuitiva. - Hammad Hafeez [ 3 ]

El precio de Latenode se basa en el tiempo de ejecución, no en las tareas individuales, lo que lo convierte en una opción económica para la automatización a gran escala de Puppeteer. Esta plataforma permite a los desarrolladores centrarse en crear flujos de trabajo robustos sin preocuparse por costes excesivos.

Para maximizar la eficiencia, puede utilizar la integración con Javascript de Latenode, un total de 300 integraciones con bases de datos, CRM, herramientas de gestión de proyectos y modelos de inteligencia artificial como Claude, ChatGPT y Gemini. Hay muchos casos de uso potenciales: divulgación automatizada, gestión de bases de datos, web scraping, etc. Al combinar Latenode y Puppeteer, puede centralizar y optimizar sus procesos de automatización.

sbb-itb-23997f1

Si aún quieres una guía sobre cómo solucionar los problemas de Puppeteer, consulta el desglose a continuación.

¿No se pudo iniciar Chromium en el VPS? Instale las dependencias faltantes en el VPS puppetter.

Antes de que empieces

Antes de instalar Puppeteer, asegúrese de que su configuración cumpla con las dependencias necesarias para garantizar una instalación y un funcionamiento sin problemas.

Node.js Configuración

Se requiere titiritero Node.js para ejecutar. Las últimas versiones de Puppeteer funcionan con Node.js versión 18 o superior, que se alinea con la versión LTS actual.

Para comprobar su versión de Node.js, use este comando:

node --version

Si su versión es inferior a la 18, actualice Node.js antes de continuar. Se recomienda encarecidamente usar la última versión LTS. Tras confirmar su versión de Node.js, verifique los requisitos del sistema operativo de su sistema.

Requisitos del sistema

Los requisitos del sistema para Puppeteer dependen del sistema operativo que uses. Aquí tienes un breve resumen:

Sistema operativo	Arquitectura	Componentes requeridos	Tamaño aproximado de descarga
Windows	x64	Chrome para pruebas	~ 280MB
macOS	x64, arm64	Chrome para pruebas	~ 170MB
Debian / Ubuntu	x64	Chrome para pruebas + Bibliotecas	~ 282MB

Al instalar Puppeteer, se descargará automáticamente una versión compatible de Chrome para realizar pruebas. El tamaño de la descarga varía según el sistema operativo (aproximadamente 280 MB para Windows, 170 MB para macOS y 282 MB para Debian/Ubuntu Linux). [ 1 ].

Los usuarios de Linux, especialmente de Debian/Ubuntu, necesitarán instalar algunas bibliotecas adicionales. Usen el siguiente comando:

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

A continuación se ofrecen algunos consejos adicionales para entornos específicos:

AWS EC2 Amazon Linux:Habilite el repositorio EPEL e instale Chromium antes de configurar Puppeteer.
Entornos Docker:Agregue las bibliotecas compartidas necesarias y el paquete Chromium a su Dockerfile.
TypeScript Proyectos: Utilice TypeScript versión 4.7.4 o superior para acceder a las últimas definiciones de tipos de Puppeteer y mejorar el soporte IDE.

Pasos básicos de instalación

Una vez que haya confirmado la configuración de Node.js y los requisitos del sistema, puede instalar Puppeteer usando npm.

Guía de instalación de npm

Tienes dos formas de instalar Puppeteer a través de npm:

Instalación estándar:Esta opción descarga automáticamente Chrome para realizar pruebas:
```
npm i puppeteer
```
Instalación del núcleo:Use esto si desea administrar los navegadores por separado y omitir la descarga de Chrome para realizar pruebas:
```
npm i puppeteer-core
```

Con la instalación estándar, Chrome para pruebas y el chrome-headless-shell Los binarios se descargan a $HOME/.cache/puppeteer. Consulte la sección Requisitos del sistema para obtener detalles sobre el tamaño de las descargas.

Una vez instalado, estará listo para probar su configuración.

Probar su configuración

Comience creando un archivo llamado test.js y agrega el siguiente script:

<span class="hljs-keyword">const</span> puppeteer = <span class="hljs-built_in">require</span>(<span class="hljs-string">'puppeteer'</span>);

(<span class="hljs-title function_">async</span> () => {
  <span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>();
  <span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://www.google.com'</span>);
  <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Page title:'</span>, <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">title</span>());
  <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();
})();

Ejecute el script con:

node test.js

Si el script se ejecuta correctamente y muestra el título de la página, su instalación está funcionando correctamente.

Consejos para solucionar problemas

Usuarios de Linux:Utilice su administrador de paquetes para asegurarse de que todas las dependencias necesarias estén instaladas.
Usuarios de Windows:Verifique que los permisos del sandbox de Chrome estén configurados correctamente.
Si Chrome no se encuentra en su ubicación predeterminada, configure el PUPPETEER_CACHE_DIR Variable de entorno para señalar el directorio de instalación correcto.

"Correr sin un arenero es fuertemente desanimadoConsidere configurar un entorno de pruebas en su lugar." [ 2 ]

Para una mejor estabilidad y un mantenimiento más sencillo, puede crear un .puppeteerrc.cjs archivo para configurar el comportamiento de Puppeteer en lugar de pasar argumentos directamente al launch método.

Solución de problemas de Chromium

Los problemas de Chromium a menudo se deben a bibliotecas faltantes o configuraciones incorrectas.

Uso de Chromium local

Si prefieres usar una instalación de Chromium existente en lugar de descargar una nueva, puedes configurar Puppeteer para que funcione con tu navegador local. Este método es útil si necesitas una versión específica de Chromium o si gestionas la instalación del navegador manualmente.

Para vincular Puppeteer con tu Chromium local, ajusta tu configuración de inicio de esta manera:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({ <span class="hljs-attr">executablePath</span>: <span class="hljs-string">'/usr/bin/chromium-browser'</span> });

Asegúrese de que todas las bibliotecas necesarias estén instaladas. En Linux, puede identificar las bibliotecas que faltan con:

ldd chrome | grep not

Si usar una instalación local no es una opción, considere instalar Chromium por separado siguiendo los pasos a continuación.

Instalación de Chromium por separado

A partir de Puppeteer v20.0.0, se descarga Chrome para pruebas en lugar de Chromium.

Descripción general de compatibilidad:

Versión del titiritero	Versión del navegador	Tamaño de la descarga
v24.4.0	Chrome para pruebas 134.0.6998.35	~170 MB (Mac OS)
v24.3.1	Chrome para pruebas 133.0.6943.141	~282 MB (Linux)
v24.3.0	Chrome para pruebas 133.0.6943.126	~280 MB (Windows)

Si encuentra un error de "Error al iniciar Chrome", pruebe estas soluciones:

Comprobar dependencias:Instale cualquier biblioteca faltante en los sistemas basados en Debian:
```
<span class="hljs-built_in">sudo</span> apt-get install -y libasound2 libatk1.0-0 libgbm-dev
```

Ajustar la configuración de la memoria:Para entornos Docker, aumente /dev/shm tamaño o utilizar el --disable-dev-shm-usage bandera:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--disable-dev-shm-usage'</span>]
});

Establecer tiempos de espera de navegación:Evite bloqueos configurando un tiempo de espera de navegación personalizado, como 60 segundos:

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">setDefaultNavigationTimeout</span>(<span class="hljs-number">60000</span>); <span class="hljs-comment">// 60 seconds</span>

Chrome(-ium) sin interfaz gráfica necesita muchas dependencias para funcionar, y Puppetteer no las instala todas. - savebreach.com

Para entornos como GitLab CI o casos donde el sandbox está deshabilitado (no recomendado), incluya argumentos de lanzamiento específicos:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--no-sandbox'</span>, <span class="hljs-string">'--disable-setuid-sandbox'</span>]
});

Para evitar las advertencias relacionadas con HTTPS en versiones recientes de Chrome, desactive la función HttpsFirstBalancedModeAutoEnable:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--disable-features=HttpsFirstBalancedModeAutoEnable'</span>]
});

Manejo de dependencias

Gestionar las dependencias eficazmente es crucial para evitar fallos de inicio y comportamientos impredecibles. Esta sección explica cómo resolver conflictos de versiones y mantener los paquetes actualizados para evitar errores de ejecución.

Solución de conflictos de paquetes

Los conflictos de paquetes suelen provocar errores como "No se puede encontrar el módulo 'puppeteer-core/internal/...'" o problemas al iniciar Chrome. Aquí te explicamos cómo solucionar estos problemas:

<span class="hljs-comment">// Example: Resolving version conflicts using package.json overrides</span>
{
  <span class="hljs-string">"overrides"</span>: {
    <span class="hljs-string">"ws"</span>: <span class="hljs-string">"^8.17.1"</span>,
    <span class="hljs-string">"debug"</span>: <span class="hljs-string">"^4.3.4"</span>
  }
}

Pasos para solucionar problemas:

Comprobar la versión de Node.jsAsegúrate de usar Node.js 18 o superior. Las versiones anteriores pueden causar problemas de compatibilidad.
Verificar bibliotecas del sistemaEn Linux, asegúrese de que todas las bibliotecas del sistema necesarias estén instaladas. Consulte la lista de dependencias en la sección "Requisitos del sistema".
Revisar las políticas de Chrome:Las políticas de Chrome pueden entrar en conflicto con las predeterminadas de Puppeteer --disable-extensions bandera. Intenta iniciar sin ella:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">ignoreDefaultArgs</span>: [<span class="hljs-string">'--disable-extensions'</span>]
});

Una vez resueltos los conflictos, actualice sus paquetes para garantizar la estabilidad continua.

Mantener los paquetes actualizados

Actualizar las dependencias periódicamente reduce los riesgos de seguridad y garantiza la compatibilidad. A continuación, se explica cómo gestionar este proceso:

Dependencias de la pista

Utilice una tabla sencilla para supervisar las versiones de los paquetes, las fechas de actualización y su importancia:

PREMIUM	Versión actual	Última actualización	Requerido por
titiritero	24.4.0	Marzo 2024	Funcionalidad central
ws	8.17.1	Feb 2024	Soporte WebSocket
depurar	4.3.4	Enero 2024	Sistema de registro

Gestión de versiones

Al actualizar, utilice con cuidado los rangos de versiones semánticas. Para dependencias críticas, fije las versiones exactas para evitar cambios inesperados.

<span class="hljs-punctuation">{</span>
  <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
    <span class="hljs-attr">"puppeteer"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"24.4.0"</span><span class="hljs-punctuation">,</span>
    <span class="hljs-attr">"puppeteer-core"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"24.4.0"</span>
  <span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">}</span>

Solución de problemas de actualizaciones

Genere un informe de dependencia detallado con:

npm list --all > dependency-report.txt

Este informe ayuda a identificar conflictos y dependencias anidadas problemáticas.

Para entornos como Docker o GitLab CI, asegúrese de que su configuración incluya los paquetes de sistema necesarios:

<span class="hljs-keyword">RUN</span><span class="language-bash"> apt-get update && apt-get install -y \
    chromium \
    libnss3 \
    libgconf-2-4 \
    libxss1</span>

Configuraciones extra

Ajuste Puppeteer para configuraciones avanzadas con estas configuraciones adicionales.

Variables de entorno

Las variables de entorno le permiten ajustar el comportamiento de Puppeteer y anular las configuraciones predeterminadas.

A continuación se presentan algunas variables clave:

Variable	Proposito	Valor de ejemplo
DIRECCIÓN_DE_CACHÉ_DIR_TITIRISTA	Especifica un directorio de caché personalizado para las descargas del navegador	/usr/local/cache/titiritero
RUTA EJECUTABLE DEL TITULAR	Apunta a un ejecutable específico del navegador	/usr/bin/cromo
HTTP_PROXY	Configura los ajustes del proxy HTTP	http://proxy.company.com:8080
HTTPS_PROXY	Configura los ajustes del proxy HTTPS	https://proxy.company.com:8443
NO_PROXY	Enumera los dominios excluidos del uso de proxy	host local,127.0.0.1

Para instalaciones personalizadas de Chromium, defina la ruta ejecutable de la siguiente manera:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">executablePath</span>: process.<span class="hljs-property">env</span>.<span class="hljs-property">PUPPETEER_EXECUTABLE_PATH</span> || puppeteer.<span class="hljs-title function_">executablePath</span>()
});

Una vez configuradas las variables de entorno, puedes configurar servidores proxy para manejar las restricciones de red de manera efectiva.

Configuración de proxy

Para utilizar un servidor proxy con Puppeteer, aplique la siguiente configuración:

<span class="hljs-comment">// Launch Puppeteer with a proxy server and authentication</span>
<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--proxy-server=http://157.230.255.230:8118'</span>]
});

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">authenticate</span>({
  <span class="hljs-attr">username</span>: <span class="hljs-string">'proxyUser'</span>,
  <span class="hljs-attr">password</span>: <span class="hljs-string">'proxyPass'</span>
});

<span class="hljs-comment">// Optimize navigation with specific settings</span>
<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://example.com'</span>, {
  <span class="hljs-attr">waitUntil</span>: <span class="hljs-string">'networkidle2'</span>,
  <span class="hljs-attr">timeout</span>: <span class="hljs-number">30000</span>
});

Incluya el manejo de errores para garantizar un rendimiento sólido en producción:

<span class="hljs-keyword">try</span> {
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(url);
} <span class="hljs-keyword">catch</span> (error) {
  <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'Proxy connection failed:'</span>, error.<span class="hljs-property">message</span>);
  <span class="hljs-comment">// Add fallback logic or retry mechanism</span>
}

Para configuraciones corporativas, exporte la configuración de proxy en su terminal:

<span class="hljs-built_in">export</span> HTTP_PROXY=<span class="hljs-string">"http://proxy.company.com:8080"</span>
<span class="hljs-built_in">export</span> HTTPS_PROXY=<span class="hljs-string">"https://proxy.company.com:8443"</span>
<span class="hljs-built_in">export</span> NO_PROXY=<span class="hljs-string">"localhost,127.0.0.1,.company.internal"</span>

También puedes validar conexiones proxy mediante programación:

<span class="hljs-keyword">const</span> <span class="hljs-title function_">validateProxy</span> = <span class="hljs-keyword">async</span> (<span class="hljs-params">page</span>) => {
  <span class="hljs-keyword">try</span> {
    <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">'https://api.ipify.org?format=json'</span>);
    <span class="hljs-keyword">const</span> content = <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">content</span>();
    <span class="hljs-keyword">return</span> content.<span class="hljs-title function_">includes</span>(<span class="hljs-string">'ip'</span>);
  } <span class="hljs-keyword">catch</span> {
    <span class="hljs-keyword">return</span> <span class="hljs-literal">false</span>;
  }
};

Esto garantiza que su configuración de proxy funcione correctamente antes de continuar.

Próximos Pasos

Lista de verificación de configuración

Antes de empezar con la automatización de Puppeteer, asegúrese de que su entorno esté configurado correctamente. Utilice el siguiente script para validar su configuración:

<span class="hljs-comment">// Validation script for environment setup</span>
<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>();
<span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">validateEnvironment</span>();  <span class="hljs-comment">// Custom validation</span>
<span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();

Componente de configuración	Paso de verificación	Problema común
Node.js	Comprobar compatibilidad de versiones	Versión obsoleta de Node.js
Paquete.json	Verificar la entrada "type": "module"	Errores de importación de ES6
Instalación de Chrome	Prueba de lanzamiento del navegador	Falta el binario de Chromium
Configuraciones de memoria	Comprobar el tamaño de /dev/shm en Docker	El navegador se bloquea al iniciarse
Gestión de Recursos	Implementar browser.close()	Pérdidas de memoria

Una vez verificada su configuración, puede concentrarse en mejorar sus flujos de trabajo para obtener mejores resultados de automatización.

Consejos para empezar

CarriyoEl sistema PDF manejó eficientemente 10,000 etiquetas de envío diariamente, logrando una latencia p95 de 365 ms. [ 4 ]Para alcanzar niveles de rendimiento similares, considere estas estrategias:

Gestión de RecursosDesactive las funciones innecesarias para ahorrar recursos. Por ejemplo, inicie Puppeteer con la configuración optimizada:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">headless</span>: <span class="hljs-literal">true</span>,
  <span class="hljs-attr">args</span>: [<span class="hljs-string">'--disable-dev-shm-usage'</span>],
  <span class="hljs-attr">defaultViewport</span>: { <span class="hljs-attr">width</span>: <span class="hljs-number">1920</span>, <span class="hljs-attr">height</span>: <span class="hljs-number">1080</span> }
});

Gestión de errores :Utilice métodos de recuperación de errores robustos, como bloques try-catch y controladores de errores personalizados adaptados a problemas específicos.
Optimización de performance:Aumenta la velocidad mediante:
- Almacenamiento en caché de datos de uso frecuente
- Interceptar solicitudes de red
- Ejecución de tareas en paralelo
- Uso de Chrome DevTools para supervisar el rendimiento

Para una automatización más avanzada, explora la plataforma de flujo de trabajo low-code de Latenode. Ofrece precios basados en la ejecución y una gama de funciones para simplificar las implementaciones complejas de Puppeteer. [ 3 ].