Windows迁移至Ubuntu的Vite Vue项目无法运行问题排查

1. 核对package.json脚本配置 #

先打开项目根目录的package.json，检查scripts里的dev命令是否为直接调用vite：

"scripts": {
  "dev": "vite"
}

如果是这种配置，问题大概率出在本地依赖安装不完整或npm路径识别异常。

2. 验证本地依赖安装状态 #

运行以下命令查看node_modules下的可执行文件列表，确认是否存在vite：

ls node_modules/.bin

如果找不到vite，说明依赖安装过程有异常，重新执行npm install并仔细观察终端输出，重点排查：

• 网络超时或镜像源问题：可以临时切换npm源为淘宝镜像后重试

  npm config set registry https://registry.npmmirror.com/
  npm install
  

• 权限错误：不要用sudo npm install，而是配置npm全局目录到用户私有路径避免权限冲突：

  mkdir -p ~/.npm-global
  npm config set prefix '~/.npm-global'
  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
  source ~/.bashrc
  

  配置完成后重新安装依赖。

3. 尝试用npx直接调用本地Vite #

跳过npm脚本，直接执行：

npx vite

如果项目能正常启动，说明npm脚本调用时未正确识别本地依赖路径，可以把package.json里的dev命令修改为：

"scripts": {
  "dev": "npx vite"
}

4. 检查Node.js/npm版本兼容性 #

Vite要求Node.js版本至少为v14.18.0或v16.0.0以上，运行以下命令确认版本：

node -v
npm -v

如果版本过低，用nvm安装符合要求的Node.js版本：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 18
nvm use 18

切换版本后重新安装依赖。

5. 清理缓存后重装依赖 #

缓存损坏可能导致依赖安装不完整，执行以下命令彻底清理后重新安装：

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

6. 修复项目目录权限 #

Ubuntu下项目目录的权限可能限制了依赖安装，执行以下命令赋予当前用户完整权限：

sudo chown -R $USER:$USER /path/to/your/project

之后重新安装依赖并尝试启动项目。

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