Vite构建报错需建立“现象→原因→动作”映射：1.启动失败因预构建崩溃，删.vite/deps、vite --force或exclude问题包；2.模块找不到因alias路径未以/开头，检查vite.config.ts中resolve.alias配置；3.类型正常但运行报错因TS未识别vite/client环境，需在tsconfig.json的types中添加"vite/client"。
记Vite构建报错，核心不是死背，而是建立“现象→原因→动作”的快速映射。下面这三类高频报错，按实际发生频率和破坏性排序，每类都配了典型表现、一句话定位逻辑、以及可立即执行的操作。
1. 启动失败：Pre-bundling dependencies failed
这是Vite项目刚敲 npm run dev 就卡住的第一大拦路虎。
- 本质是依赖预构建崩了：Vite启动时会把 node_modules 里一堆第三方包（比如 vue、lodash-es）提前转成浏览器能直接 import 的格式，这步叫 pre-bundling。一旦某个包结构怪、用了不兼容语法、或路径有符号，就直接报这个错。
-
立刻试这三步：
- 删掉项目根目录下的 .vite/deps 文件夹（别手软，它就是缓存）
- 终端运行 vite --force 强制重做预构建
- 如果还崩，打开 vite.config.ts，在
optimizeDeps里加exclude: ['xxx']把疑似问题包踢出去（比如某些 Electron 原生模块）
2. 模块找不到：Alias not found 或 404 in browser console
写 import { api } from '@/api' 却提示路径不存在，或者浏览器 Network 标签里显示 /src/api/index.js 404。
-
根本不在代码写错，而在配置没对齐：VS Code 里能跳转、TS 不报错，不代表 Vite 运行时认得这个别名。它只认 vite.config.ts 里
resolve.alias的配置，而且路径必须以 / 开头（表示从项目根目录起算）。 -
验证+修复两步走：
- 终端执行 vite config --showConfig，搜
alias，确认输出里真有@: '/src'这样的映射 - 检查你的 alias 配置是否写成
'@': 'src'（缺了斜杠）或'@': './src'（用了相对路径）——这两种写法 Vite 都不认
- 终端执行 vite config --showConfig，搜
3. 类型正常但运行报错：TS 提示没问题，页面白屏或控制台报 Cannot find module
尤其常见于引入 .vue 组件、自定义类型声明、或用 defineComponent 写 setup 时。
- 八成是 TypeScript 和 Vite 的类型桥接断了：Vite 不直接跑 tsc，它靠自己的插件链处理 .ts/.vue，需要额外告诉 TS “vite/client” 这个环境类型存在。
-
补上这一行就稳了：
- 打开项目根目录的 tsconfig.json
- 确保
"compilerOptions"下有："types": ["vite/client", "vue"] - 如果用的是 Vue 3.3+ 的 defineModel 或 withDefaults，再加
"vue/macros"到 types 数组里
不用全记，先盯住这三类。遇到报错，先看终端第一行红字关键词，再对照上面找对应动作。跑通三次，肌肉记忆就建立了。
