node:lts-alpine镜像构建Puppeteer应用出现启动报错问题

报错根因 #

• 出现的 ENOENT 错误是因为 node:lts-alpine 作为精简镜像使用 musl libc 作为标准库，而 Puppeteer 默认下载的内置 Chromium 是为 glibc 环境编译的，二者不兼容。同时 alpine 默认缺失 Chromium 运行所需的系统依赖库，导致可执行文件无法被正常调用。

修复步骤 #

1. 修改 Dockerfile 配置 #

需要在镜像构建阶段安装 alpine 官方源编译的适配 musl 环境的 Chromium，同时配置环境变量告知 Puppeteer 跳过内置 Chromium 下载，使用系统安装的 Chromium：

FROM node:lts-alpine
ENV NODE_ENV=production
# Puppeteer 相关环境配置
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

WORKDIR /usr/src/app

# 安装 Chromium 及运行依赖
RUN apk add --no-cache \
      chromium \
      nss \
      freetype \
      harfbuzz \
      ca-certificates \
      ttf-freefont

COPY ["package.json", "package-lock.json*", "npm-shrinkwrap.json*", "./"]
RUN npm install --production --silent && mv node_modules ../
COPY . .
RUN chown -R node /usr/src/app
USER node
CMD ["npm", "start"]

2. 调整 Puppeteer 启动参数 #

在代码中调用 puppeteer.launch 的位置，增加适配容器环境的启动参数：

const browser = await puppeteer.launch({
  // 非必须，配置了PUPPETEER_EXECUTABLE_PATH环境变量可以省略该配置
  executablePath: '/usr/bin/chromium-browser',
  args: [
    // 容器环境无法使用沙箱，必须添加
    '--no-sandbox',
    '--disable-setuid-sandbox',
    // 避免容器共享内存不足导致Chromium崩溃
    '--disable-dev-shm-usage'
  ]
})

注意事项 #

• 如果出现 Puppeteer 与 Chromium 版本不兼容的问题，可以先确认你使用的 Puppeteer 版本对应的兼容 Chromium 大版本，选择对应版本的 alpine 镜像即可。
• 生产环境不要删除 --no-sandbox 相关参数，容器内默认不支持 Chromium 沙箱能力。

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