close
指南
配置
插件
API
博客
关于
贡献
指南
配置
插件
API
博客
关于
贡献

从 Webpack 迁移

Rspack 的配置设计基于 Webpack，可以轻松地将项目从 Webpack 迁移到 Rspack。

本文档主要针对使用 Webpack 5 的项目。由于 Rspack 的 API 和配置与 Webpack 5 保持一致。对于不使用 Webpack 5 的项目，还有其他迁移指南可以参考。

安装 Rspack

在您的项目目录中，将 Rspack 作为 devDependencies 安装。

npm
yarn
pnpm
bun
npm add @rspack/core @rspack/cli -D

现在您可以从项目中删除与 Webpack 相关的依赖项。

npm
yarn
pnpm
bun
npm remove webpack webpack-cli webpack-dev-server
提示

在某些情况下，您仍然需要将 webpack 作为开发依赖项保留，例如使用 vue-loader 或 fork-ts-checker-webpack-plugin。

这是因为这些插件直接 import Webpack 的子路径并与 Webpack 耦合。如果您遇到此问题，可以向这些插件的维护者提供反馈，询问他们是否可以将 webpack 设为可选依赖项。

更新 package.json

更新您的构建脚本，使用 Rspack 而不是 Webpack。

package.json
{
  "scripts": {
-   "serve": "webpack serve",
-   "build": "webpack build",
+   "serve": "rspack serve",
+   "build": "rspack build",
  }
}

更新配置

将 webpack.config.js 文件重命名为 rspack.config.js。

提示

Rspack 命令可以使用 -c 或 --config 指定配置文件，类似于 Webpack 命令。但是，与 Webpack 不同，如果未明确指定配置文件，Rspack 默认使用 rspack.config.js。

Rspack 目前不支持所有 Webpack 配置，并且某些配置可能会影响构建输出。为了确保构建输出的正确性，Rspack 默认情况下启用严格的配置验证。但是，Rspack 也提供了一种宽松模式，方便逐步迁移。您可以通过设置 RSPACK_CONFIG_VALIDATE 环境变量来启用它。

# Enable loose validation mode will print out erroneous configurations but will not throw error.
RSPACK_CONFIG_VALIDATE=loose rspack build
# Enable loose validation mode, without printing errors or throwing error.
RSPACK_CONFIG_VALIDATE=loose-silent rspack build

Rspack 正在积极地实现 Webpack 的即将推出的功能，因此一些配置默认值与 Webpack 5 不同，如下所示

配置 Webpack 默认值 Rspack 默认值
node.global true 'warn'
node.__filename 'mock' 'warn-mock'
node.__dirname 'mock' 'warn-mock'

您可以参考 配置 Rspack 查看 Rspack 支持的配置。

Webpack 内置插件

Rspack 已经实现了大多数 Webpack 内置插件，并使用相同的名称和配置参数，方便替换。

例如，替换 DefinePlugin

rspack.config.js
- const webpack = require('webpack');
+ const rspack = require('@rspack/core');

