Puppeteer无头模式运行正常 有头模式配合xvfb启动超时排查

该超时问题和启动超时时长配置无关，90%以上的触发原因是三类配置错误：

• xvfb启动后未将DISPLAY环境变量正确透传给Puppeteer拉起的Chrome子进程，Chrome启动后找不到可用显示服务直接挂起
• Chrome 112+版本有头模式在无物理GPU的虚拟化环境中默认强制开启GPU硬件加速，渲染进程初始化阶段直接卡死
• 此前长期使用的旧版无头模式（headless: true）本身和真实浏览器渲染逻辑存在显著差异，DOM统计、性能指标偏差属于已知问题，不需要强行追求有头模式也可拿到准确结果。

第一步：先补全环境依赖，验证xvfb基础可用性 #

不要直接在业务代码里调试，先在VM命令行执行以下操作确认基础环境正常：

1. 安装全量Chrome和xvfb依赖，缺任何一个都可能导致Chrome静默卡死

apt update && apt install -y xvfb x11-xkb-utils xfonts-100dpi xfonts-75dpi xfonts-scalable xfonts-cyrillic x11-apps libgbm1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libcups2 libdrm2 libgtk-3-0 libnss3 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libxshmfence1 google-chrome-stable

2. 手动启动xvfb服务，固定显示端口、关闭访问控制避免权限问题

Xvfb :99 -screen 0 1920x1080x24 -ac +extension GLX +render -noreset &
export DISPLAY=:99

3. 执行xclock命令验证X11显示服务正常，命令无报错、进程正常驻留则说明xvfb配置可用，杀掉xclock进程继续后续配置。

第二步：修正Puppeteer启动配置 #

核心注意点：不要使用Puppeteer自带的精简版Chrome，直接调用系统安装的全量稳定版Chrome；必须在启动浏览器前注入DISPLAY环境变量，浏览器启动后再设置环境变量无效。
直接使用以下配置替换原有启动逻辑，不需要设置几分钟的超长超时，配置正确的情况下30秒内即可完成启动：

const puppeteer = require('puppeteer');
// 提前注入显示端口环境变量
process.env.DISPLAY = ':99';

const browser = await puppeteer.launch({
  headless: false,
  executablePath: '/usr/bin/google-chrome-stable',
  timeout: 30000,
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
    '--disable-gpu', // 无物理GPU环境必填，禁用硬件加速避免渲染进程卡死
    '--disable-software-rasterizer',
    '--disable-extensions',
    '--window-size=1920,1080',
    '--no-first-run',
    '--no-default-browser-check',
    '--disable-features=Translate,BackForwardCache,InterestFeedContentSuggestions'
  ],
  defaultViewport: {
    width: 1920,
    height: 1080,
    deviceScaleFactor: 1
  }
});

第三步：替换xvfb集成逻辑 #

不要使用第三方npm封装的xvfb包，这类包普遍存在环境变量透传bug、进程生命周期管理异常问题，直接用Node原生child_process模块手动拉起xvfb稳定性最高：

const { spawn } = require('child_process');
// 脚本启动时先拉起xvfb进程
const xvfbProcess = spawn('Xvfb', [
  ':99',
  '-screen', '0', '1920x1080x24',
  '-ac',
  '+extension', 'GLX',
  '+render',
  '-noreset'
]);
// 等待1秒待xvfb完全启动后，再初始化Puppeteer
await new Promise(resolve => setTimeout(resolve, 1000));
process.env.DISPLAY = ':99';

// 此处放置Puppeteer初始化、登录鉴权、Lighthouse审计的业务逻辑

// 脚本退出时自动清理xvfb进程
process.on('exit', () => {
  xvfbProcess.kill('SIGTERM');
});

低维护成本备选方案 #

如果不想长期维护xvfb服务，可以直接切换到Chrome新版无头模式，不需要虚拟显示支持，Chrome 112+版本的新版无头模式已经完全对齐有头模式的渲染逻辑，Lighthouse审计的DOM节点数、性能指标和手动DevTools测试结果偏差小于2%，是目前CI环境跑性能审计的主流方案：

const browser = await puppeteer.launch({
  headless: 'new', // 启用新版无头模式
  executablePath: '/usr/bin/google-chrome-stable',
  // 其余启动参数和上述有头模式保持一致即可
});

• 优先使用root用户运行脚本，非root用户需要提前执行xhost +配置X11访问权限，否则会出现无权限访问显示服务的问题
• 如果是Docker环境部署，启动容器时需要添加--cap-add=SYS_ADMIN权限，否则Chrome沙箱机制会阻止进程启动
• Lighthouse启动审计前，等待浏览器完全初始化2秒再执行页面跳转，避免冷启动阶段的资源占用干扰审计结果
• 审计过程中不要打开额外的Chrome标签页，避免抢占CPU、内存资源导致性能数据失真

内容的提问来源于stack exchange，提问作者Jack Lorenzo Kurtz