Vite构建报错多因路径、模块、环境、配置四类问题，覆盖90%以上场景：路径错误需检查alias与tsconfig同步；模块失败常因预构建卡住，可强制重构建或排除冲突包；环境错误源于上下文不匹配，如局域网访问需设host为'0.0.0.0'；配置错误则多由特殊字符路径或ESM/CJS混用引发。
Vite 构建报错大多有明确诱因，不是玄学问题。关键在于分清是开发环境（vite dev）还是构建阶段（vite build）出错，再按模块定位——路径、模块、环境、配置四类问题覆盖了 90% 以上场景。
路径相关报错：404、找不到模块、别名失效
这类错误最常见，表现如 Cannot find module '@/utils' 或浏览器控制台资源 404。
- 检查
vite.config.ts中resolve.alias是否用path.resolve(__dirname, 'src')写成绝对路径，不能写相对路径或字符串拼接 - TypeScript 项目必须同步更新
tsconfig.json的compilerOptions.paths和baseUrl，否则编辑器和类型检查会报错，但运行可能正常 - 静态资源（图片、字体）放在
public/目录下，引用时用绝对路径/images/logo.png；若从src/引入，需用import url from '@/assets/logo.png'，让 Vite 自动处理路径 - 部署到子路径（如
/admin/）时，务必在配置中加base: '/admin/'，否则打包后所有资源请求仍从根目录发起
模块解析失败：Pre-bundling dependencies failed、buffer/process is not defined
本质是 Vite 预构建（optimizeDeps）阶段卡住，多见于含 CJS、Node.js API 或二进制依赖的包。
- 删除
.vite/deps目录，再运行vite --force强制重做预构建 - 在
optimizeDeps.exclude中排除冲突包（如regedit、registry-js），改用动态导入或条件判断隔离 Node 环境逻辑 -
buffer is not defined类错误，说明代码里用了 Node 全局变量，但没注入 polyfill。可在define中手动挂载：define: { global: 'globalThis' }，或用插件如vite-plugin-node-polyfills
环境与运行时错误：局域网访问空白、Electron 中 nativeModule.xxx 报错
不是代码写错，而是上下文环境不匹配导致的“看起来像 bug”的行为。
- 局域网访问空白，先确认
server.host设为'0.0.0.0'，再检查防火墙或杀毒软件是否拦截了端口 - Electron + Vite 场景下，原生模块（如
.node文件）不会被自动打包，需通过external排除，并确保require('xxx')在主进程执行，而非渲染进程 - 遇到
nativeModule.enumKeys is not a function这类错误，大概率是模块导出结构被 Vite 处理变形（例如全量对象被挂到default上），应改用解构导入：const { enumKeys } = require('registry-js')，避免链式访问
配置与语法错误：No loader configured for ".html"、CJS/ESM 混用警告
这类错误往往和项目路径或工程配置强相关，表面离谱，根源简单。
- 报
No loader configured for ".html" files？先看项目路径里有没有#、&、空格等特殊字符，Windows 下尤其敏感。把项目移到纯英文无符号路径（如D:/project/myapp）就能解决 - Vite 5+ 默认只支持 ESM 配置文件。若用
vite.config.js，需在package.json加"type": "module"，或直接改用vite.config.mjs；否则会提示CJS Node API deprecated - PostCSS 配置暂不支持
.mts，如果用了 TypeScript 写 PostCSS 配置，得重命名为postcss.config.cjs或.cts