module.exports = {
  //...
  plugins: [
-   new webpack.DefinePlugin({
+   new rspack.DefinePlugin({
      // ...
    }),
  ],
}

查看 与 Webpack 一致的内置插件 了解更多关于 Rspack 中支持的 Webpack 插件的信息。

社区插件

Rspack 支持大多数 Webpack 社区插件，并且也为一些当前不支持的插件提供了替代方案。

查看 插件兼容性 了解更多关于 Rspack 与流行的 Webpack 社区插件的兼容性信息。

copy-webpack-plugin → rspack.CopyRspackPlugin

rspack.config.js
- const CopyWebpackPlugin = require('copy-webpack-plugin');
+ const rspack = require('@rspack/core');

module.exports = {
  plugins: [
-   new CopyWebpackPlugin({
+   new rspack.CopyRspackPlugin({
      // ...
    }),
  ]
}

mini-css-extract-plugin → rspack.CssExtractRspackPlugin

rspack.config.js
- const CssExtractWebpackPlugin = require('mini-css-extract-plugin');
+ const rspack = require('@rspack/core');

module.exports = {
  plugins: [
-   new CssExtractWebpackPlugin({
+   new rspack.CssExtractRspackPlugin({
      // ...
    }),
  ]
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
-          CssExtractWebpackPlugin.loader,
+          rspack.CssExtractRspackPlugin.loader,
          "css-loader"
        ],
+        type: 'javascript/auto'
      }
    ]
  }
}

tsconfig-paths-webpack-plugin → resolve.tsConfig

rspack.config.js
- const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  resolve: {
-   plugins: [new TsconfigPathsPlugin({})]
+   tsConfig: {}
  }
}

加载器

Rspack 的加载器运行器与 Webpack 的加载器功能完全兼容，支持绝大多数 Webpack 加载器。您可以直接使用现有的加载器，无需任何更改。但是，为了获得最佳性能，请考虑迁移以下加载器。

babel-loader / swc-loader → builtin:swc-loader

使用 builtin:swc-loader 比 babel-loader 和外部 swc-loader 具有更好的性能，因为它避免了 JavaScript 和 Rust 之间的频繁通信。

如果您需要使用 Babel 插件进行自定义转换逻辑，可以保留 babel-loader，但建议将其使用范围限制在较少的文件中，以防止性能大幅下降。

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /\.tsx?$/i,
-        use: [
-          {
-            loader: 'babel-loader',
-            options: {
-              presets: ['@babel/preset-typescript'],
-            },
-          },
-        ],
-        test: /\.jsx?$/i,
-        use: [
-          {
-            loader: 'babel-loader',
-            options: {
-              presets: ['@babel/preset-react'],
-            },
-          },
-        ],
-      },
+      {
+        test: /\.(j|t)s$/,
+        exclude: [/[\\/]node_modules[\\/]/],
+        loader: 'builtin:swc-loader',
+        options: {
+          jsc: {
+            parser: {
+              syntax: 'typescript',
+            },
+            externalHelpers: true,
+            transform: {
+              react: {
+                runtime: 'automatic',
+                development: !prod,
+                refresh: !prod,
+              },
+            },
+          },
+          env: {
+            targets: 'Chrome >= 48',
+          },
+        },
+      },
+      {
+        test: /\.(j|t)sx$/,
+        loader: 'builtin:swc-loader',
+        exclude: [/[\\/]node_modules[\\/]/],
+        options: {
+          jsc: {
+            parser: {
+              syntax: 'typescript',
+              tsx: true,
+            },
+            transform: {
+              react: {
+                runtime: 'automatic',
+                development: !prod,
+                refresh: !prod,
+              },
+            },
+            externalHelpers: true,
+          },
+          env: {
+            targets: 'Chrome >= 48', // browser compatibility
+          },
+        },
+      },
     ],
   },
 };

file-loader / url-loader / raw-loader → 资源模块

Rspack 实现了 Webpack 5 的 资源模块，使用资源模块来替换 file-loader、url-loader 和 raw-loader，以获得更好的性能。

file-loader → asset/resource

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /\.(png|jpe?g|gif)$/i,
-        use: ["file-loader"],
-      },
+      {
+        test: /\.(png|jpe?g|gif)$/i,
+        type: "asset/resource",
+      },
     ],
   },
 };

url-loader → asset/inline

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /\.(png|jpe?g|gif)$/i,
-        use: ["url-loader"],
-      },
+      {
+        test: /\.(png|jpe?g|gif)$/i,
+        type: "asset/inline",
+      },
     ],
   },
 };

raw-loader → asset/source

rspack.config.js
module.exports = {
   module: {
     rules: [
-      {
-        test: /^BUILD_ID$/,
-        use: ["raw-loader",],
-      },
+      {
+        test: /^BUILD_ID$/,
+        type: "asset/source",
+      },
     ],
   },
 };