vite构建阶段明确分离开发时按需编译（esm+原生import）与生产构建（rollup驱动），需区分优化hmr体验或构建产物；关键配置包括build.rollupoptions、target、resolve.alias等，须结合--report分析产物、pure注释验证tree-shaking、动态导入检查chunk分割。
理解 Vite 构建阶段的核心分工
Vite 的构建不是“打包器替代 Webpack”这么简单，而是把开发时的按需编译（ESM + 原生 import）和生产构建（Rollup 驱动）做了明确分离。重构代码前先确认：你改的是开发体验（如 HMR 行为、插件逻辑），还是构建产物（如 chunk 分割、tree-shaking 效果、输出格式）。两者调试方式和配置入口完全不同。
检查 vite.config.ts 中影响构建结果的关键项
很多重构问题其实源于配置误用。重点关注以下几类：
- build.rollupOptions：直接透传给底层 Rollup，修改 output.manualChunks、plugins、external 等会显著改变产物结构；
- build.target / build.modules：决定语法降级范围，改错会导致低版本浏览器报错或 polyfill 漏入；
- resolve.alias / resolve.dedupe：别名冲突或重复引入（尤其多包 monorepo 场景）会破坏 tree-shaking；
- optimizeDeps.include / exclude：影响预构建行为，改完后首次启动慢或 HMR 失效常源于此。
按模块粒度验证构建产物变化
别只看 dist/ 是否生成，要主动分析产物是否符合预期：
- 运行 vite build --report 生成
stats.html，用可视化工具查 bundle 组成、重复依赖、未被引用的导出； - 对关键模块加
/*#__PURE__*/注释，确认无副作用的函数是否真被摇掉； - 用
import('./module.js').then(...)动态导入后，检查是否生成独立 chunk，以及命名是否符合build.rollupOptions.output.entryFileNames规则。
常见重构陷阱与对应解法
这些点看似小，却高频导致构建异常：
-
全局变量污染：在
src/env.d.ts或vite-env.d.ts中声明的类型不会进构建，但若误写window.xxx = ...在模块顶层，会被 Rollup 当作有副作用保留； -
条件导入失效：用
if (import.meta.env.PROD) { import('./prod-only.js') }时，Vite 默认不删掉非生产分支 —— 需配合build.rollupOptions.plugins加rollup-plugin-strip-code或手动 define 替换； -
CSS 提取错乱：启用了
build.cssCodeSplit: true却没配好build.rollupOptions.output.assetFileNames，导致 CSS 文件名不含 hash，缓存失效； -
第三方库未正确 external：比如把
vue打进 bundle，又在 HTML 中单独引入 CDN 版本，运行时报 “Duplicate application instance detected”。
