Docker容器内使用Puppeteer启动浏览器报错如何解决

问题对应两类根因，分开配置即可解决：

一、修复Puppeteer/Chromium容器内启动异常 #

容器默认精简镜像缺少Chromium运行依赖，且默认权限配置不满足Chromium沙箱要求，按以下配置调整：

• 编写Dockerfile时预装依赖，避免Puppeteer自带二进制兼容问题：

FROM node:20-bookworm-slim

# 安装Chromium及运行依赖
RUN apt-get update \
    && apt-get install -y --no-install-recommends \
    chromium \
    fonts-liberation libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 \
    libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc-s1 libglib2.0-0 \
    libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libu2f-udev libvulkan1 libx11-6 \
    libx11-xcb1 libxcb1 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# 指定Puppeteer使用系统预装的Chromium
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

• 调整Puppeteer启动参数，适配容器环境：

const browser = await puppeteer.launch({
  headless: "new",
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage', // 解决Docker默认/dev/shm分区过小导致的浏览器崩溃问题
    '--disable-gpu'
  ]
})

注意：--no-sandbox为容器环境必填参数，Chromium默认沙箱机制在容器权限模型下无法正常运行。

二、修复容器访问宿主机3000端口的网络问题 #

容器拥有独立网络命名空间，内部的localhost指向容器自身，而非宿主机，直接访问localhost:3000必然失败，按运行环境选择对应方案：

• Linux环境：
  1. 启动容器时添加--network="host"参数，直接复用宿主机网络栈，此时容器内可直接通过localhost:3000访问宿主机服务；
  2. 若不想使用host网络模式，可通过docker0网桥默认IP172.17.0.1访问，将代码中目标地址改为http://172.17.0.1:3000即可。
• Mac/Windows（Docker Desktop环境）：
  Docker内置了宿主机解析域名host.docker.internal，直接将代码中目标地址改为http://host.docker.internal:3000即可，无需额外修改网络配置。
• 跨系统兼容方案：
  启动容器时添加参数--add-host=host.docker.internal:host-gateway，即可在Linux/Mac/Windows环境下统一使用host.docker.internal访问宿主机，docker-compose配置中可在extra_hosts字段下添加对应规则。

三、验证步骤 #

1. 先进入运行中的容器，用curl测试目标地址连通性，确认网络通了再调试Puppeteer逻辑；
2. 容器内直接执行chromium --headless=new --no-sandbox https://example.com，确认浏览器本身可正常启动，再排查业务代码问题。

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