很多初学 Vite 搭建项目的同学，都会遇到一个经典报错：vite: command not found。明明跟着教程操作，终端却识别不到 vite 命令，大概率是未正确安装 Vite、安装方式错误、环境变量未生效导致的。
今天整理一套 100% 生效的解决方案，区分项目局部使用、全局使用两种场景，同时附上常见坑点排查，新手直接照搬即可解决。
一、报错核心原因
终端无法识别 vite 命令，根本问题只有一个：当前环境下没有安装 Vite，或安装后未生效。
常见误区：很多同学局部安装了 Vite，却直接在终端输入 vite 命令，自然会报错！
二、两种解决方案（优先推荐第一种）
方案一：项目局部安装（官方推荐、最稳妥）
局部安装仅对当前项目生效，不会污染全局环境，也是企业开发、项目协作的标准用法，适配所有前端项目。
步骤1：打开终端，进入你的项目根目录（必须是项目根目录，包含 package.json 文件）
步骤2：执行安装命令
# npm 用户
npm install -D vite
# yarn 用户
yarn add -D vite
# pnpm 用户
pnpm add -D vite步骤3：通过 npm 脚本启动项目（关键！不要直接输 vite）
安装完成后，打开项目 package.json，确认 scripts 配置（新建 Vite 项目默认自带）：
"scripts": {
"dev": "vite",
"build": "vite build"
}终端执行启动命令：
npm run dev即可正常启动 Vite 开发服务器，彻底解决报错。
方案二：全局安装（任意目录可直接使用 vite 命令）
如果需要在电脑任意目录，直接输入 vite、vite build 等命令，可选择全局安装，适合频繁新建 Vite 项目的场景。
# npm 用户
npm install -g vite
# yarn 用户
yarn global add vite
# pnpm 用户
pnpm add -g vite重要操作：安装完成后，必须关闭当前终端，重新打开，让环境变量生效，之后即可直接使用 vite 命令。
# 直接启动项目
vite
# 打包项目
vite build三、高频报错坑点排查（90% 新手都会踩）
1. 全局安装后依旧提示 command not found
大概率是 Node 全局包路径未加入系统环境变量：
- Windows：查看 npm 全局路径，添加到系统 PATH 环境变量
- Mac/Linux：执行
echo $PATH，检查 Node 全局目录是否在环境变量中
临时最优解决：放弃全局安装，使用局部安装 + npm run dev 方式，零环境变量问题。
2. Mac/Linux 安装出现权限报错
禁止使用 sudo 强制安装全局包，会导致权限混乱、后续依赖报错。优先使用项目局部安装方案，安全无隐患。
3. Node 版本过低导致安装失效
Vite 官方最低要求 Node.js 18+，如果你的 Node 版本过低，会出现安装成功但命令失效、隐性报错等问题。
查看版本：node -v，版本过低直接升级 LTS 稳定版本即可。
四、总结（快速记忆）
- 日常项目开发：优先局部安装 vite，用 npm run dev 启动，稳定无副作用；
- 频繁新建项目：选择全局安装，安装后重启终端；
- 报错排查优先检查：Node 版本、是否在项目根目录、是否重启终端；
- 尽量避免 sudo 安装全局依赖，规避权限问题。
后续遇到 Vite 启动、打包报错，都可以优先对照以上步骤排查，基本能解决 99% 的新手问题～
