排查 vite 构建产物异常,核心思路是区分开发环境(hmr)与生产构建(rollup)的差异,通过清理缓存、检查插件配置和对比输出日志来定位问题。具体做法包括使用 npx vite build --debug 开启详细日志,检查 vite.config.js 中的 build.rollupoptions 配置是否冲突,以及确认第三方库是否正确打包。若产物出现运行时错误,需重点检查代码分割(code splitting)导致的异步加载失败或全局变量污染。

Vite 构建产物中缺少特定模块或文件
当构建产物中缺失预期文件时,通常是因为 Rollup 的 Tree Shaking 机制移除了未被引用的代码,或者插件配置错误地过滤了资源。解决方法是检查入口文件是否显式引入了该模块,并在 vite.config.js 中通过 build.rollupOptions.output.manualChunks 强制保留关键 chunk,或调整 external 配置以避免意外排除。

import { createApp } from 'vue';
import App from './App.vue';
import './missing-module.css'; // 确保显式引入
const app = createApp(App);
app.mount('#app');
上述代码中,若 ./missing-module.css 未在组件中引用但需在构建后存在,Vite 默认可能不会将其作为独立 chunk 输出,除非在 HTML 模板中直接引用或通过插件处理。检查 dist/ 目录下的 index.html 是否包含对该资源的引用。
构建产物运行时出现 404 或路径错误
构建后页面白屏或资源 404,多因 base 配置与实际部署路径不匹配,或动态导入路径解析错误。需在 vite.config.js 中设置正确的 base 值(如 /my-app/),并确保所有路由和静态资源引用使用相对路径或基于 base 的路径。对于动态导入,避免使用硬编码字符串,改用常量或函数生成路径。

// vite.config.js
export default {
base: '/my-app/', // 根据部署子目录调整
build: {
rollupOptions: {
output: {
manualChunks: {
vendor: ['vue', 'vue-router']
}
}
}
}
};
若部署在子目录,base 必须与服务器根路径一致。检查构建后的 index.html 中 <script></script> 和 标签的 src/href 是否以 /my-app/ 开头。同时,确保后端服务器正确配置静态资源服务,支持 SPA 回退到 index.html。
基于手动分块配置导致构建失败的具体问题
当在 vite.config.js 中使用 manualChunks 自定义代码分割时,若配置不当会导致构建报错或产物不完整。例如,将未导出的内部模块强行拆分会引发 Module not found 错误。应仅对已导出且稳定的依赖进行分块,并通过 --debug 日志验证 chunk 划分是否符合预期。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











