Puppeteer随机报错‘Missing X server or $DISPLAY’求助排查

可能的原因及解决办法 #

1. 子进程未继承$DISPLAY环境变量 #

Puppeteer启动Chromium时会创建独立子进程，如果你的应用通过进程管理工具（如pm2、systemd）启动，或者脚本未显式传递环境变量，子进程可能无法获取到$DISPLAY的值。

• 解决：在Puppeteer启动配置里强制传递环境变量：

  const browser = await puppeteer.launch({
    env: { ...process.env, DISPLAY: ':1' },
    // 其他配置参数
  });
  

  如果用pm2，启动时加上--env DISPLAY=:1，或者在ecosystem.config.js的env字段中配置该变量。

2. X11会话不稳定或端口失效 #

即使当前$DISPLAY设为:1，X服务器可能因超时、资源不足等原因断开对应会话，导致新浏览器进程无法连接。

• 解决：
  • 检查X服务器状态：执行ps aux | grep Xorg，确认:1对应的X进程是否在运行。
  • 改用xvfb虚拟显示服务器，避免依赖真实X会话：安装xvfb后，启动应用前执行xvfb-run -a -s "-screen 0 1920x1080x24" node your-app.js；或者在代码中配置无头模式+xvfb兼容参数：

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

3. X11访问权限丢失 #

运行Puppeteer的用户可能失去了X服务器的访问权限，比如xhost授权过期、用户切换后权限未同步。

• 解决：
  • 执行xhost +local:，允许本地用户访问X服务器（仅限测试或可信环境，注意安全风险）。
  • 如果用root用户运行，需传递XAUTHORITY变量：env XAUTHORITY=/home/your-user/.Xauthority DISPLAY=:1 node your-app.js。

4. 浏览器进程残留占用资源 #

之前崩溃的Chromium进程未彻底关闭，占用了X11连接资源，导致新进程无法创建连接。

• 解决：
  • 启动前清理残留进程：执行pkill -f chromium-browser || true。
  • 在代码中确保浏览器正常关闭：用try/catch包裹逻辑，在finally块调用browser.close()。

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