npm create vite@latest创建React项目启动时提示找不到vite包报错

问题场景 #

执行以下步骤创建Vite React+TypeScript项目时启动失败：

1. 运行npm create vite@latest vite-react，选择React、TypeScript
2. 进入项目目录cd vite-react
3. 执行npm install
4. 运行npm run dev时抛出错误：

> vite-react@0.0.0 dev
> vite

failed to load config from [my-path]\vite-project\vite-react\vite.config.ts
error when starting dev server:
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'vite' imported from [my-path]\vite-project\vite-react\vite.config.ts.timestamp-1677228345613.mjs
    at new NodeError (node:internal/errors:399:5)
    at packageResolve (node:internal/modules/esm/resolve:889:9)
    at moduleResolve (node:internal/modules/esm/resolve:938:20)
    at defaultResolve (node:internal/modules/esm/resolve:1153:11)
    at nextResolve (node:internal/modules/esm/loader:163:28)
    at ESMLoader.resolve (node:internal/modules/esm/loader:838:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40)
    at link (node:internal/modules/esm/module_job:76:36)

环境信息 #

• Node.js: v18.14.2
• npm: 9.5.0
• Vite全局版本: vite/4.1.1 win32-x64 node-v18.14.2

已排查结论 #

• 无vite.config.ts的Vanilla+TypeScript项目可正常运行
• 含vite.config文件的Svelte+TypeScript、React+JavaScript项目均出现相同报错
• 家用机器可正常执行流程，工作笔记本无法重装系统

解决方案 #

1. 重装本地依赖 #

删除旧依赖文件后重新安装，避免缓存或安装不完整问题：

# 删除node_modules和锁文件
rm -rf node_modules package-lock.json
# 重新安装依赖
npm install

Windows环境执行：

Remove-Item -Recurse -Force node_modules, package-lock.json
npm install

2. 明确调用本地Vite #

修改package.json中的脚本，强制使用项目本地安装的Vite版本，避免全局与本地版本冲突：

{
  "scripts": {
    "dev": "./node_modules/.bin/vite",
    "build": "tsc && ./node_modules/.bin/vite build",
    "preview": "./node_modules/.bin/vite preview"
  }
}

Windows环境替换为：

{
  "scripts": {
    "dev": ".\\node_modules\\.bin\\vite",
    "build": "tsc && .\\node_modules\\.bin\\vite build",
    "preview": ".\\node_modules\\.bin\\vite preview"
  }
}

3. 清理npm缓存 #

清理npm缓存后重新安装依赖，解决缓存损坏导致的依赖加载问题：

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

4. 卸载全局Vite #

全局Vite版本可能与项目本地依赖版本存在兼容问题，卸载全局版本后仅使用本地依赖：

npm uninstall -g vite

之后直接运行npm run dev即可，npm会自动调用项目内的本地Vite。

5. 完善Vite配置文件类型声明 #

在vite.config.ts顶部添加类型声明，确保TS解析正确：

/// <reference types="vite" />
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
})

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