构建链路迁移时先让旧流程能回退

构建链路迁移时先让旧流程能回退1. 重构演习的惨烈教训为了快 3 秒把上线发布搞挂了存量项目从 Webpack 迁移到 Vite 时不能只替换配置文件。依赖兼容性、浏览器支持范围、资源路径和运行时全局变量都需要单独验证。例如旧代码可能依赖require.context部分包可能引用global、Buffer或process。本地开发能运行并不保证生产构建和目标浏览器中的行为一致。迁移期应保留可回退的构建链路并按页面和关键路径逐步验证。2. 存量 Webpack 项目迁移 Vite 的常见兼容点迁移风险主要来自构建模型和运行时假设的差异。Webpack 是基于 Bundle打包逻辑的它不挑食不管是 CommonJS、AMD 还是 ESMWebpack 都会自备一个强大的require运行时帮你在内存里全量抹平。而 Vite 在开发阶段是基于 Native ESM原生 ES 模块的它要求你的代码和三方依赖必须严格遵守标准的 ES 模块规范。大型前端项目中常见以下三类兼容问题第一类是require.context与动态 import 的差异。旧项目可能用require.context注册路由或图标迁移时需要改为import.meta.glob或适配层并逐处验证语义是否一致。第二类是Node.js 全局变量Polyfill缺失。依赖若引用global、Buffer或process.env需要确认其浏览器支持方式。Webpack 5 也不再默认填充多数 Node polyfill不能假设旧链路一定会兜底。第三类是CSS 加载顺序变化。构建工具、代码分割和动态导入都可能改变样式到达顺序。迁移时应通过关键页面截图或视觉回归测试检查覆盖关系。下面这张表梳理了迁移过程中的核心暗坑与正确的工程解法构建隐患/暗坑类型Webpack 默认行为Vite 默认行为生产级工程解法require.context动态加载项目可能依赖其打包语义需要改为import.meta.glob或适配层先建立兼容封装再逐步替换Nodeglobal/Buffer是否可用取决于项目配置与版本默认不提供 Node 运行时优先替换浏览器不兼容依赖必要时审慎配置 polyfillCommonJS 依赖包可由 webpack 处理开发阶段可能由 OptimizeDeps 预构建验证依赖包和生产构建行为必要时替换依赖环境变量读取process.env.XXXimport.meta.env.VITE_XXX编译期自定义 Define 别名映射隔离把问题在编译前梳理干净迁移才不会变成撞大运。3. 分阶段平滑切换路径双轨构建Dual-Track Build与兼容降级架构迁移期可采用双轨构建保留旧链路作为回退路径在 CI 中同时构建并运行关键回归测试达到预先定义的稳定标准后再切换。具体实施分为四个阶段第一阶段AST 预清洗与规范改造Pre-clean Phase用自动化 AST 脚本全局扫一遍老代码把process.env替换为环境无关的提取函数将require.context批量改写为import.meta.glob的兼容封装确保代码库同时兼容两套打包工具。第二阶段Vite 配置文件与预构建治理Dev Engine Phase引入 Vite 作为开发环境启动项。对确有预构建问题的依赖再评估是否配置optimizeDeps.include。第三阶段双轨构建与 CI 产物 Diff 校验Dual-Build Phase在 CI/CD 中同时输出 Webpack 和 Vite 产物并运行 Playwright 回归集。不要把资源 Hash 或 DOM 完全一致作为唯一目标应重点验证页面功能、资源可访问性和视觉结果。第四阶段灰度切流与旧打包器卸载Cutover Phase从小范围流量开始切换观察错误、资源加载和关键业务指标满足退出条件后再扩大范围。确认不再需要回退时才删除旧配置。迁移计划应明确验证项、回退方案和切换条件。4. 生产级 Vite 智能化迁移插件与 AST 自动修复脚本为了让迁移过程自动化我们编写了一套专用的迁移 Node.js AST 转换脚本与自定义 Vite 插件。第一套脚本是基于 Babel AST 的代码预清洗器可以在 5 秒内自动把老项目里上百个文件中的require.context和process.env转换为 Vite 兼容的代码// scripts/migrate-to-vite-ast.ts — 确定性 AST 迁移转换脚本 import * as parser from babel/parser; import traverse from babel/traverse; import generate from babel/generator; import * as t from babel/types; import fs from fs-extra; import path from path; export async function transformLegacyCode(filePath: string) { const code await fs.readFile(filePath, utf-8); const ast parser.parse(code, { sourceType: module, plugins: [typescript, jsx], }); let isModified false; traverse(ast, { // 1. 将 process.env.REACT_APP_XXX 自动转换为 import.meta.env.VITE_XXX MemberExpression(astPath) { if ( t.isMemberExpression(astPath.node.object) t.isIdentifier(astPath.node.object.object, { name: process }) t.isIdentifier(astPath.node.object.property, { name: env }) ) { const envVarName (astPath.node.property as t.Identifier).name; if (envVarName.startsWith(REACT_APP_) || envVarName.startsWith(MIX_)) { const newEnvName envVarName.replace(/^(REACT_APP_|MIX_)/, VITE_); astPath.replaceWith( t.memberExpression( t.memberExpression(t.identifier(import), t.identifier(meta)), t.memberExpression(t.identifier(env), t.identifier(newEnvName)) ) ); isModified true; } } }, // 2. 将 require.context(./dir, true, /\.png$/) 转换为 Vite 的 import.meta.glob CallExpression(astPath) { const callee astPath.node.callee; if ( t.isMemberExpression(callee) t.isIdentifier(callee.object, { name: require }) t.isIdentifier(callee.property, { name: context }) ) { const args astPath.node.arguments; if (args.length 1 t.isStringLiteral(args[0])) { const dirPath args[0].value; // 构建 import.meta.glob 的新 AST 节点 const globPattern ${dirPath}/**/*.{png,jpg,jpeg,svg,tsx,ts}; const globCall t.callExpression( t.memberExpression( t.memberExpression(t.identifier(import), t.identifier(meta)), t.identifier(glob) ), [t.stringLiteral(globPattern), t.objectExpression([ t.objectProperty(t.identifier(eager), t.booleanLiteral(true)) ])] ); astPath.replaceWith(globCall); isModified true; } } }, }); if (isModified) { const output generate(ast, {}, code); await fs.writeFile(filePath, output.code, utf-8); console.log(✅ [AST 自动修缮] 成功修复兼容文件: ${path.basename(filePath)}); } }第二套代码是生产级vite.config.ts配置文件内置了 Node.js 变量填充、CommonJS 插件与预构建优化// vite.config.ts — 生产级双轨迁移 Vite 配置 import { defineConfig } from vite; import react from vitejs/plugin-react; import path from path; import { NodeGlobalsPolyfillPlugin } from esbuild-plugins/node-globals-polyfill; export default defineConfig({ plugins: [ react(), // 自定义安全拦截插件防止编译期误泄露全量环境变量 { name: vite-plugin-security-guard, transform(code, id) { if (id.endsWith(.tsx) || id.endsWith(.ts)) { if (code.includes(process.env.SECRET_KEY)) { throw new Error( [安全构建拦截] 检测到文件 ${id} 中包含高危服务端秘钥引用); } } return null; }, }, ], resolve: { alias: { : path.resolve(__dirname, ./src), // 手工将老项目中可能依赖的 Node 全局对象指向浏览器兼容 Polyfill buffer: rollup-plugin-node-polyfills/polyfills/buffer-es6, process: process/browser, }, }, define: { // 填充 Webpack 老代码里的 global 声明防止 runtime 抛出 ReferenceError global: globalThis, }, optimizeDeps: { // 强制显式预构建那些包含 CommonJS 的老旧重型 AI 渲染库 include: [echarts, lodash-es, dagre-d3], esbuildOptions: { // 开启 Node 全局变量 ESBuild 插件 plugins: [ NodeGlobalsPolyfillPlugin({ process: true, buffer: true, }), ], }, }, build: { target: es2015, outDir: dist-vite, sourcemap: true, // 解决大型存量项目打包单 Chunk 过大的分割策略 rollupOptions: { output: { manualChunks(id) { if (id.includes(node_modules)) { if (id.includes(react) || id.includes(react-dom)) { return vendor-core; } if (id.includes(echarts) || id.includes(zrender)) { return vendor-charts; } return vendor-async; } }, }, }, }, });自动化 AST 转换可以减少重复修改但输出仍需通过类型检查、构建和页面回归测试。polyfill 与分包配置也应只针对已确认的兼容问题引入。5. 迁移验证用项目基线衡量收益在切换前后应在相同机器、缓存状态和依赖版本下记录开发启动时间、HMR 延迟、生产构建耗时、产物体积和关键页面错误率。不要把单次数据外推为所有项目的收益。双轨构建、回归测试和灰度切换的价值在于降低迁移风险而不是保证“零故障”。确认兼容边界和回退条件后再逐步停用旧构建链路。