Laravel Vite执行npm run build报qt.qpa.xcb连接display错误咨询

问题场景 #

在集成Vite的全新Laravel 10项目中，于Docker容器laravel.test内执行npm run build命令完全正常，但在Vagrant部署的Ubuntu 22.04环境中执行该命令时，出现以下错误：

$ npm run build

> build
> vite build

qt.qpa.xcb: could not connect to display :0.0
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, xcb.

Aborted (core dumped)

注：已通过./vendor/bin/sail artisan sail:publish导出laravel.test容器的Dockerfile，并将所有包同步安装到Vagrant环境中。

1. 什么是display？Vite为何需要它？ #

• display是X Window系统（Linux/Unix桌面环境的图形基础系统）中用于标识图形输出设备的标识符，:0.0一般指代本地的第一个显示器。
• Vite本身是纯命令行的构建工具，不需要图形环境。触发这个错误的原因是项目依赖的某个Node.js包（比如图片处理、UI渲染类插件）依赖Qt库，这类包在运行时会尝试调用X11图形系统；而你的Vagrant环境要么是无图形界面的服务器版系统，要么未正确配置X11转发，导致找不到可用的display设备。

2. Docker环境laravel.test与Vagrant Ubuntu 22.04环境的差异 #

• 图形环境配置：Laravel Sail的laravel.test容器默认会配置Qt使用offscreen无图形插件，或者容器内的Node.js依赖是针对无图形环境编译/安装的，不会主动触发图形系统调用；而Vagrant环境的依赖可能默认带有图形界面需求，系统也未配置Qt的无图形运行模式。
• 环境变量差异：Docker容器内大概率设置了QT_QPA_PLATFORM=offscreen这类环境变量，强制Qt在无图形模式下运行；而Vagrant环境缺少该变量，导致Qt默认尝试连接X11 display。
• 依赖安装细节：即便同步了Dockerfile的包列表，不同环境下的依赖安装仍可能存在差异——比如Docker容器使用Debian/Ubuntu的特定包版本，或者npm安装时的编译环境不同，导致Vagrant环境下的依赖引入了图形依赖，而Docker环境下是纯命令行版本。

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