团队落地Vite最佳实践的核心是建立可共识、可验证、可延续的工程契约，涵盖统一入口管理（src/pages/**/index.html）、分阶段构建策略（dev/CI/prod隔离）、产物可验证（stats.html/depcheck/大小校验）及环境变量强约束（VITE_前缀、base路径统一）。
团队落地 Vite 构建最佳实践，核心不是堆配置，而是建立可共识、可验证、可延续的工程契约。重点在于统一入口管理、分阶段优化策略、构建结果可预期，避免“本地快、CI慢”“开发稳、上线崩”这类典型割裂。
统一多页面入口结构与自动化识别
中大型项目普遍面临页面分散、入口不一的问题。手动维护 build.rollupOptions.input 易出错且难同步。推荐做法：
- 约定
src/pages/**/index.html为唯一合法入口模式，每个子目录即一个独立页面 - 在
vite.config.ts中用 glob 自动扫描：build.rollupOptions.input = Object.fromEntries( glob.sync('src/pages/**/index.html').map(file => [path.basename(path.dirname(file)), file]) ) - 配合
resolve.alias统一映射@pages到src/pages，跨页面复用组件/工具时路径清晰、IDE 可跳转
分阶段构建策略：开发态、CI态、生产态各守其责
Vite 的 dev 和 build 是两条不同链路，混用同一套配置必然失衡。需按场景隔离目标：
-
开发态（vite serve）：关闭
server.hmr.overlay防止错误遮挡真实 DOM 问题；启用cacheDir: 'node_modules/.vite-dev'避免与 CI 缓存冲突 -
CI 态（vite build --mode ci）：强制
build.sourcemap = 'hidden'，禁用terser改用esbuild压缩，跳过类型检查（由单独tsc --noEmit步骤覆盖） -
生产态（vite build --mode production）：启用
build.rollupOptions.output.manualChunks按域拆包（如vendor、ui、api），并设置build.rollupOptions.output.entryFileNames加版本前缀，确保 CDN 缓存精准失效
构建产物必须可验证、可回溯
构建完成不能只看“打包成功”，要能回答三个问题：体积是否合理？依赖是否纯净？变更是否受控？
- 每次
npm run build后自动生成dist/stats.html（用rollup-plugin-visualizer），纳入 PR 检查项 - 用
depcheck+ 自定义脚本扫描package.json中声明但未 import 的依赖，防止“幽灵依赖”膨胀包体 - 在
buildEnd钩子中校验关键 chunk 大小阈值（如index.js ），超限自动报错，阻断高风险发版
环境变量与构建路径强约束
前端环境误用是线上事故高频原因。必须从机制上杜绝自由发挥：
- 所有环境变量名强制以
VITE_开头，且只在.env系列文件中定义；禁止在代码里硬编码 URL 或开关 -
import.meta.env.VITE_API_BASE必须与后端 Swagger 文档中的basePath完全一致，CI 流水线启动前先比对两者是否匹配 - 静态资源路径统一走
base: '/subapp/'配置，HTML 中不写相对路径./assets/，避免部署到非根路径时 404
