在Node Docker容器中运行vitest --ui时出现spawn xdg-open ENOENT错误

问题原因 #

Vitest的--ui模式默认会自动调用系统默认浏览器打开UI页面，但Docker容器通常是无桌面环境的极简系统，缺少xdg-open这个Linux桌面环境用来启动默认应用的工具，因此触发了找不到命令的错误。

解决方案 #

1. 禁用自动打开浏览器

修改你的npm脚本，添加--open false参数阻止Vitest尝试启动浏览器：

// package.json
{
  "scripts": {
    "test-ui": "vitest --ui --open false"
  }
}

或者直接在容器内执行命令：

npx vitest --ui --open false

执行后Vitest UI会正常启动，终端会输出UI的访问地址（比如http://localhost:51204/__vitest__/）。

2. 映射容器端口到主机

由于UI运行在容器内部，需要通过Docker端口映射让主机能访问：
启动容器时添加端口映射参数，把容器内的UI端口（示例为51204）映射到主机的同端口：

docker run -p 51204:51204 [你的容器镜像/容器名]

之后在主机浏览器中访问http://localhost:51204/__vitest__/即可打开Vitest UI。

3. （不推荐）安装桌面相关工具（仅临时测试用）

如果一定要在容器内启动浏览器，需要安装xdg-open及相关依赖，但这会大幅增加容器体积，不符合容器轻量化设计：

# Debian/Ubuntu系容器
apt-get update && apt-get install -y xdg-utils
# Alpine系容器
apk add --no-cache xdg-utils

即便安装完成，还需配置容器桌面显示转发，操作复杂，不建议用于常规开发场景。

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