在Docker node:20-alpine中使用Puppeteer启动失败的求助

近期在Docker中使用Puppeteer时，遭遇浏览器进程启动失败错误，提示找不到指定路径的Chrome。尝试更换为node:20-slim镜像并添加额外依赖包后，问题仍未解决。

错误日志 #

Error: Failed to launch the browser process! spawn /usr/src/apigateway/.cache/puppeteer/chrome/linux-121.0.6167.85/chrome-linux64/chrome ENOENT


TROUBLESHOOTING: https://pptr.dev/troubleshooting

    at ChildProcess.onClose (/usr/src/apigateway/node_modules/@puppeteer/browsers/lib/cjs/launch.js:267:24)
    at ChildProcess.emit (node:events:518:28)
    at ChildProcess._handle.onexit (node:internal/child_process:292:12)
    at onErrorNT (node:internal/child_process:484:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)

原Dockerfile #

FROM node:20-alpine

RUN apk add --no-cache \
    udev \
    ttf-freefont \
    chromium \
    nss \
    freetype \
    freetype-dev \
    harfbuzz \
    ca-certificates \
    fontconfig \
    curl

# Create app directory
RUN mkdir -p /usr/src/apigateway
WORKDIR /usr/src/apigateway

# Bundle app source
COPY . /usr/src/apigateway

# Install app dependencies
RUN npm install

EXPOSE 1337
CMD [ "node", "server.js"]

核心问题分析 #

错误根源是Alpine镜像环境与Puppeteer默认下载的Chrome二进制文件不兼容，且你已通过apk安装了系统版Chromium，但未配置Puppeteer优先使用该版本。

具体修复步骤 #

1. 修改Dockerfile，指定使用系统Chromium #

在npm install前添加环境变量，跳过Puppeteer自带Chrome的下载，并指定系统Chromium的路径。同时移除不需要的freetype-dev依赖精简镜像：

FROM node:20-alpine

RUN apk add --no-cache \
    udev \
    ttf-freefont \
    chromium \
    nss \
    freetype \
    harfbuzz \
    ca-certificates \
    fontconfig \
    curl

# 配置Puppeteer使用系统安装的Chromium
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

# Create app directory
RUN mkdir -p /usr/src/apigateway
WORKDIR /usr/src/apigateway

# Bundle app source
COPY . /usr/src/apigateway

# Install app dependencies
RUN npm install

EXPOSE 1337
CMD [ "node", "server.js"]

2. 调整Puppeteer启动代码参数 #

Docker环境下必须禁用沙箱模式，同时添加适配Alpine的参数，避免启动失败：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage', // 解决Alpine共享内存不足问题
      '--disable-gpu' // 无GPU环境下禁用GPU加速
    ]
  });
  // 后续业务代码
})();

3. 重新构建并运行容器 #

执行以下命令重新构建镜像并启动容器：

docker build -t puppeteer-app .
docker run -p 1337:1337 puppeteer-app

内容的提问来源于stack exchange，提问作者Jaswanth M