WSL2中Puppeteer设headless=false启动有头浏览器报X显示错误排查

报错根本原因 #

• WSL2默认是无图形化界面的纯终端运行环境，所有需要可视化输出的程序都依赖X11图形显示服务完成窗口渲染。脚本启动有头Chrome时，会尝试读取系统DISPLAY环境变量定位图形渲染端点，没有对应服务和环境变量配置的情况下，就会直接抛出Unable to open X display错误。
• 之前追加的--no-sandbox、--disable-setuid-sandbox仅用于解决Linux环境下Chrome沙箱权限校验的问题，和图形显示服务的依赖没有关联，因此无法解决当前报错。
• 无头模式可以正常运行，是因为无头模式本身不需要依赖X11服务渲染可视化窗口，直接在内存中完成页面渲染并返回脚本结果，不调用系统图形组件。

分步修复方案 #

1. 准备X11图形显示通道 #

根据Windows版本选择对应配置：

• 如果是Windows 11、或是已手动开启WSLg功能的Windows 10版本：WSLg已经内置了X11服务，会自动将WSL内的程序窗口投射到Windows桌面，不需要额外安装第三方X服务器。直接在WSL终端执行echo $DISPLAY，能看到非空的输出值就说明通道已就绪。
• 如果是未开启WSLg的旧版Windows 10：需要先在Windows端安装轻量X服务器（如VcXsrv、Xming），启动时打开两个核心配置：关闭本地连接访问控制、禁用原生OpenGL渲染，避免后续Chrome窗口出现白屏、卡顿问题。

2. 配置WSL2的DISPLAY环境变量 #

在WSL终端打开你的shell配置文件（bash用户编辑~/.bashrc，zsh用户编辑~/.zshrc），在文件末尾追加一行配置：
export DISPLAY=$(ip route | grep default | awk '{print $2}'):0
执行source ~/.bashrc让配置立即生效。这行配置会自动识别Windows主机的IP地址，将WSL内程序的图形输出定向到Windows端的X服务端口。

注意：如果Windows开启了默认防火墙规则，需要为安装的X服务器添加入站连接放行规则，允许专用网络下的6000端口连接，否则会出现连接超时。

3. 验证图形通道连通性 #

在WSL终端执行sudo apt install x11-apps安装轻量测试程序，再执行xeyes命令。如果Windows桌面弹出可跟随鼠标移动的卡通眼睛窗口，就说明X11通道已经完全打通。

4. 调整Puppeteer启动参数 #

在原有参数基础上，追加两个适配WSL环境的配置，避免Chrome渲染崩溃：

• --disable-gpu：关闭WSL环境下兼容性较差的GPU硬件加速
• --display=:0：显式指定图形显示端口，避免环境变量读取异常

最终的启动示例代码如下：

await puppeteer.launch({
  headless: false,
  args: [
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-gpu',
    '--display=:0'
  ]
})

重新运行脚本后，Chrome可视化窗口就会正常弹出。

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