前端构建工具演进 从 Webpack 迁移到 Rolldown 的策略

构建工具这几年换了一轮：Webpack → Vite/esbuild → Turbopack/Rspack → Rolldown。业务团队真正关心的不是"谁更卷"，而是三件事：迁移风险、产物等价性、以及构建时间到底能省多少。本文给一套可执行的迁移与验证策略。

一、先建立度量基线

没有基线的迁移等于赌博。开工前先固化三组数据：

# 冷构建耗时
for i in 1 2 3 4 5; do
  rm -rf node_modules/.cache dist
  /usr/bin/time -f "%e s" npx webpack --mode production 2>&1 | tail -1
done

# 热启动耗时（首个可交互页面）
# 产物体积与 chunk 数
du -sh dist; find dist -name "*.js" | wc -l
# 关键 chunk 的 gzip 后体积
find dist -name "*.js" -exec gzip -c {} \; | wc -c

把冷构建、热启动、产物 gzip 总量、chunk 数写进 BUILD_BASELINE.md。迁移成功的定义就是"构建时间显著下降、产物 gzip 总量不超过阈值、无行为回归"。

二、迁移决策树

是否重度依赖 Webpack loader（raw-loader/worker-loader/css-modules 定制）？
├── 是 → 先做 loader 替换评估，或走 Rspack（loader 兼容层最厚）
└── 否 → 是否 SSR 且需要 fine-grained 控制产物？
         ├── 是 → Rolldown（Rollup 语义 + Rust 内核）
         └── 否 → Vite（Dev 体验最好）

判断依据：Rspack/Rolldown 都是 Rust 内核，量级接近（大型项目常见 5~10 倍构建加速）；差别在生态兼容面。Rspack 主打 Webpack 兼容，Rollldown 主打 Rollup 插件生态兼容。存量项目选哪个，主要看你的自定义逻辑是写在哪一侧。

三、渐进式迁移：先影子构建

不要一次性替换。最稳的路径是双跑影子构建：新工具产物与老产物共存一段时间，用 diff 校验。

// rolldown.config.mjs（示例骨架）
import { defineConfig } from "rolldown";

export default defineConfig({
  input: { main: "src/main.ts", admin: "src/admin.ts" },
  output: { dir: "dist-new", sourcemap: true },
  resolve: { extensions: [".ts", ".tsx", ".js"] },
  plugins: [/* 复用 Rollup 生态插件 */],
});

npm run build:webpack   # dist
npm run build:rolldown  # dist-new
node scripts/verify-build.mjs     # 结构校验

四、产物等价性怎么校验

产物字节级等价在真实项目里不现实（压缩器差异、模块顺序差异），要做的是行为等价性校验：

// scripts/verify-build.mjs（要点）
import { readFileSync, readdirSync } from "node:fs";

const norm = (s) => s
  .replace(/\/\*!.*?\*\//g, "")
  .replace(/sourceMappingURL=.*$/gm, "");

function exportsOf(dir) {
  const set = new Set();
  for (const f of readdirSync(dir)) {
    if (!f.endsWith(".js")) continue;
    const code = norm(readFileSync(`${dir}/${f}`, "utf8"));
    for (const m of code.matchAll(/__name:\s*"?([A-Za-z_$][\w$]*)"?/g)) set.add(m[1]);
  }
  return set;
}

const a = exportsOf("dist"), b = exportsOf("dist-new");
const missing = [...a].filter((x) => !b.has(x));
if (missing.length) {
  console.error("MISSING EXPORTS:", missing.slice(0, 20));
  process.exit(1);
}

真正的等价性靠端到端：把 dist-new 挂到预发环境跑冒烟 e2e（Playwright 覆盖核心流程），并抓首屏关键指标（LCP/TTI/错误率）对比。构建工具的坑基本都是"某类边界场景行为不同"，单靠静态 diff 抓不全。

五、必须验证的六类边界场景

| 场景 | 风险点 | |---|---| | 动态 import + 魔法字符串 | 静态分析失效导致 chunk 缺失 | | CommonJS 混用 ESM | 具名导出丢失、默认导出多层嵌套 | | Node 内置模块在浏览器被引用 | 缺 polyfill 直接构建失败 | | CSS Modules 命名约定 | 类名 hash 规则不一致导致样式错乱 | | source map 完整性 | 报错栈无法定位 | | 环境变量注入时机 | process.env.X 未 define 打成 undefined |

针对第一类，加一条 CI 检查：产物里出现 Cannot find module 类字符串就失败。针对最后一类，在构建后 grep 产物确认关键变量已被常量替换：

if grep -rn "process.env.API_BASE" dist-new/assets/*.js; then
  echo "环境变量未被替换"; exit 1
fi

六、Dev 体验与 CI 的分别收益

要区分两个收益面：本机 dev 冷启动/热更新（Vite/Rolldown dev 收益最直观）与 CI 全量构建（Rust 内核收益最大）。

CI 上还有两个高性价比优化，迁移前就该先做，能立即拿到收益：

# 构建缓存复用
- uses: actions/cache@v4
  with:
    path: |
      node_modules/.cache
      dist
    key: build-${{ hashFiles('**/pnpm-lock.yaml', 'src/**') }}

再加拆分：把不影响产物的类型检查、lint 拆成并行 job，构建 job 只做 bundle。很多团队迁移工具前，先把 CI 时间砍一半。

七、回滚开关

迁移期在部署层保留开关，两条流水线分别产出两个镜像/静态目录，通过网关头切换或灰度比例放量：

/static-webpack/    稳定产物 95%
/static-rolldown/   新产物  5% → 30% → 100%

保留一个迭代周期，观察前端错误率（Sentry 按 release 分组）与首屏指标无异动再彻底切换、删除旧配置。

小结

工具换代本身不产生业务价值，缩短的反馈回路与 CI 成本才是。按"基线 → 影子双跑 → 行为等价校验 → 灰度回滚"四步走，风险可以压到很低。选型的判断点只有两个：自定义逻辑在 Webpack 侧还是 Rollup 侧，以及你是否需要 SSR 的产物细粒度控制。别为跑分数字迁移，为"每次提交少等 4 分钟"迁移。