四类高频构建问题闭环解决：一、白屏查路径与入口配置；二、HMR失效检查模块依赖链与插件顺序；三、样式丢失定位变量注入与CSS Modules引用；四、OOM先禁source map、删冗余插件、拆大依赖。
直接聚焦四类高频构建问题，按“定位—复现—调优—验证”闭环推进，不堆配置、不讲原理，只解决你正在卡住的地方。
一、白屏问题：先查路径，再看模块加载
页面打开空白，控制台报 404 或 Failed to load module script，大概率是入口路径错配：
- 确认
src/pages/xxx/index.html中的<script type="module" src="/src/pages/xxx/main.js"></script>路径是否加了多余斜杠或漏写type="module" - 检查
vite.config.js的build.rollupOptions.input是否用了path.resolve写绝对路径，避免相对路径导致构建时找不到 HTML - 运行
vite build --debug，看日志里是否出现skipping chunk graph analysis for non-entry chunk—— 这说明某个页面没被识别为入口，需补全配置
二、HMR 失效：不是插件问题，而是模块图断连
改了组件或样式，浏览器没更新，不是 Vite 坏了，而是热更新链路没接上：
- 确保修改的是当前页面对应的
main.js或其直接 import 的模块；Vite 默认只监听当前入口依赖图内的文件 - 检查是否有自定义
html插件提前拦截了index.html注入逻辑，导致 HMR runtime 没写进去 - 若用 Vue，确认
@vitejs/plugin-vue在插件数组中靠前，且没被其他插件（如vite-plugin-html）覆盖掉<script></script>注入时机
三、样式丢失：不是 CSS 没编译，而是作用域或注入时机错位
开发时样式正常，构建后部分样式不生效，常见于 SCSS 全局变量或 CSS-in-JS 场景：
- 全局变量未注入？在
vite.config.js中配置css.preprocessorOptions.scss.additionalData，指向一个含$primary-color: #1890ff;的变量文件 - 多个页面共用样式但重复打包？把公共样式抽到
src/shared/styles/global.scss，并在各main.js开头统一import '@/shared/styles/global.scss' - 使用 CSS Modules 时类名异常？确认
.module.scss文件命名规范，且组件中通过import styles from './xxx.module.scss'正确引用
四、构建内存溢出（OOM）：别急着加参数，先砍体积和插件
CI 上跑 vite build 直接崩溃，报 JavaScript heap out of memory，本质是 Rollup 把太多东西塞进内存：
- 禁用不必要的 source map：
build.sourcemap = 'hidden'，实测可降内存占用 25%+，且不影响线上错误定位 - 删掉非核心插件：比如
vite-plugin-legacy（除非要兼容 IE）、vite-plugin-compression（压缩应交给 Nginx） - 拆分大依赖：用
build.rollupOptions.output.manualChunks单独抽离vue、lodash-es、echarts等大库，避免它们和业务代码混在一个 chunk 里反复解析
不复杂但容易忽略。关键不是让 Vite 更“全能”，而是让它只做真正该做的事。
