部署后Docker环境中Puppeteer无法运行的问题排查

问题重现 #

在SvelteKit项目中使用Puppeteer将HTML转换为PDF，本地运行正常，但部署到Docker环境后触发以下错误：

Failed to launch the browser process!
rosetta error: failed to open elf at /lib64/ld-linux-x86-64.so.2

当前使用的Puppeteer转换函数：

async function generatePdfWithPuppeteer(htmlContent) {
    const browser = await puppeteer.launch({
        headless: true,
        executablePath: puppeteer.executablePath(),
        args: ['--no-sandbox', '--disable-setuid-sandbox']
    });

    const page = await browser.newPage();
    await page.setContent(htmlContent, { waitUntil: 'networkidle0' });

    const pdfBuffer = await page.pdf({
        format: 'A4',
        printBackground: true,
        margin: {
            top: '20mm',
            bottom: '20mm',
            left: '15mm',
            right: '15mm'
        }
    });

    await browser.close();
    return pdfBuffer;
}

错误原因 #

核心问题是架构不兼容：

• 使用的node:18-slim镜像默认是x86_64版本，但服务器为ARM64架构（如AWS Graviton、Apple M系列服务器）
• Rosetta转译层无法处理Puppeteer预下载的x86版本Chromium，导致找不到x86架构的动态链接库/lib64/ld-linux-x86-64.so.2
• 单独执行npm install puppeteer --arch=arm64的时机错误，先执行的npm install已安装默认架构依赖，后续单独安装会引发版本冲突

解决方案 #

1. 调整Puppeteer启动参数 #

更新启动配置，使用新版无头模式并补充Docker环境必要参数：

async function generatePdfWithPuppeteer(htmlContent) {
    const browser = await puppeteer.launch({
        headless: 'new', // 启用新版无头模式，兼容性更强
        executablePath: puppeteer.executablePath(),
        args: [
            '--no-sandbox',
            '--disable-setuid-sandbox',
            '--disable-dev-shm-usage', // 解决Docker共享内存不足问题
            '--disable-gpu',
            '--single-process'
        ]
    });

    // 后续代码保持不变
    const page = await browser.newPage();
    await page.setContent(htmlContent, { waitUntil: 'networkidle0' });

    const pdfBuffer = await page.pdf({
        format: 'A4',
        printBackground: true,
        margin: {
            top: '20mm',
            bottom: '20mm',
            left: '15mm',
            right: '15mm'
        }
    });

    await browser.close();
    return pdfBuffer;
}

2. 修正Dockerfile（关键） #

使用对应架构的基础镜像，安装系统版Chromium并补充必要依赖：

# 自动匹配服务器架构的Node.js镜像，或手动指定ARM64版本：node:18-slim-arm64v8
FROM node:18-slim

# 安装Chromium及ARM64环境必需的系统依赖
RUN apt-get update && apt-get install -y \
    chromium \
    wget \
    ca-certificates \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libgdk-pixbuf2.0-0 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils \
    libgbm1 \ # ARM64环境运行Chromium必需的库
    libdrm2 \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

# 环境变量指定使用系统安装的Chromium，避免Puppeteer下载架构不匹配的版本
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

WORKDIR /app

COPY package*.json ./

# 一次性安装所有依赖，确保Puppeteer与架构匹配
RUN npm install

COPY . .

EXPOSE 8000

RUN npm run build

CMD ["npm", "run", "preview"]

3. 额外注意事项 #

• 确保package.json中已包含puppeteer依赖，无需单独执行npm install puppeteer --arch=arm64
• 如果在ARM机器上构建x86架构的镜像，需使用Docker Buildx开启跨架构构建：

  docker buildx build --platform linux/amd64 -t your-image-name .
  

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