构建工具升级，先把插件兼容性列成清单
从 Vite 4 升级到 Vite 6 前，应先阅读目标版本的迁移指南和依赖的兼容说明。构建工具、Rollup、Node.js、插件及样式预处理器的版本组合都会影响结果；不能仅通过修改package.json判断升级风险。
1. Vite 版本升级中的四大“暗坑”风险
升级检查可从以下四个方向开始：
风险一：CJS / ESM 边界硬性切断（Deprecation of CJS API）
检查 Node.js 版本、Vite 的 CJS Node API 迁移要求，以及依赖是否依赖非标准的require()或运行时模块加载。浏览器出现模块语法错误也可能与部署的<script type="module">、目标浏览器或产物格式有关，应结合具体报错定位。
风险二：Rollup 升级带来的 Chunk 命名与 Hash 变化
底层 Rollup 或配置变化可能改变产物文件名和 hash。旧客户端请求旧资源出现 404，通常与部署时过早清理旧资源、HTML 缓存策略或发布原子性有关；应保留旧资源一段时间，并验证 HTML 与资源的缓存规则。
风险三：CSS 预处理器与 Sass/Less 编译引擎切换
检查 Sass/Less 版本、废弃 API 和全局注入配置。@import的迁移警告不必然导致 CSS 顺序变化；若样式回归，应通过视觉回归和产物 diff 确认具体原因。
风险四：自定义 Vite 插件钩子（Plugin Hooks）兼容性断层
自定义插件应按 Vite 与 Rollup 的目标版本逐个验证钩子签名、执行顺序和产物影响，并为关键注入逻辑加集成测试。
2. Vite 升级风险评估矩阵与自动化检测
为了防止升级导致事故，必须在升级前建立一套完整的风险评估流水线：
3. Vite 升级风险检测与构建基准对撞脚本
我们手写了一套升级风险评估 CLI 工具，在升级前自动对新旧构建结果进行指标对撞与语法检查：
import { build } from 'vite'; import * as fs from 'fs'; import * as path from 'path'; interface BuildStats { duration: number; chunkCount: number; totalSizeMB: number; } export async function runViteUpgradeAssessment(configPath: string): Promise<BuildStats> { const startTime = Date.now(); console.log('🚀 开始 Vite 升级构建设定分析与风险对撞...'); // 执行 Vite 构建 const output = await build({ configFile: configPath, build: { write: false // 内存中编译，不污染本地磁盘 } }); const duration = Date.now() - startTime; let chunkCount = 0; let totalSize = 0; if ('output' in output) { const outputs = Array.isArray(output.output) ? output.output : [output.output]; for (const item of outputs) { if (item.type === 'chunk') { chunkCount++; totalSize += Buffer.byteLength(item.code); } else { totalSize += Buffer.byteLength(item.source); } // 检查产物中是否存在未解开的 CJS 遗留语法 if (item.type === 'chunk' && item.code.includes('module.exports =')) { console.warn(`[升级风险警告] 产物 Chunk ${item.fileName} 中发现未转译的 CJS 语法！`); } } } const result: BuildStats = { duration, chunkCount, totalSizeMB: Number((totalSize / (1024 * 1024)).toFixed(2)) }; console.log(`✅ 评估完成: 构建耗时 ${duration}ms, 生成 ${chunkCount} 个 Chunk, 总体积 ${result.totalSizeMB} MB`); return result; }升级检查清单
先做依赖与 Node.js 版本检查，再用双版本构建比较产物和关键路由。最后在预发布环境验证静态资源缓存、样式、插件功能与目标浏览器。扫描module.exports只能提供线索，不能替代运行时测试。
