5月28日 04:05

如何从 Webpack 迁移到 Rspack？

Rspack 是字节跳动开源的基于 Rust 的高性能构建工具，从设计之初就以 Webpack 兼容性为核心目标。Rspack 1.0 已于 2024 年 10 月正式发布，到 2026 年已成为生产就绪的 Webpack 替代方案，在大型项目中可实现 5-10 倍的构建速度提升。以下是完整的迁移路径和关键要点。

核心答案

Rspack 与 Webpack 的配置兼容性约 95%，大多数项目可在 1-2 天内完成迁移。迁移的核心步骤：替换依赖 → 重命名配置文件 → 更新构建脚本 → 修复不兼容项 → 验证构建产物一致性。Yelp 等公司的实际迁移案例显示，迁移后构建时间减少约 50%，HMR 速度从 3-5 秒缩短到 500 毫秒以内。

迁移步骤

1. 替换依赖

卸载 Webpack 相关包，安装 Rspack 对应包：

bash
# 卸载 Webpack 依赖
npm uninstall webpack webpack-cli webpack-dev-server

# 安装 Rspack 依赖
npm install @rspack/core @rspack/cli -D

# 如果使用 dev-server
npm install @rspack/dev-server -D

使用 pnpm 或 yarn 时同理。注意 Rspack 要求 Node.js >= 16。

2. 迁移配置文件

将 webpack.config.js 复制为 rspack.config.js，大部分配置可以直接复用：

js
// rspack.config.js — 从 webpack.config.js 复制后调整
const rspack = require('@rspack/core');

module.exports = {
  entry: './src/index.js',    // 入口配置完全兼容
  output: {
    filename: '[name].[contenthash].js',
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      // 大部分 loader 规则可以直接复用
    ],
  },
  plugins: [
    new rspack.HtmlWebpackPlugin({ template: './public/index.html' }),
  ],
  resolve: {
    extensions: ['.js', '.jsx', '.ts', '.tsx'],
  },
};

需要修改的地方主要是导入语句：将 require('webpack') 替换为 require('@rspack/core')。

3. 更新构建脚本

json
{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build"
  }
}

4. 修复不兼容项

这是迁移中耗时最多的环节，常见的需要调整的配置：

loader 替换：移除 ts-loader 和 babel-loader，Rspack 内置 swc-loader，原生支持 TypeScript 和 JSX 编译
插件替换：TerserWebpackPlugin 用 Rspack 内置的 SwcJsMinimizerRspackPlugin 替代；MiniCssExtractPlugin 用 rspack.CssExtractRspackPlugin 替代
自定义插件：如果项目中使用了访问 compilation.entrypoints 等内部 API 的自定义插件，需要对照 Rspack 的 API 进行调整

js
// Rspack 内置能力替代示例
module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          loader: 'builtin:swc-loader',  // 内置 swc，替代 ts-loader
          options: {
            jsc: {
              parser: { syntax: 'typescript', tsx: true },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};

5. 验证构建产物

迁移完成后，务必对比 Webpack 和 Rspack 的构建产物，确保功能一致性：

对比产出文件数量和体积
运行全量测试用例
检查运行时行为是否一致（特别是动态 import、代码分割、环境变量注入等）
使用 rspack build --profile 分析构建产物

兼容性详情

配置项	兼容程度	说明
Entry	完全兼容	所有入口配置方式均支持
Output	大部分兼容	部分冷门选项有差异
Module Rules	大部分兼容	loader 生态覆盖率 90%+
Resolve	完全兼容	别名、扩展名等均支持
Plugins	部分兼容	常用插件覆盖率 90-95%，自定义插件需检查
Dev Server	接近兼容	`@rspack/dev-server` API 与 `webpack-dev-server` 高度一致

常见问题排查

某个 Webpack 插件不兼容怎么办？

首先查阅 Rspack 官方兼容性列表。如果确实不支持，可以：1）寻找该插件在 Rspack 中的替代方案；2）通过 compatLayer 配置尝试兼容运行；3）暂时保留 Webpack 构建路径，采用渐进式迁移。

迁移后构建速度没有明显提升？

检查是否仍在使用 JavaScript 实现的 loader（如 postcss-loader、sass-loader），它们会成为性能瓶颈。优先替换为 Rspack 内置的 Rust 实现或社区提供的 SWC-based 方案。同时检查 source-map 配置，开发环境建议使用 cheap-module-source-map。

大型 monorepo 如何迁移？

推荐采用适配器模式（Adapter Pattern）：创建统一的构建配置工厂函数，根据环境变量选择输出 Webpack 或 Rspack 配置。Yelp 在迁移其 monorepo 时采用了分阶段上线策略，先在新分支验证，再逐步放量。保留 Webpack 配置作为回滚方案，直到 Rspack 构建稳定运行至少一个迭代周期。

TypeScript 项目需要额外配置吗？

Rspack 内置 SWC 支持 TypeScript 编译，可以移除 ts-loader、fork-ts-checker-webpack-plugin 等相关依赖。但注意 Rspack 不执行类型检查，需要单独运行 tsc --noEmit 或在 IDE 中处理类型检查。

性能对比参考

基于社区基准测试和实际迁移案例的数据：

指标	Webpack	Rspack	提升
冷启动时间	30s+	~1.4s	约 20 倍
生产构建	30-60s	3-4s	约 10 倍
HMR 增量编译	3-5s	<500ms	约 8 倍
内存占用	较高	较低	30-50%

以上数据来自中大型 React 项目，实际效果因项目规模和配置复杂度而异。

迁移策略选择

何时选择 Rspack？

现有项目使用 Webpack 且迁移到 Vite 成本过高（如重度依赖 Webpack 特有插件链）
大型 monorepo 或企业级应用需要显著的构建速度提升
团队熟悉 Webpack 生态，希望最低学习成本获得性能收益

何时考虑其他方案？

全新项目且不依赖 Webpack 生态 → 优先考虑 Vite
Next.js 项目 → Turbopack 是官方推荐的加速方案
Vue 生态项目 → Rsbuild（基于 Rspack 的上层方案）提供更开箱即用的体验

Rspack 的定位是 Webpack 项目的低风险高回报迁移路径，而非所有场景的最优解。选择工具时首先要明确项目的实际瓶颈和团队的迁移预算。

标签：Rspack