Docker内运行Puppeteer报错缺失X server/$DISPLAY，如何连接本地显示？

配置文件与操作过程 #

Dockerfile #

FROM node:lts-bullseye-slim

RUN echo 'export PUPPETEER_SKIP_DOWNLOAD=true' > /etc/bash.bashrc

COPY . /project

WORKDIR /project

RUN apt update \
    && npm install --location=global npm -y \
    && npm install -g npm-check

RUN cd /project \
    && npm i

RUN apt-get update && \
    apt-get install gnupg wget -y && \
    wget --quiet --output-document=- https://dl-ssl.google.com/linux/linux_signing_key.pub | gpg --dearmor > /etc/apt/trusted.gpg.d/google-archive.gpg && \
    sh -c 'echo "deb [arch=amd64] https://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' && \
    apt-get update && \
    apt-get install google-chrome-stable -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

docker-compose.yml #

version: "3.9"
services: 
    accounts:
        image: holism/crawl
        container_name: crawl
        working_dir: /project
        ports: 
            - 3000:3000
        restart: always
        command: tail -f /dev/null
        volumes:
            - /project/package.json:/project/package.json
            - /project/app.js:/project/app.js

执行报错 #

通过docker exec -it crawl bash进入容器，执行node app.js时出现以下错误：

/project/node_modules/@puppeteer/browsers/lib/cjs/launch.js:262
                reject(new Error([
                       ^

Error: Failed to launch the browser process! undefined
[173:187:0927/084608.100277:ERROR:bus.cc(406)] Failed to connect to the bus: Failed to connect to socket /run/dbus/system_bus_socket: No such file or directory
[173:173:0927/084608.105774:ERROR:ozone_platform_x11.cc(240)] Missing X server or $DISPLAY
[173:173:0927/084608.105788:ERROR:env.cc(255)] The platform failed to initialize.  Exiting.


TROUBLESHOOTING: https://pptr.dev/troubleshooting

    at ChildProcess.onClose (/project/node_modules/@puppeteer/browsers/lib/cjs/launch.js:262:24)
    at ChildProcess.emit (node:events:529:35)
    at ChildProcess._handle.onexit (node:internal/child_process:292:12)

其他配置 #

package.json：

{
    "dependencies": {
        "puppeteer": "^19.7.3"
    }
}

Node.js版本：v18.18.0

解决方案 #

1. 本地X服务器授权（Linux/macOS） #

在本地终端执行命令，允许X服务器接受容器连接（仅测试环境使用，生产环境需限制权限）：

xhost +

2. 更新docker-compose.yml配置 #

添加X11转发相关的环境变量与卷挂载，传递本地显示设备信息给容器：

version: "3.9"
services: 
    accounts:
        image: holism/crawl
        container_name: crawl
        working_dir: /project
        ports: 
            - 3000:3000
        restart: always
        command: tail -f /dev/null
        volumes:
            - /project/package.json:/project/package.json
            - /project/app.js:/project/app.js
            # 挂载本地X11套接字
            - /tmp/.X11-unix:/tmp/.X11-unix
        environment:
            # 传递本地DISPLAY环境变量
            - DISPLAY=${DISPLAY}
            # 解决dbus连接错误
            - DBUS_SESSION_BUS_ADDRESS=unix:path=/run/dbus/system_bus_socket
        # 赋予容器访问设备的特权
        privileged: true

3. 调整Puppeteer启动参数 #

在app.js中启动Puppeteer时，添加必要的参数规避沙箱与权限问题：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/usr/bin/google-chrome-stable',
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage'
    ]
  });
  // 后续业务代码
})();

4. Windows环境适配 #

Windows系统需先安装VcXsrv这类X服务器软件，启动时勾选Disable access control，再在终端执行：

set DISPLAY=localhost:0.0

之后启动容器，docker-compose.yml中需映射对应X套接字路径（具体路径依VcXsrv配置而定）。

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