datawalkdev/frontendci

Node + Headless Chromium 依赖镜像

镜像概述

本镜像为Node.js应用提供预配置环境，集成了无头（Headless）Chromium运行所需的全部系统依赖。旨在解决Node.js应用中集成浏览器渲染、自动化测试等功能时的环境配置复杂性，减少开发者在依赖安装和兼容性调试上的时间成本。

核心功能与特性

• 完整Node.js环境：内置稳定版Node.js及npm/yarn包管理器，支持标准Node.js应用运行
• 无头Chromium依赖：预安装libnss3、libxss1、libasound2、libatk1.0-0等Chromium运行必需系统库
• 工具兼容性：无缝支持Puppeteer、Playwright等主流浏览器自动化工具，无需额外安装系统依赖
• 轻量级设计：基于Alpine或Debian Slim基础镜像构建，平衡功能完整性与镜像体积
• 即开即用：无需手动配置浏览器环境变量或权限设置，可直接运行依赖浏览器的Node.js脚本

使用场景

• 网页截图生成：通过Puppeteer/Playwright实现服务端网页截图，用于报告生成、社交媒体分享等场景
• 前端自动化测试：运行基于Jest、Mocha等框架的前端测试用例，支持浏览器环境下的DOM操作测试
• 网页内容爬取：抓取JavaScript动态渲染的网页内容，解决传统爬虫无法解析客户端渲染页面的问题
• 服务端渲染（SSR）：配合Next.js、Nuxt.js等框架，实现前端页面服务端预渲染，提升首屏加载速度
• 浏览器性能监控：模拟用户行为进行前端性能指标（如LCP、FID）采集与分析

使用方法与配置说明

基础使用（Docker Run）

运行本地Node.js脚本（需依赖浏览器功能）：

bash
docker run -it --rm \
  -v $(pwd):/app \
  -w /app \
  docker.xuanyuan.run/node-headless-chromium \
  node your-script.js

说明：-v $(pwd):/app 挂载当前目录至容器内/app路径，-w /app 设置工作目录为/app

Docker Compose配置示例

创建docker-compose.yml：

yaml
version: '3'
services:
  app:
    image: docker.xuanyuan.run/node-headless-chromium
    volumes:
      - ./src:/app/src
    environment:
      - NODE_ENV=production
      - CHROMIUM_FLAGS=--no-sandbox --disable-dev-shm-usage
    command: node src/index.js

启动服务：docker-compose up -d

关键配置参数

环境变量

常用Chromium启动参数

• --no-sandbox：禁用沙箱模式（容器环境必需）
• --disable-dev-shm-usage：避免共享内存限制导致浏览器崩溃
• --disable-gpu：禁用GPU加速（无头模式无需GPU）
• --window-size=1920,1080：设置默认窗口尺寸（影响截图分辨率）

典型应用示例（Puppeteer截图）

1. 创建Node.js项目并安装Puppeteer：

bash
mkdir chromium-demo && cd chromium-demo
npm init -y
npm install puppeteer

2. 编写截图脚本（screenshot.js）：

javascript
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    args: process.env.CHROMIUM_FLAGS.split(' '), // 使用环境变量中的启动参数
    headless: 'new' // 启用新无头模式
  });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'example.png', fullPage: true });
  await browser.close();
})();

3. 通过容器运行脚本：

bash
docker run -it --rm \
  -v $(pwd):/app \
  -w /app \
  -e CHROMIUM_FLAGS="--no-sandbox --disable-dev-shm-usage --window-size=1200,800" \
  docker.xuanyuan.run/node-headless-chromium \
  node screenshot.js

执行后，当前目录将生成example.png截图文件。