脚手架启动失败（Vue CLI/Vite/Create React App）

小白阿龙2025-12-19 13:50

问题现象

执行 npm run serve（Vue CLI）/npm run dev（Vite/React）时抛出错误，典型报错：

Error: Cannot find module 'vue-cli-service'
Error: The engine "node" is incompatible with this module. Expected version ">=16.0.0". Got "14.17.0"
vite: error: Invalid options in vite.config.js: unknown option 'baseUrl'

深层原因

依赖损坏/缺失 ：node_modules 未正确安装或被意外删除。
版本不兼容：Node/NPM版本与框架要求不匹配（如Vite要求Node 14.18+/16+）。
配置语法错误 ：混淆不同脚手架的配置项（如Vite用base而非Vue CLI的baseUrl）。
缓存冲突：npm缓存的旧依赖与当前项目不兼容。

分步解决方案

步骤1：检查并升级Node/NPM版本（核心）

推荐用nvm（Node版本管理器） 管理多版本Node，避免全局版本冲突：

bash 复制代码

# 安装nvm（Mac/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装指定版本Node（如18.x，满足绝大多数框架要求）
nvm install 18

# 切换到该版本
nvm use 18

# 验证版本
node -v # 输出v18.x.x
npm -v # 输出8.x.x

Windows用户可使用 nvm-windows，操作逻辑一致。

步骤2：清理并重新安装依赖

bash 复制代码

# Mac/Linux：删除依赖和锁文件
rm -rf node_modules package-lock.json

# Windows：删除依赖和锁文件
rd /s /q node_modules && del package-lock.json

# 重新安装依赖（推荐用pnpm，速度更快）
npm install -g pnpm
pnpm install

步骤3：清理npm缓存

bash 复制代码

npm cache clean --force

步骤4：修正配置文件语法

以Vite为例，避免混淆Vue CLI的配置项：

js 复制代码

// vite.config.js 正确配置
export default {
  base: '/my-project/', // 替代Vue CLI的baseUrl（项目基础路径）
  server: { port: 3000 } // 端口配置
}

验证

重新执行 npm run dev，项目正常启动并在浏览器访问 localhost:3000 则解决。