twilio/twilio-video-browsers

node+browser Docker镜像文档

1. 镜像概述和主要用途

本镜像集成Node.js运行环境与浏览器环境，旨在提供一站式解决方案，满足需要Node.js与浏览器协同工作的场景。通过将Node.js的脚本能力与浏览器的网页渲染/交互能力结合，可高效支持自动化测试、网页处理、爬虫等任务，避免本地环境配置差异导致的兼容性问题。

2. 核心功能和特性

• 双环境集成：包含Node.js运行时环境与主流浏览器（默认集成Chrome，具体版本可通过镜像标签指定），无需单独安装浏览器依赖。
• 自动化工具支持：内置浏览器驱动（如ChromeDriver），兼容Selenium、Puppeteer等自动化测试/控制工具，可直接调用浏览器API。
• 无头模式优化：默认支持浏览器无头模式（Headless），减少图形界面资源占用，适合服务器/容器化环境。
• 多版本标签：提供多版本Node.js（如16.x、18.x、20.x LTS）与浏览器版本组合，通过镜像标签（如18-chrome120）区分，满足不同项目依赖需求。

3. 使用场景和适用范围

典型场景

• 前端自动化测试：通过Node.js测试框架（Jest、Mocha）配合Selenium/Puppeteer，执行网页UI自动化测试（如元素定位、表单提交、兼容性验证）。
• 网页截图/PDF生成：利用Puppeteer等工具，通过Node.js脚本控制浏览器渲染网页并生成截图（PNG/JPG）或PDF文件（如报表、文档导出）。
• 动态网页爬虫：针对JavaScript渲染的动态网页（如SPA应用），通过Node.js脚本驱动浏览器执行页面交互（如滚动、点击）并提取数据。
• CI/CD流程集成：作为CI/CD流水线的执行环境，在构建阶段自动运行前端测试、生成网页预览文件，或在部署前验证页面渲染效果。

4. 使用方法和配置说明

4.1 docker run 命令示例

基础用法（执行Node.js脚本控制浏览器）

将本地Node.js脚本（如test.js）挂载到容器内，执行需要浏览器参与的任务：

bash
# 挂载当前目录到容器工作目录，执行脚本
docker run -it --rm \
  -v $(pwd):/usr/src/app \  # 挂载本地目录到容器内工作目录
  -w /usr/src/app \         # 设置容器工作目录
  -e HEADLESS=true \        # 启用无头模式（默认true，可选false）
  node+browser:18-chrome120 \  # 使用Node.js 18 + Chrome 120版本
  node test.js              # 执行本地脚本

端口映射（如需浏览器远程调试）

若需通过本地工具（如Chrome DevTools）调试容器内浏览器，可映射调试端口：

bash
docker run -it --rm \
  -v $(pwd):/usr/src/app \
  -p 9222:9222 \            # 映射浏览器远程调试端口（Chrome默认9222）
  node+browser:latest \
  node --inspect=0.0.0.0:9222 test.js  # 启动浏览器调试模式

4.2 docker-compose 配置示例

适用于多服务协同场景（如Node.js服务+浏览器任务），通过docker-compose.yml定义服务：

yaml
version: '3.8'
services:
  browser-worker:
    image: node+browser:20-chrome124  # Node.js 20 + Chrome 124
    volumes:
      - ./scripts:/usr/src/app        # 挂载本地脚本目录
      - ./output:/usr/src/app/output  # 挂载输出目录（如截图/PDF）
    working_dir: /usr/src/app
    environment:
      - NODE_ENV=production          # 设置Node.js环境变量
      - HEADLESS=true                # 无头模式启用
      - SCREEN_RESOLUTION=1920x1080  # 浏览器窗口分辨率（影响截图尺寸）
    command: node crawl.js           # 启动爬虫脚本
    restart: on-failure              # 任务失败时自动重试

5. 配置参数说明

5.1 环境变量

5.2 卷挂载点

6. 注意事项

• 镜像体积：因包含浏览器及依赖，镜像体积较大（基础版本约1.5GB，完整版本约2.5GB），建议通过私有仓库加速拉取。
• 资源需求：浏览器运行需足够内存（单实例建议分配≥1GB内存，复杂页面建议2GB+），可通过--memory参数限制容器资源。
• 权限控制：容器默认使用非root用户（node，UID 1000）运行，挂载本地目录时需确保权限匹配（可通过chmod 777临时测试，生产环境建议通过--user参数指定UID）。
• 版本兼容性：Node.js版本需与项目package.json的engines字段匹配，浏览器版本需与自动化工具（如Puppeteer要求Chrome版本≥对应API版本）兼容，建议通过镜像标签明确指定版本（如20-chrome124）。
• 中文支持：默认不包含中文字体，如需渲染中文，可选择带-fonts后缀的镜像标签（如20-chrome124-fonts），或自行挂载中文字体文件到/usr/share/fonts。