Windows环境下Vite构建加载vite.config.ts时出现spawn UNKNOWN错误

错误现象 #

构建Vite项目时，加载vite.config.ts文件环节失败，抛出spawn UNKNOWN错误。该问题仅在Windows环境出现，WSL（Oracle 9.8）及RHEL 8虚拟机中构建正常。

错误日志 #

[ERROR] error during build:
[ERROR] Error: spawn UNKNOWN
[ERROR]     at ChildProcess.spawn (node:internal/child_process:421:11)
[ERROR]     at Object.spawn (node:child_process:761:9)
[ERROR]     at ensureServiceIsRunning %PROJECT_DIR%\node_modules\vite\node_modules\esbuild\lib\main.js:1975:29)
[ERROR]     at build (%PROJECT_DIR%\node_modules\vite\node_modules\esbuild\lib\main.js:1873:26)
[ERROR]     at bundleConfigFile (file:///%PROJECT_DIR%/node_modules/vite/dist/node/chunks/dep-CDnG8rE7.js:66504:24)
[ERROR]     at loadConfigFromFile (file:///%PROJECT_DIR%/node_modules/vite/dist/node/chunks/dep-CDnG8rE7.js:66474:27)
[ERROR]     at resolveConfig (file:///%PROJECT_DIR%/node_modules/vite/dist/node/chunks/dep-CDnG8rE7.js:66083:30)
[ERROR]     at build (file:///%PROJECT_DIR%/node_modules/vite/dist/node/chunks/dep-CDnG8rE7.js:65180:24)
[ERROR]     at CAC.<anonymous> (file:///%PROJECT_DIR%/node_modules/vite/dist/node/cli.js:828:11)
[ERROR] -> [Help 1]

项目配置文件（vite.config.ts） #

import { UserConfigFn } from 'vite';
import { overrideVaadinConfig } from './vite.generated';

const customConfig: UserConfigFn = (env) => ({
// Here you can add custom Vite parameters
// https://vitejs.dev/config/
});

export default overrideVaadinConfig(customConfig)

环境信息 #

• 操作系统：Windows
• Vite版本：5.4.8
• Node.js版本：22.6.0

原因分析 #

spawn UNKNOWN错误本质是Windows下Node.js的child_process.spawn调用失败，常见诱因包括：

1. esbuild二进制文件问题：Vite依赖的esbuild二进制包在Windows下未正确安装、损坏，或版本与系统不兼容。
2. Node.js版本兼容性：Node.js 22为较新的非LTS版本，可能与Vite 5.4.8或其依赖的esbuild存在兼容性冲突。
3. 项目路径异常：项目目录路径包含空格、中文或特殊字符，导致spawn调用无法正确解析路径。
4. 权限或安全拦截：Windows系统权限不足，或杀毒软件/防火墙拦截了esbuild进程的创建。

排查解决方法 #

• 重新安装依赖并清理缓存
  删除node_modules文件夹和package-lock.json，执行以下命令重装依赖：

  npm install
  

  同时清理npm缓存：

  npm cache clean --force
  

• 指定兼容Windows的esbuild版本
  手动安装与Vite 5.4.8兼容的esbuild稳定版本：

  npm install esbuild@0.21.5 --save-dev
  

• 降级Node.js到LTS版本
  使用nvm管理Node.js版本，降级到20.x LTS版本（兼容性更稳定）：

  nvm install 20
  nvm use 20
  

• 检查并修改项目路径
  确保项目所在路径无空格、中文或特殊字符，例如将C:\My Projects\ViteApp改为C:\MyProjects\ViteApp。

• 临时关闭安全软件
  暂时关闭Windows Defender或第三方杀毒软件，排查是否是安全工具拦截了进程创建。

• 强制使用esbuild纯JS版本（临时方案）
  在vite.config.ts顶部添加以下代码，强制使用esbuild的JavaScript实现（会降低构建速度）：

  process.env.ESBUILD_BINARY_PATH = require.resolve('esbuild/lib/main.js');
  

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