> For AI agents: the complete documentation index is available at https://rspack.rs/zh/llms.txt, the full documentation bundle is available at https://rspack.rs/zh/llms-full.txt.

# 迁移 webpack

Rspack 的配置是基于 webpack 的设计实现的，以此你能够非常轻松地将项目从 webpack 迁移至 Rspack。

文档主要针对使用 webpack 5 的项目，因为目前 Rspack 的配置是基于 webpack 5 的设计实现的。如果你的项目使用的不是 webpack 5，可以参考以下迁移指南：

- 对于使用 webpack 4 或更低版本的项目，可以参考 [webpack - 从 v4 升级到 v5](https://webpack.docschina.org/migrate/5/) 了解相关差异。
- 对于使用 [create-react-app](https://create-react-app.dev/) 或 [CRACO](https://craco.js.org/) 的项目，可以参考 [迁移 Create React App](https://rspack.rs/zh/guide/migration/cra.md)。
- 对于使用 [Vue CLI](https://cli.vuejs.org/zh/) 的项目，可以参考 [Rsbuild - 从 Vue CLI 迁移](https://rsbuild.rs/zh/guide/migration/vue-cli)。

## 检查 Node.js 版本

迁移前，请确保所有构建环境使用 Rspack 支持的 Node.js 版本。`@rspack/core@2` 要求 Node.js `^20.19.0 || >=22.12.0`。

请确保本地开发、CI 和部署构建环境使用一致的 Node.js 版本，并按需更新 `.nvmrc`、Volta 配置和构建镜像等版本设置。

## 安装 Rspack

在你的项目目录下安装 Rspack：


```sh [npm]
npm add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [yarn]
yarn add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [pnpm]
pnpm add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [bun]
bun add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [deno]
deno add npm:@rspack/core npm:@rspack/cli npm:@rspack/dev-server -D
```

其中 `@rspack/cli` 和 `@rspack/dev-server` 为可选依赖：

- 未使用 `webpack-cli` 时，不需要安装 `@rspack/cli`
- 未使用 `webpack-dev-server` 时，不需要安装 `@rspack/dev-server`
- `@rspack/core` 和 `@rspack/cli` 应使用相同版本。`@rspack/dev-server` 的版本可能不同，无需保持一致。

## 修改 package.json

更新构建脚本以使用 Rspack 代替 webpack，查看 [CLI](https://rspack.rs/zh/api/cli.md) 了解更多。

```diff title="package.json"
{
  "scripts": {
-   "dev": "webpack serve",
-   "build": "webpack build",
+   "dev": "rspack dev",
+   "build": "rspack build",
+   "preview": "rspack preview",
  }
}
```

## 移除不支持的 CLI 参数

Rspack CLI 不支持部分 webpack CLI 参数，例如 `--progress`、`--color`、`--bail` 和 `--output-pathinfo`。保留这些参数会在读取配置前报 `Unknown option`。

迁移时，应从构建命令中删除这些不支持的参数；如果仍需保留对应行为，请改用 Rspack 配置：

```diff title="package.json"
{
  "scripts": {
-   "build": "webpack --mode production --progress --color",
+   "build": "rspack --mode production",
  }
}
```

```js title="rspack.config.mjs"
export default {
  stats: {
    // 对应 webpack CLI 的 --color
    colors: true,
  },
};
```

## 修改配置

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

:::tip 提示
Rspack 命令与 webpack 命令相同，均可通过 `-c` 或 `--config` 指定配置文件。但与 webpack 不同的是，如果你未显式指定配置文件，Rspack 默认使用 `rspack.config.js`。
:::

Rspack 兼容 webpack 的绝大部分配置项，查阅 [配置 Rspack](https://rspack.rs/zh/config/index.md) 来了解 Rspack 支持的所有配置。

## 缓存配置 \{#cache-configuration}

webpack 和 Rspack 的缓存配置结构并不完全相同。迁移时不建议直接复制 webpack 的 cache 配置，而应根据 Rspack 的 [cache 配置](https://rspack.rs/zh/config/cache.md) 做对应调整。

仅就 Cache 存储而言，禁用缓存和内存缓存的写法可以直接映射到 Rspack：`cache: false`、
`cache: true` 和 `cache: { type: 'memory' }`。

如果 webpack 使用文件系统缓存，应迁移为 Rspack [持久化缓存](https://rspack.rs/zh/config/cache.md#%E6%8C%81%E4%B9%85%E5%8C%96%E7%BC%93%E5%AD%98)，并按下面的字段映射进行调整。

webpack 的 `cache.cacheUnaffected` 优化在概念上对应 Rspack 顶层的
[`incremental`](https://rspack.rs/zh/config/incremental.md) 选项。Rspack 中该选项与 Cache 相互独立，因此
`cache: false` 不会禁用 Incremental。如需同时阻止两种机制复用跨 compilation 状态，还需要设置
`incremental: false`。由于 Rspack Incremental 覆盖更多 compilation 阶段，并且有独立的默认值，
迁移时应单独评估该选项，而不是把它当作 Cache 字段重命名。

1. 将 webpack 的 `cache.type: 'filesystem'` 改为 Rspack 的 `cache.type: 'persistent'`。

```diff title="rspack.config.mjs"
export default {
- cache: {
-   type: 'filesystem',
- },
+ cache: {
+   type: 'persistent',
+ },
};
```

2. 将 webpack 的 `cache.buildDependencies` 展平为 Rspack [`cache.buildDependencies`](https://rspack.rs/zh/config/cache.md#builddependencies) 所需的文件路径数组。

```diff title="rspack.config.mjs"
export default {
- cache: {
-   buildDependencies: {
-     config: [__filename, path.join(__dirname, 'package.json')],
-     ts: [path.join(__dirname, 'tsconfig.json')]
-   }
- },
+ cache: {
+   type: 'persistent',
+   buildDependencies: [
+     __filename,
+     path.join(import.meta.dirname, 'package.json'),
+     path.join(import.meta.dirname, 'tsconfig.json')
+   ]
+ },
};
```

3. webpack 的 [`cache.name`](https://rspack.rs/zh/config/cache.md#name) 和 [`cache.version`](https://rspack.rs/zh/config/cache.md#version) 可以保持不变。Rspack 使用相同的 `cache.name` 语义创建可同时存在的缓存。

4. 将 webpack 顶层的 `snapshot` 配置移动到 Rspack [`cache.snapshot`](https://rspack.rs/zh/config/cache.md#snapshot)。

```diff title="rspack.config.mjs"
export default {
- snapshot: {
-   immutablePaths: [path.join(__dirname, 'constant')],
-   managedPaths: [path.join(__dirname, 'node_modules')],
-   unmanagedPaths: []
- },
+ cache: {
+   type: 'persistent',
+   snapshot: {
+     immutablePaths: [path.join(import.meta.dirname, 'constant')],
+     managedPaths: [path.join(import.meta.dirname, 'node_modules')],
+     unmanagedPaths: []
+   }
+ },
};
```

5. 将 webpack 的 `cache.cacheDirectory` 移动到 Rspack [`cache.storage.directory`](https://rspack.rs/zh/config/cache.md#storagedirectory)，并将 webpack 的 `cache.cacheLocation` 移动到 Rspack [`cache.storage.location`](https://rspack.rs/zh/config/cache.md#storagelocation)。它们的配置名称不同，但语义一致。Rspack 同样会将 `storage.location` 默认设置为 `storage.directory/cache.name`。

```diff title="rspack.config.mjs"
export default {
- cache: {
-   type: 'filesystem',
-   cacheDirectory: path.join(__dirname, 'node_modules/.cache/test'),
-   cacheLocation: path.join(__dirname, 'node_modules/.cache/test/client')
- },
+ cache: {
+   type: 'persistent',
+   storage: {
+     type: 'filesystem',
+     directory: path.join(import.meta.dirname, 'node_modules/.cache/test'),
+     location: path.join(import.meta.dirname, 'node_modules/.cache/test/client')
+   }
+ },
};
```

下面的示例自动转换 Cache 存储配置；Incremental 应作为独立的迁移决策处理。

```js
function transform(webpackConfig, rspackConfig) {
  if (webpackConfig.cache === undefined) {
    webpackConfig.cache = webpackConfig.mode === 'development';
  }

  if (!webpackConfig.cache) {
    rspackConfig.cache = false;
    return;
  }

  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
    rspackConfig.cache = true;
    return;
  }

  rspackConfig.cache = { type: 'persistent' };

  rspackConfig.cache.buildDependencies = Object.values(
    webpackConfig.cache.buildDependencies || {},
  ).flat();

  rspackConfig.cache.name = webpackConfig.cache.name;
  rspackConfig.cache.version = webpackConfig.cache.version;

  rspackConfig.cache.snapshot = {
    immutablePaths: webpackConfig.snapshot?.immutablePaths,
    managedPaths: webpackConfig.snapshot?.managedPaths,
    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
  };

  rspackConfig.cache.storage = {
    type: 'filesystem',
    directory: webpackConfig.cache.cacheDirectory,
    location: webpackConfig.cache.cacheLocation,
  };
}
```

## webpack 内置插件

Rspack 实现了大部分 webpack 内置插件，其命名和参数配置与 webpack 保持一致，你可以非常轻松地替换它们。

例如替换 [DefinePlugin](https://rspack.rs/zh/plugins/define-plugin.md)：

```js title="rspack.config.js"
const webpack = require('webpack'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

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

查看 [webpack 内置插件兼容性](https://rspack.rs/zh/plugins/webpack-built-in-plugin-support.md)，了解 Rspack 对 webpack 内置插件和部分内部插件的兼容状态。

## 社区插件

Rspack 支持大部分 webpack 社区插件，并为暂不支持的插件提供了替代方案。

查看[社区插件兼容性](https://rspack.rs/zh/plugins/community-plugin-compatibility.md)，了解 Rspack 对 webpack 常见社区插件的兼容情况。

部分 webpack 生态包需要升级到较新版本才能兼容 Rspack，例如 [`webpack-node-externals`](https://www.npmjs.com/package/webpack-node-externals) 和 [`node-polyfill-webpack-plugin`](https://www.npmjs.com/package/node-polyfill-webpack-plugin)。复用社区包前，建议升级到最新版本，因为旧版本可能依赖不兼容的 webpack API。

### html-webpack-plugin

大多数项目从 [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin) 迁移时，建议使用 [`html-rspack-plugin`](https://github.com/rstackjs/html-rspack-plugin)。它是面向 Rspack 的 JavaScript fork，能够更好地兼容已有的选项、模板和集成。


```sh [npm]
npm add html-rspack-plugin -D
```

```sh [yarn]
yarn add html-rspack-plugin -D
```

```sh [pnpm]
pnpm add html-rspack-plugin -D
```

```sh [bun]
bun add html-rspack-plugin -D
```

```sh [deno]
deno add npm:html-rspack-plugin -D
```

在 Rspack 配置中更新导入和构造函数名称：

```diff title="rspack.config.mjs"
-import HtmlWebpackPlugin from 'html-webpack-plugin';
+import HtmlRspackPlugin from 'html-rspack-plugin';

 export default {
   plugins: [
-    new HtmlWebpackPlugin({
+    new HtmlRspackPlugin({
       // ...
     }),
   ],
 };
```

完成迁移后，从项目依赖中移除 `html-webpack-plugin`。

如果更关注构建性能，也可以选择内置的 Rust 插件 [`rspack.HtmlRspackPlugin`](https://rspack.rs/zh/plugins/html-rspack-plugin.md)。详情请参阅 [HTML 指南](https://rspack.rs/zh/guide/languages/html.md#%E9%80%89%E6%8B%A9%E6%8F%92%E4%BB%B6)。

### unplugin

部分 [unplugin](https://rspack.rs/zh/guide/features/plugin.md#unplugin) 包会为不同构建工具提供独立入口。如果提供了 `/rspack` 入口，请使用它代替 `/webpack`，以选择 Rspack 适配层：

```diff title="rspack.config.mjs"
- import AutoImport from 'unplugin-auto-import/webpack';
- import Components from 'unplugin-vue-components/webpack';
+ import AutoImport from 'unplugin-auto-import/rspack';
+ import Components from 'unplugin-vue-components/rspack';
```

### copy-webpack-plugin

使用 [rspack.CopyRspackPlugin](https://rspack.rs/zh/plugins/copy-rspack-plugin.md) 代替 [copy-webpack-plugin](https://github.com/webpack/copy-webpack-plugin)：

```js title="rspack.config.js"
const CopyWebpackPlugin = require('copy-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

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

### mini-css-extract-plugin

使用 [rspack.CssExtractRspackPlugin](https://rspack.rs/zh/plugins/css-extract-rspack-plugin.md) 代替 [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin)：

```diff title="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"
        ],
      }
    ]
  }
}
```

### tsconfig-paths-webpack-plugin

Rspack 不支持 webpack 的 `resolve.plugins` 选项。使用 [resolve.tsConfig](https://rspack.rs/zh/config/resolve.md#resolvetsconfig) 选项代替 [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin)：

```diff title="rspack.config.mjs"
-import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
+import path from 'node:path';

 export default {
  resolve: {
-    plugins: [new TsconfigPathsPlugin()],
+    tsConfig: path.resolve(import.meta.dirname, 'tsconfig.json'),
  },
};
```

### fork-ts-checker-webpack-plugin

使用 [ts-checker-rspack-plugin](https://github.com/rstackjs/ts-checker-rspack-plugin) 代替 [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin)：

```js title="rspack.config.js"
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin'); // [!code --]
const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin'); // [!code ++]

module.exports = {
  plugins: [
    new ForkTsCheckerWebpackPlugin(), // [!code --]
    new TsCheckerRspackPlugin(), // [!code ++]
  ],
};
```

### terser-webpack-plugin

对于使用 [terser-webpack-plugin](https://github.com/webpack/terser-webpack-plugin) 压缩 JavaScript 的项目，建议改用 [rspack.SwcJsMinimizerRspackPlugin](https://rspack.rs/zh/plugins/swc-js-minimizer-rspack-plugin.md) 以获得更好的构建性能：

```js title="rspack.config.js"
const TerserPlugin = require('terser-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  optimization: {
    minimizer: [
      new TerserPlugin(), // [!code --]
      new rspack.SwcJsMinimizerRspackPlugin(), // [!code ++]
      new rspack.LightningCssMinimizerRspackPlugin(),
    ],
  },
};
```

:::tip
当显式配置 [optimization.minimizer](https://rspack.rs/zh/config/optimization.md#optimizationminimizer) 时，Rspack 默认的压缩器会被禁用，因此建议同时保留 JavaScript 和 CSS 的压缩器。
:::

### css-minimizer-webpack-plugin

对于使用 [css-minimizer-webpack-plugin](https://github.com/webpack/css-minimizer-webpack-plugin) 压缩 CSS 的项目，建议改用 [rspack.LightningCssMinimizerRspackPlugin](https://rspack.rs/zh/plugins/lightning-css-minimizer-rspack-plugin.md) 以获得更好的构建性能：

```js title="rspack.config.js"
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin(),
      new CssMinimizerPlugin(), // [!code --]
      new rspack.LightningCssMinimizerRspackPlugin(), // [!code ++]
    ],
  },
};
```

## Loaders

Rspack 与绝大多数 webpack loader 保持兼容，因此通常可以直接复用现有的 loader 生态，无需额外改造。

不过，为了获得更优的构建性能与更稳定的行为，我们仍然建议按照下面的方式进行适当迁移：

### babel-loader

将 [babel-loader](https://github.com/babel/babel-loader) 迁移为 [builtin:swc-loader](https://rspack.rs/zh/guide/features/builtin-swc-loader.md)，以使用 Rspack 内置的 SWC 转换能力并获得更高性能。

如果你需要通过 babel 插件进行自定义转换逻辑，可以保留 `babel-loader`，但不建议对大量文件使用 `babel-loader`，因为这会导致显著的性能下降。

- 将 [@babel/preset-typescript](http://npmjs.com/package/@babel/preset-typescript) 替换为使用 `detectSyntax: 'auto'` 的 `builtin:swc-loader`：

```diff title="rspack.config.js"
module.exports = {
  module: {
    rules: [
      {
-        test: /\.(j|t)sx?$/,
+        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-           loader: 'babel-loader',
+           loader: 'builtin:swc-loader',
+           options: {
+             detectSyntax: 'auto',
+           },
          },
        ],
      },
    ],
  },
};
```

- 将 [@babel/preset-react](http://npmjs.com/package/@babel/preset-react) 替换为 SWC 的 `jsc.transform.react` 选项：

```diff title="rspack.config.js"
+const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-            loader: 'babel-loader',
+            loader: 'builtin:swc-loader',
            options: {
-              presets: ['@babel/preset-typescript', '@babel/preset-react'],
+              jsc: {
+                transform: {
+                  react: {
+                    runtime: 'automatic',
+                    development: isDev,
+                    refresh: isDev,
+                  },
+                },
+              },
+              detectSyntax: 'auto',
            },
          },
        ],
      },
    ],
  },
};
```

### swc-loader

将外置 [swc-loader](https://swc.rs/docs/usage/swc-loader) 迁移为 [builtin:swc-loader](https://rspack.rs/zh/guide/features/builtin-swc-loader.md) 时，除了 loader 名称改为 `builtin:swc-loader` 外，其余选项与原 `swc-loader` 完全一致。

```js title="rspack.config.js"
module.exports = {
  module: {
    rules: [
      {
        test: /\.(j|t)sx?$/,
        use: [
          {
            loader: 'swc-loader', // [!code --]
            loader: 'builtin:swc-loader', // [!code ++]
          },
        ],
      },
    ],
  },
};
```

### file-loader

将 [file-loader](https://github.com/webpack-contrib/file-loader) 迁移为 [资源模块](https://rspack.rs/zh/guide/features/asset-module.md) 的 `asset/resource` 类型。

```diff title="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

将 [url-loader](https://github.com/webpack-contrib/url-loader) 迁移为 [资源模块](https://rspack.rs/zh/guide/features/asset-module.md) 的 `asset/inline` 类型。

```diff title="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

将 [raw-loader](https://github.com/webpack-contrib/raw-loader) 迁移为 [资源模块](https://rspack.rs/zh/guide/features/asset-module.md) 的 `asset/source` 类型。

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

### vue-loader

对于 Vue 3 项目，请将 `vue-loader` 替换为 [`rspack-vue-loader`](https://rspack.rs/zh/guide/integrations/vue.md#vue-3)，并同步更新插件导入和 loader 名称：

```diff title="rspack.config.mjs"
-import { VueLoaderPlugin } from 'vue-loader';
+import { VueLoaderPlugin } from 'rspack-vue-loader';

export default {
  plugins: [new VueLoaderPlugin()],
  module: {
    rules: [
      {
        test: /\.vue$/,
-       loader: 'vue-loader',
+       loader: 'rspack-vue-loader',
+       options: {
+         experimentalInlineMatchResource: true,
+       },
      },
    ],
  },
};
```

## 常见 webpack 库替换

迁移 webpack 生态中的配套库时，下面这些非插件类包通常需要替换：

| webpack 库                | Rspack 替代方案                                                                   | 说明                   |
| ------------------------ | ----------------------------------------------------------------------------- | -------------------- |
| `webpack`                | [`@rspack/core`](https://www.npmjs.com/package/@rspack/core)                  | 核心包。                 |
| `webpack-cli`            | [`@rspack/cli`](https://www.npmjs.com/package/@rspack/cli)                    | Rspack CLI 命令。       |
| `webpack-dev-server`     | [`@rspack/dev-server`](https://github.com/rstackjs/rspack-dev-server)         | Rspack 开发服务器。        |
| `webpack-dev-middleware` | [`@rspack/dev-middleware`](https://github.com/rstackjs/rspack-dev-middleware) | 自定义 Node.js 服务中的中间件。 |
| `webpack-chain`          | [`rspack-chain`](https://github.com/rstackjs/rspack-chain)                    | 链式生成 Rspack 配置。      |
| `webpack-merge`          | [`rspack-merge`](https://github.com/rstackjs/rspack-merge)                    | 合并 Rspack 配置。        |

> 对于插件类包，请查看[社区插件兼容性](https://rspack.rs/zh/plugins/community-plugin-compatibility.md)。

## 移除 webpack 依赖

使用 Rspack 构建成功后，请检查 loader、插件或自定义构建脚本是否仍导入 `webpack` 或 `webpack/lib/*`。

如果仍存在相关导入，请暂时保留 `webpack` 作为兼容依赖。替换相关依赖或确认不再需要后，再移除 webpack 相关依赖：


```sh [npm]
npm remove webpack webpack-cli webpack-dev-server
```

```sh [yarn]
yarn remove webpack webpack-cli webpack-dev-server
```

```sh [pnpm]
pnpm remove webpack webpack-cli webpack-dev-server
```

```sh [bun]
bun remove webpack webpack-cli webpack-dev-server
```

```sh [deno]
deno remove npm:webpack npm:webpack-cli npm:webpack-dev-server
```