Vite依赖预构建失败通常表现为启动报错、控制台提示Failed to resolve entry或卡在preparing deps...，应先运行vite --debug暴露esbuild错误堆栈，再逐项排查问题包的ESM/CJS兼容性、optimizeDeps.exclude配置、package.json exports字段、.vite缓存及pnpm硬链接干扰。
Vite 依赖预构建（Dependency Pre-Bundling）失败时，通常表现为启动报错、控制台出现 Failed to resolve entry for package 或 Cannot find module 类似提示，也可能卡在 preparing deps... 阶段。排查核心在于定位具体哪个包出问题、为什么出问题，以及如何绕过或修复。
查看详细错误日志和构建上下文
Vite 默认会隐藏部分底层错误细节。启用调试模式可暴露真实原因：
- 运行
vite --debug或vite dev --debug，它会打印 esbuild 的原始错误堆栈 - 关注输出中紧邻
[vite] dependency pre-bundling后的报错行，尤其是error during build:或failed to load url后面的内容 - 检查是否提示
Unexpected token（ESM/CJS 混用）、Missing export（命名导出不兼容）、Invalid package.json "exports"（exports 字段配置异常）等
确认问题依赖是否被正确识别为 ESM 或需跳过预构建
Vite 对 CommonJS 包自动做转换，但某些包（如含动态 require()、__dirname、Node.js 内置模块引用）无法安全转成 ESM，导致预构建失败：
- 在
vite.config.ts中临时添加optimizeDeps.exclude排除可疑包，例如：optimizeDeps: { exclude: ['some-cjs-only-package'] } - 若排除后能启动，说明该包确实不兼容预构建；后续可考虑用
dynamic import()懒加载，或找 ESM 替代方案 - 检查包的
package.json是否有"type": "module"或合规的"exports"字段；缺失或错误会导致 Vite 误判模块类型
检查 node_modules 状态与缓存干扰
损坏的依赖或旧缓存常引发看似随机的预构建失败：
立即学习“Java免费学习笔记（深入）”；
- 删除
node_modules/.vite目录（Vite 的依赖缓存），再重启服务 - 执行
npm install或yarn install重装依赖，避免软链接/损坏文件影响解析 - 使用
vite --force强制重新预构建所有依赖（跳过缓存校验） - 若用 pnpm，注意其硬链接机制可能导致某些包路径解析异常；可尝试
pnpm store prune清理后重装
验证是否是插件或别名配置冲突
第三方插件（尤其自定义 resolver 或 alias 插件）可能干扰 Vite 的依赖解析流程：
- 临时注释掉
vite.config.ts中非必要的插件，特别是涉及resolveId或load钩子的插件 - 检查
resolve.alias是否意外覆盖了真实依赖路径，比如把react指向了一个不存在的本地文件 - 确认没有在
optimizeDeps.include中手动加入语法错误的路径或未安装的包名
