WSL Ubuntu下Puppeteer启动有界面浏览器报$DISPLAY缺失错误求助

• 设备环境：两台运行WSL Ubuntu的电脑（台式机+笔记本）
• 技术版本：Node.js v19.1.0、npm v9.3.1、Puppeteer（含puppeteer-extra）
• 异常现象：台式机可正常运行带界面的Chromium执行代码；笔记本无头模式运行正常，但有界面模式启动报错，执行echo $DISPLAY输出为空
• 终端报错信息：

Error: Failed to launch the browser process!
[16533:16533:0130/140329.896545:ERROR:ozone_platform_x11.cc(238)] Missing X server or $DISPLAY
[16533:16533:0130/140329.896887:ERROR:env.cc(255)] The platform failed to initialize. Exiting.

• 测试代码：

const { executablePath } = require('puppeteer');
const puppeteer = require('puppeteer-extra')

const url = "https://www.google.com/"

async function createPage() {
    const browser = await puppeteer.launch({headless: false, executablePath: executablePath(), args: ['--disable-web-security', '--disable-features=IsolateOrigins,site-per-process']});
    const page = await browser.newPage();
    return page;
}

async function openPage(page) {
    await page.goto(url);
}

async function screenshot_photo(page) {
    await page.screenshot({path: 'screenshot.jpg'});
    await page.close()
}

async function testing() {
    var page = await createPage();
    await openPage(page);
    await screenshot_photo(page);
}

testing();

一、修复$DISPLAY环境变量（核心问题） #

WSL本身无图形界面，需依赖Windows端X服务器实现GUI转发，步骤如下：

1. 安装Windows端X服务器
   下载安装VcXsrv（或X410），启动时选择Multiple windows，Display number设为0，取消勾选Native opengl，勾选Disable access control（临时测试用，后续可配置权限）。
2. 临时配置DISPLAY变量
   在WSL终端执行：

   export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0.0
   

   执行echo $DISPLAY验证，输出应为192.168.x.x:0.0格式。
3. 永久配置DISPLAY
   编辑~/.bashrc（或~/.zshrc，根据使用的shell），添加上述export命令，保存后执行source ~/.bashrc，重启终端后自动生效。

二、重新部署Puppeteer（清理残留环境） #

若之前安装存在残留，按以下步骤彻底重装：

1. 清理旧依赖

   npm uninstall puppeteer puppeteer-extra
   rm -rf node_modules package-lock.json
   

2. 重新安装依赖

   npm install puppeteer
   npm install puppeteer-extra
   

3. 验证Chromium可用性
   在WSL终端执行：

   $(npx puppeteer browsers path chromium)
   

   若能弹出Chromium窗口，说明环境配置正常。

三、代码优化（可选） #

无需手动指定executablePath，Puppeteer会自动找到内置Chromium，同时添加WSL适配参数：

const browser = await puppeteer.launch({
  headless: false,
  args: [
    '--disable-web-security',
    '--disable-features=IsolateOrigins,site-per-process',
    '--no-sandbox',
    '--disable-setuid-sandbox'
  ]
});

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