Docker中Puppeteer+Codeceptjs测试报错：找不到浏览器版本756035

API 探路者

2026-5-11

解决Docker中Codeceptjs+Puppeteer的浏览器版本匹配问题

问题根源

你遇到的错误核心是Puppeteer版本与Docker内安装的Chrome Stable版本不匹配。Puppeteer的每个版本都绑定了特定的Chromium修订版本（这里是756035），你虽然通过apt安装了Chrome Stable，但Puppeteer默认会优先寻找它绑定的那个特定Chromium版本；再加上你设置PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true跳过了绑定版本的下载，自然就出现了找不到文件的报错。另外，即使安装了系统Chrome，你也没明确告诉Puppeteer去使用它，这也是问题之一。

修复步骤

1. 调整Dockerfile的环境变量与依赖安装顺序

你的PUPPETEER_SKIP_CHROMIUM_DOWNLOAD环境变量放在了安装Puppeteer之后，这会导致安装时仍会尝试下载Chromium。同时，Docker容器运行Chrome还需要一些额外的系统依赖库，我已经帮你补充进去了：

# Use whatever version you are running locally (see node -v)
FROM node:12.18
WORKDIR /app

# 先设置环境变量，提前告知Puppeteer跳过Chromium下载
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true

# 安装系统依赖、Chrome Stable及工具脚本
RUN apt-get update \
 && apt-get install -y wget gnupg ca-certificates libxss1 libnss3 libasound2 libatk-bridge2.0-0 libgtk-3-0 \
 && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
 && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \
 && apt-get update \
 && apt-get install -y google-chrome-stable \
 && rm -rf /var/lib/apt/lists/* \
 && wget --quiet https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh -O /usr/sbin/wait-for-it.sh \
 && chmod +x /usr/sbin/wait-for-it.sh

# 安装项目基础依赖
COPY package.json package-lock.json ./
RUN npm install

# 安装Codeceptjs和Puppeteer（此时会遵守跳过Chromium下载的设置）
RUN npm install codeceptjs puppeteer

COPY . /app

# 执行测试用例
RUN npx codeceptjs run

2. 修改Codeceptjs配置，指定系统Chrome路径

在你的codecept.conf.js（或codecept.json）中，给Puppeteer配置项添加executablePath和Docker运行必需的启动参数：

exports.config = {
  // 其他原有配置...
  helpers: {
    Puppeteer: {
      url: "你的测试目标URL",
      show: false,
      executablePath: '/usr/bin/google-chrome-stable', // 关键：指定系统安装的Chrome路径
      args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'] // Docker无沙箱环境的必需参数
    }
  },
  // 其他原有配置...
};

这些启动参数是为了让Chrome在Docker的受限环境中正常运行，避免权限和资源不足的问题。

3. 可选：锁定Puppeteer版本匹配Chrome版本

如果你更倾向于让Puppeteer绑定的Chromium版本和系统Chrome完全一致，可以先查清楚安装的Chrome Stable版本，再安装对应版本的Puppeteer。比如Chrome 84对应Puppeteer 5.3.0，你可以在package.json中明确指定：

{
  "dependencies": {
    "codeceptjs": "^2.6.0",
    "puppeteer": "5.3.0"
  }
}

这种方式需要你手动维护版本对应关系，不如直接使用系统Chrome灵活，但能避免版本兼容问题。

验证修复

重新构建镜像并运行容器即可：

docker build -t codecept-puppeteer-test .
docker run codecept-puppeteer-test

此时Puppeteer会调用你安装的Chrome Stable，不会再出现找不到指定浏览器修订版本的报错。

内容的提问来源于stack exchange，提问作者Jananath Banuka