构建工具迁移别把旧系统一次推倒先把慢和难维护分别说清构建工具迁移常从“旧项目太慢”开始但冷启动、热更新和生产打包是不同链路。瓶颈可能在转译、类型检查、插件、文件扫描或 I/O也可能来自项目本身的模块关系。先保存构建命令、环境和阶段耗时再决定更换工具是否能解决主要问题。配置难维护也需要具体证据哪些 loader 没有负责人哪些插件依赖隐式全局哪些目标浏览器仍在支持范围。直接把 Webpack 配置翻译成另一种语法会把旧假设一并搬过去一开始就删除旧路径又让差异难以复核。一次性迁移时CSS Modules 的 hash、CommonJS/ESM 互操作和旧浏览器 polyfill 都可能出现差异。应在代表性页面和目标浏览器上做双构建对比并保留可回退路径。双构建可以提供对照但也会增加配置同步成本。是否采用、保留多久应由迁移范围和回退条件决定。重点是每次只改变可以验证的一组行为并让旧制品仍可重新构建。迁移时容易漏掉的差异1. 语法与模块互操作性Module Interoperability隐形断层旧项目可能混用 CommonJS 与 ESM并通过 alias、ProvidePlugin 或自定义 loader 注入内容。新工具对同一写法的解析和开发、生产路径可能不同。应先扫描这些隐式入口并用实际模块导入、动态加载和错误路径验证不能只看首页成功编译。2. Polyfill 与 Target 降级失效目标语法与运行时 Polyfill 是两件事。新工具的target设置不一定等价于旧 Babel 与core-js链路。先从产品支持范围取得浏览器与运行环境清单再在目标环境运行代表性页面。没有证据仍在使用的旧目标也应通过产品决定移除不要让迁移顺手改掉兼容承诺。3. Chunk 拆分策略与缓存命中率破损新旧工具的分块名称和边界可能不同。总资源体积只是一个角度还要检查入口首载、异步路由、公共依赖重复和内容哈希稳定性。静态目录大小不能直接推导缓存命中缓存规则和真实请求需要单独观察。建立可对照的迁移顺序可以先为一个代表性入口增加新构建固定依赖、环境变量与输入资源比较功能和产物。若项目最迫切的问题在开发服务器可先验证开发链路若问题来自生产分块则应尽早生成候选制品。顺序由瓶颈决定不必套用“开发环境一定先行”。CI 同时运行两套构建时记录工具版本、警告、资源清单和构建阶段。静态 Diff 负责发现变化浏览器测试负责确认页面行为目标平台测试负责兼容性。差异无需收敛到任意固定比例而要逐项解释哪些是预期、哪些需要修正。切换时按入口、路由或发布渠道缩小范围并保留使用旧工具重新构建同一提交的能力。新旧产物不要混在同一缓存键下监控也要能识别构建来源。发现问题后才能把请求与具体制品对应起来。一个构建目录比较示例下面的BuildArtifactComparator扫描两个目录按规范化文件名比较资源是否缺失和大小差异。它不能证明产物兼容不同工具可能采用完全不同的分块命名代码拆分合理变化也会被标记示例忽略 JSON还没有检查新目录多出的文件、入口引用、source map 和运行行为。默认比例只是示例参数应由项目基线决定。工具还需处理空目录、零字节文件、符号链接和扫描错误使用的哈希算法也只服务于内容比较不承担安全完整性校验。实际门禁应先输出报告供人工确认再根据稳定规则决定是否阻断。import * as fs from fs; import * as path from path; import * as crypto from crypto; export interface ArtifactFileMeta { relativePath: string; sizeBytes: number; hash: string; } export interface DiffReport { isCompatible: boolean; totalSizeDiffBytes: number; missingFiles: string[]; oversizedFiles: string[]; summary: string; } /** * 构建产物静态 Diff 校验器 */ export class BuildArtifactComparator { /** * 扫描指定打包输出目录生成文件元数据 Map */ public static scanArtifactDirectory(dirPath: string): Mapstring, ArtifactFileMeta { const fileMap new Mapstring, ArtifactFileMeta(); const walk (currentDir: string) { const files fs.readdirSync(currentDir); for (const file of files) { const fullPath path.join(currentDir, file); const stat fs.statSync(fullPath); if (stat.isDirectory()) { walk(fullPath); } else if (stat.isFile()) { // 忽略 .map 文件与 stats.json if (file.endsWith(.map) || file.endsWith(.json)) continue; const relativePath path.relative(dirPath, fullPath); const fileBuffer fs.readFileSync(fullPath); const hash crypto.createHash(md5).update(fileBuffer).digest(hex); fileMap.set(relativePath, { relativePath, sizeBytes: stat.size, hash, }); } } }; walk(dirPath); return fileMap; } /** * 对比 Webpack 产物与新构建引擎产物 * param webpackDir Webpack 输出目录路径 * param newEngineDir 新构建引擎输出目录路径 * param maxAllowedSizeDiffRatio 允许的最大体积偏差比例 (默认 0.05 即 5%) */ public static compareArtifacts( webpackDir: string, newEngineDir: string, maxAllowedSizeDiffRatio: number 0.05 ): DiffReport { const webpackFiles this.scanArtifactDirectory(webpackDir); const newEngineFiles this.scanArtifactDirectory(newEngineDir); let totalWebpackSize 0; let totalNewEngineSize 0; webpackFiles.forEach(meta (totalWebpackSize meta.sizeBytes)); newEngineFiles.forEach(meta (totalNewEngineSize meta.sizeBytes)); const missingFiles: string[] []; const oversizedFiles: string[] []; // 检查核心静态资源是否有缺失或严重膨胀 webpackFiles.forEach((wpMeta, relPath) { // 简单剔除文件 Hash 后进行正则基准匹配 (如 main.a1b2c.js - main.js) const normalizedName relPath.replace(/\.[a-f0-9]{8,16}\./, .); let matchedInNew false; newEngineFiles.forEach((newMeta, newRelPath) { const newNormalized newRelPath.replace(/\.[a-f0-9]{8,16}\./, .); if (normalizedName newNormalized) { matchedInNew true; // 检测单文件体积突变 const sizeDiffRatio Math.abs(newMeta.sizeBytes - wpMeta.sizeBytes) / wpMeta.sizeBytes; if (sizeDiffRatio maxAllowedSizeDiffRatio) { oversizedFiles.push( ⚠️ 资源体积偏离大: ${normalizedName} (Webpack: ${wpMeta.sizeBytes}B, NewEngine: ${newMeta.sizeBytes}B) ); } } }); if (!matchedInNew) { missingFiles.push(relPath); } }); const totalSizeDiffBytes totalNewEngineSize - totalWebpackSize; const overallDiffRatio Math.abs(totalSizeDiffBytes) / totalWebpackSize; const isCompatible missingFiles.length 0 overallDiffRatio maxAllowedSizeDiffRatio; return { isCompatible, totalSizeDiffBytes, missingFiles, oversizedFiles, summary: Webpack 总体积: ${(totalWebpackSize / 1024).toFixed(2)}KB, 新引擎总体积: ${(totalNewEngineSize / 1024).toFixed(2)}KB, 偏差: ${(overallDiffRatio * 100).toFixed(2)}%, }; } } // CI/CD 质量门禁示例 if (require.main module) { const wpOutputDir ./dist-webpack; const newOutputDir ./dist-rspack; if (fs.existsSync(wpOutputDir) fs.existsSync(newOutputDir)) { const report BuildArtifactComparator.compareArtifacts(wpOutputDir, newOutputDir); console.log( 构建产物静态 Diff 结果:, report.summary); if (!report.isCompatible) { console.error( CI 打回: 新旧构建产物偏差过大暂停线上切换); report.oversizedFiles.forEach(msg console.error(msg)); process.exit(1); } else { console.log(✅ 构建产物一致性校验通过可以安全发版); } } }每个阶段的验证重点迁移阶段核心任务确定性治理对策禁用反模式基线梳理记录命令、插件、目标环境和现有产物保存可复验构建与代表性页面只记录一个总耗时就决定换工具候选构建为限定入口配置新工具对照模块、CSS、资源路径和环境变量同时修改业务代码与全部构建配置CI 对照运行静态报告和浏览器测试解释分块、体积、警告与行为差异仅凭目录总大小宣布兼容小范围切换发布可识别的新制品稳定分流并演练旧构建重新接管新旧产物共用无法区分的缓存键收尾移除旧配置和临时适配确认调用方、文档与发布脚本已切换长期维护两套无负责人配置回退能力也会过期保留旧配置期间应在关键变更后确认它仍能构建当前提交。若只是把文件留在仓库却从不运行真正需要回退时可能早已失效。反过来两套配置长期并行会增加维护成本所以开始迁移时就写明清理条件和负责人。完成切换前从候选制品重新安装并跑关键路由检查错误上报、source map、资源缓存和目标浏览器。迁移记录关联提交、工具链版本与已解释差异。构建工具的收益只有在功能边界不丢、发布仍可追溯的前提下才有意义。