本文详解在 ubuntu 系统下通过 npm create vite@latest 初始化 react 项目后，因 vite 命令未全局安装导致 npm run dev 报错 “vite: not found” 的根本原因与完整解决方案。
本文详解在 ubuntu 系统下通过 npm create vite@latest 初始化 react 项目后，因 vite 命令未全局安装导致 npm run dev 报错 “vite: not found” 的根本原因与完整解决方案。
在使用 Vite 快速搭建 React 项目时，一个常见误区是认为执行 npm create vite@latest my-app 后即可直接运行开发服务器。但实际上，Vite 的 CLI 工具（即 vite 命令）需作为可执行命令被系统识别——而 create-vite 脚手架本身不自动安装全局 vite，它仅负责生成项目骨架。当你运行 npm run dev 时，脚本会调用 vite 命令（见 package.json 中 "dev": "vite"），若该命令未在 $PATH 中注册，就会出现 sh: 1: vite: not found 错误，尤其在 Ubuntu 等 Linux 发行版中更为典型。
✅ 正确流程如下（推荐使用 全局安装 + 本地初始化 组合）：
-
全局安装 Vite CLI（确保 vite 命令可用）：
npm install -g vite
✅ 验证是否成功：终端输入 vite --version，应输出类似 v5.4.0 的版本号。
-
创建新项目（推荐显式指定框架和模板，避免交互式提示）：
npm create vite@latest filemanager -- --template react
? --template react 参数明确指定 React 模板，跳过交互选择；-- 用于分隔 npm 命令参数与 create-vite 的内部选项。
-
进入项目并安装依赖：
cd filemanager npm install
⚠️ 注意：npm install 安装的是项目本地依赖（含 vite 作为 devDependencies），但 npm run dev 仍优先使用全局 vite（或通过 npx vite 调用本地版本）。二者均可工作，但全局安装能确保命令始终可用。
-
启动开发服务器：
npm run dev
此时将正常输出：
✓ Starting Vite server in development mode... ➜ Local: http://localhost:5173/ ➜ Network: http://192.168.x.x:5173/
? 补充说明：
为什么 npm install 后仍报错？
因为 npm install 仅将 vite 安装到 node_modules/.bin/ 目录，而 npm run 脚本默认会优先查找 node_modules/.bin 下的可执行文件——理论上不应失败。若仍报错，常见原因包括：
• package.json 中 scripts.dev 被意外修改（如写成 "dev": "vite" 但实际应为 "vite"）；
• Shell 缓存了旧的 PATH（可执行 hash -d vite 清除或重启终端）；
• 使用了 sudo npm install 导致权限混乱（Ubuntu 下应避免 sudo npm）。-
更安全的替代方案（无需全局安装）：
若你倾向避免全局安装，可直接用 npx 运行本地 vite：npx vite
或修改 package.json 中的脚本为：
"scripts": { "dev": "npx vite" }但对新手而言，全局安装 vite 更直观、容错性更高。
? 总结：Vite 的核心设计是「CLI 分离」——create-vite 负责初始化，vite 负责运行。两者缺一不可。在 Ubuntu + Node.js 20.5 环境下，请务必先执行 npm install -g vite，再创建项目，即可彻底解决 vite: not found 问题，顺利开启 React 开发之旅。
