tilkal/node-chrome-headless

node-chrome-headless

镜像概述

node-chrome-headless 是一个基于 Debian 构建的 Docker 镜像，专为 Node.js 环境和无头 Chrome（Headless Chrome）运行而设计。该镜像主要用于前端自动化测试（如运行 Karma 测试）。需要特别注意的是，该镜像并未直接安装 Chrome 浏览器本体，而是预装了运行无头 Chrome 所需的所有系统级依赖库。

核心功能和特性

• 基于 Debian：提供稳定且兼容性强的 Linux 基础环境。
• Node.js 环境：内置 Node.js 运行时，支持执行 JavaScript 脚本和包管理命令。
• 无头 Chrome 依赖：预装运行 Headless Chrome 所需的全部系统依赖（如字体、X11 库、NSS 等），确保 Puppeteer、Playwright 或 Karma 等工具能顺利调用外部或自行下载的浏览器。
• 轻量化设计：不包含 Chrome 浏览器本体，有效减小镜像体积，用户可根据需求在构建时挂载或下载特定版本的浏览器。

使用场景和适用范围

• 前端自动化测试：在 CI/CD 流水线中运行 Karma、Jest、Mocha 等基于浏览器的单元测试或端到端测试。
• 网页抓取与自动化：结合 Puppeteer 或 Playwright 进行服务端渲染（SSR）、网页截图或数据抓取。
• 文档生成：利用无头浏览器将 HTML 页面转换为 PDF 或图片。

使用方法与部署示例

1. 作为基础镜像构建自定义镜像

由于镜像本身不包含 Chrome 本体，通常建议将其作为基础镜像，在 Dockerfile 中安装 Chromium 或让自动化工具（如 Puppeteer）自动下载。

dockerfile
FROM docker.xuanyuan.run/node-chrome-headless:latest

# 设置工作目录
WORKDIR /app

# 复制项目文件并安装依赖
COPY package*.json ./
RUN npm install

COPY . .

# 运行测试或启动应用
CMD ["npm", "test"]

2. 使用 Docker Run 运行测试

在本地或 CI 环境中直接运行当前目录下的前端测试：

bash
docker run --rm -v $(pwd):/app -w /app docker.xuanyuan.run/node-chrome-headless:latest npm run test

3. 使用 Docker Compose 配置

以下是一个用于前端测试环境的 docker-compose.yml 示例：

yaml
version: '3.8'

services:
  frontend-test:
    image: docker.xuanyuan.run/node-chrome-headless:latest
    volumes:
      - .:/app
    working_dir: /app
    command: npm run test
    shm_size: '1gb' # 增加共享内存大小，防止 Chrome 崩溃
    environment:
      - NODE_ENV=test

配置与运行注意事项

1. 浏览器安装：由于镜像仅提供依赖，您需要在项目的 Dockerfile 中通过 apt-get 安装 chromium，或者依赖 Puppeteer/Playwright 在 npm install 时自动下载浏览器可执行文件。
2. 沙盒问题（Sandboxing）：在 Docker 容器中运行 Chrome 时，通常会遇到沙盒权限问题。建议在启动浏览器时添加 --no-sandbox 和 --disable-setuid-sandbox 参数。
3. 共享内存（/dev/shm）：Chrome 在默认情况下可能会因为 Docker 默认的 /dev/shm 大小（64MB）过小而崩溃。建议在运行容器时添加 --shm-size="1g" 参数（如上述 docker-compose 示例），或在启动 Chrome 时使用 --disable-dev-shm-usage 参数。