本文详解在 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” 的根本原因与完整解决方案。
在 Ubuntu 22.04（Node.js v20.5）等现代 Linux 环境中，通过 npm create vite@latest my-app 创建 Vite 项目时，Vite CLI 工具本身并不会自动安装为全局可执行命令——它仅作为开发依赖写入新项目的 package.json 中。而 npm run dev 脚本默认调用的是全局 vite 命令（而非 npx vite 或 node_modules/.bin/vite），因此当系统找不到全局 vite 二进制时，就会抛出 sh: 1: vite: not found 错误。
⚠️ 注意：这不是 node_modules 损坏、Node 版本不兼容或权限问题，而是 命令作用域理解偏差 导致的典型误区。
✅ 正确操作流程（推荐两种方式）
方式一：全局安装 Vite（适合初学者 & 多项目开发）
# 1. 全局安装 vite CLI（需一次，后续所有 vite 项目均可复用） npm install -g vite # 2. 创建 React 项目（自动选择 React 模板） npm create vite@latest filemanager -- --template react # 3. 进入项目并安装依赖 cd filemanager npm install # 4. 启动开发服务器（此时 vite 命令已全局可用） npm run dev
✅ 优势：命令简洁，npm run dev 直接生效；适合频繁创建 Vite 项目的用户。
⚠️ 注意：确保你有 npm 全局 bin 目录写入权限（如使用 sudo 安装请谨慎；推荐配置 npm prefix 或使用 Corepack 替代）。
方式二：不依赖全局安装（更安全、更符合现代实践）
# 1. 直接创建项目（无需提前全局安装 vite） npm create vite@latest filemanager -- --template react # 2. 进入目录并安装依赖 cd filemanager npm install # 3. 使用 npx 运行本地 vite（推荐！避免全局污染） npx vite # 或直接运行预定义脚本（vite 已作为 devDependency 写入 package.json） npm run dev
✅ 优势：零全局依赖，项目隔离性强，符合“依赖即服务”原则；npm run dev 实际调用的是 node_modules/.bin/vite，完全无需全局 vite。
? 提示：若 npm run dev 仍报错，请检查 package.json 中 "scripts": { "dev": "vite" } 是否存在——Vite 官方模板默认已包含，无需手动添加。
? 排查补充建议
- 验证全局 vite 是否可用：运行 which vite 或 vite --version；
- 检查 npm 全局 bin 路径是否在 $PATH 中：echo $PATH | grep "$(npm config get prefix)/bin"；
- 若使用 nvm，确保当前 Node 版本下执行了 npm install -g（不同 Node 版本的全局模块彼此隔离）；
- 不要删除 package-lock.json 后仅执行 npm install —— 它本身不修复命令缺失问题，仅还原依赖树。
✅ 总结
根本原因在于混淆了「项目构建工具」与「全局 CLI 入口」的关系。Vite 是一个双模式工具：既可通过 npx 或本地 node_modules/.bin 调用（推荐），也可通过 -g 全局安装后直接调用。对新手而言，优先采用方式二（npx vite 或 npm run dev）即可开箱即用，无需额外全局安装；若坚持方式一，请务必确认全局 vite 已正确注册到系统 PATH。
现在，你的 React + Vite 应用将顺利启动在 http://localhost:5173 —— 开发之旅，正式开始。
