WSL Ubuntu环境Vaadin Maven项目运行npm install报错求助

这类Windows环境运行正常、WSL Ubuntu环境启动失败+npm install返回非零状态的Vaadin项目问题，90%以上由三类配置错误导致：

• 项目存放在WSL挂载的Windows NTFS分区（路径为/mnt/c/开头），WSL对NTFS分区的符号链接创建、文件权限管控存在天然缺陷，npm安装依赖时创建软链失败，直接触发后续Maven调用Vaadin前端构建流程全链路报错
• WSL环境未独立安装Linux版本的Node.js、npm，构建时错误调用了Windows盘符下的exe版本二进制，执行格式、路径转义规则不匹配
• IntelliJ关联WSL项目时，构建工具链配置错误，混用了Windows侧的Maven、Node程序，没有使用WSL内的原生Linux程序

1. 修正项目存放路径 #

禁止将需要在WSL内运行的项目放在/mnt/开头的Windows挂载目录，将整个项目文件夹复制到WSL用户主目录下，例如~/workspace/your-vaadin-project，复制完成后执行命令修正目录权限：

sudo chown -R $USER:$USER ~/workspace/your-vaadin-project
chmod -R 755 ~/workspace/your-vaadin-project

2. 安装WSL原生Node.js环境，彻底隔离Windows侧程序 #

先清理错误关联的Node安装：

sudo apt remove -y nodejs npm

通过nvm安装Node 20 LTS版本（Vaadin 23及以上版本兼容的长期支持版），安装完成后执行以下命令验证路径：

which node
which npm

验证标准：两个命令返回的路径必须是WSL本地用户目录下的路径，不能出现/mnt/c/开头的Windows盘符路径，否则说明仍在调用Windows侧程序，需要检查WSL的PATH环境变量，移除Windows侧Node、npm的路径配置。

3. 清理缓存重新构建 #

进入项目根目录，清理Windows环境生成的旧依赖、构建缓存，避免文件格式、权限冲突：

rm -rf node_modules package-lock.json target/flow-frontend ~/.npm/_cacache

先单独执行npm安装验证：

npm install

如果npm安装无报错，再执行Maven构建命令：

mvn clean package -DskipTests

如果npm安装出现网络超时错误，执行npm config set registry https://registry.npmmirror.com切换国内镜像源后重试即可。注意不要加sudo执行npm命令，否则会导致目录权限错乱。

4. 修正IntelliJ配置 #

打开IntelliJ的项目设置页，调整两处核心配置：

• 进入Build, Execution, Deployment > Build Tools > Maven页，将Maven运行时选择为WSL Ubuntu内安装的Maven路径，不要选择Windows本地安装的Maven
• 进入Languages & Frameworks > Node.js页，Node解释器选择WSL内nvm安装的Node 20路径，不要选择Windows本地安装的Node
  配置完成后重启IntelliJ，再启动项目即可正常运行。

• WSL环境下所有构建工具（Maven、Node、npm、JDK）必须全部使用WSL内安装的Linux原生版本，绝对不能混用Windows盘符下的exe版本
• 所有需要在WSL内构建运行的项目，必须存放在WSL的ext4文件系统目录下，不要放在NTFS格式的Windows挂载分区

内容的提问来源于stack exchange，提问作者obaidul kabir Rubayed