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: {}
  }
}

Loaders

Rspack 的 loader 執行器與 webpack 的 loader 功能完全相容，支援大多數 webpack loaders。您可以直接使用現有的 loaders，無需任何變更。但是，為了達到最佳效能，請考慮遷移以下 loaders

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",
+      },
     ],
   },
 };