Webpack迁移Rspack速攻实战教程（前瞻版）

前言

rspack 即将开源，但社区中不乏有已经落地的 case ，比如 rspack-migration-showcase 、 modern.js 等。

基于此，本文将介绍如何迁移一个近似于 CRA（ create-react-app ） 的项目到 rspack 。

在阅读本文前，我们认为读者已经熟练掌握了 webpack 配置，本文将略过所有前置知识。

注：由于 rspack 处于 0.0.x 版本，可能会发生较大变化，故本文可能存在过时的部分，请仔细甄别。

正文

启动层

启动层分 实例实现 和 DevServer 实现，他们的区别是：

webpack

// webpack 实例
import webpack from 'webpack'
webpack()// webpack dev server
import WebpackDevServer from 'webpack-dev-server'
WebpackDevServer()

rspack

// rspack 实例
import * as rspack from '@rspack/core'
rspack.rspack()// rspack dev server
import * as rspackDevServer from '@rspack/dev-server'
rspackDevServer.RspackDevServer()// 🔴 不支持合成导入
// import rspack from 'rspack'
// import rspackDevServer from '@rspack/dev-server'

无论是 webpack 还是 rspack ，在启动层几乎一致，通过 实例实现 传入配置得到 compiler ，即可引导启动 DevServer 或进行构建，细节略：

// 获取 compiler
const instanceImpl = rspack.rspack // or `webpack`
const compilerImpl = instanceImpl(webpackConfig)// 获取 dev server
const devServerImpl = rspackDevServer.RspackDevServer // or `WebpackDevServer`
const devServer = devServerImpl(devServerConfig, compilerImpl)

可以看到两者无明显区别，需要注意的是使用 compiler 的后续 api 可能存在 rspack 未支持的情况。

配置层

配置类型

两者配置类型获取方式：

import type { Configuration as WebpackConfig } from 'webpack'
import type { Configuration as RspConfig } from '@rspack/core'

基本一致的配置项

这里指的是直接把 webpack 的配置原模原样拷贝给 rspack 也可以兼容的选项，经作者尝试，常用选项如下：

• mode
• entry
• context
• output
• devtool
• devServer
• target
• stats
• infrastructureLogging

有区别的配置项

webpack 的复杂配置需要进行一些调整才能给予 rspack 使用。

resolve

rspack 的 resolve 配置项要在 webpack 的基础上加一个 tsConfigPath ，表示当前项目 tsconfig.json 的路径：

  rspackConfig.resolve = {...webpackConfig.resolve,tsConfigPath: ...}

module - JavaScript 资源

rspack 的每个 rule 配置必须指明他的 type ，如：

  module: {rules: [{test: /\.tsx$/,// 🟢type: 'tsx'}]}

这和 webpack 中的 asset type 等相似，但 rspack 不光有自己独有的 type 类型（比如 tsx 、ts 等），也支持 asset type （见下文）。

目前常用的 type 有：

• ts / tsx
• js / jsx
• css / css/module

请各取所需。

module - CSS 资源

由于 webpack 的 css 配置过于繁琐，此处仅介绍重点：

1. 无需配置 style-loader 、css-loader ，在 rspack 我们用不到。

2. postcss-loader 需要替换成 @rspack/postcss-loader ，选项的区别是插件必须传递实例，如：

   // 获取 postcss optionsconst postcssOptions = {plugins: [require(require.resolve('postcss-flexbugs-fixes'))// ...]}
   

   在 webpack 的 postcss-loader 选项中，插件是可以传递路径的，如仅传递 require.resolve('postcss-flexbugs-fixes') ，但传递实例也可以，但 rspack 只能传递实例。

3. 别忘了设定 css / css/module 的 type 给对应规则。

4. sass-loader / less-loader 使用、配置方式不变。

module - Asset 静态资源

和 webpack 配置方式一致，可正常使用 asset type 注明静态资源：

  {test: /\.(png|jpe?g|gif|webp)(\?.*)?$/i,type: 'asset/resource'}

注意 svgr 需要额外设定 type: 'tsx' ，表示以 JavaScript 方式承接，否则将得到错误的静态资源，另外，由于 svgr 在内部使用 babel 转译组件，将花费较长时间，可 fork 后修改为 esbuild 转译加速，或一律将 .svg 作为静态资源输出。

plugins - 非内置能力

目前 rspack 对 webpack 插件 hooks api 支持较少，大部分插件无法使用，可用经典插件如下：

• clean-webpack-plugin
• webpack-bundle-analyzer

对于 html-webpack-plugin 的平替，有两个方式可选：

1. 使用 @rspack/plugin-html 替代：目的是用来支持其他需要调用 HtmlWebpackPlugin 的后续插件，如有些插件需要在 html 模板中进一步加工，若你有二次使用 HtmlWebpackPlugin 的插件，请采用此方案。

2. 使用内置能力 builtins.html ，详见下文。

在迁移过程中，作者发现的不可用插件如下：

• fork-ts-checker-webpack-plugin

明确了哪些经典插件可以直接使用，哪些不可以后，我们距离完整补全 webpack 插件相同的能力还差一些，这些能力已在 rspack 中内置（ builtins ），通过 builtins.xxx 方式配置。

plugins - 内置能力

builtins.define

// rspack configbuiltins: {define: {'process.env.SOME': JSON.stringify('value'),// ...}}

该能力可以平替 DefinePlugin 插件，传值方式一致。

builtins.copy

该能力可以平替 copy-webpack-plugin ，大部分选项与 webpack 一致，但不完整，不支持 globOptions ，这意味着无法忽略某些文件不被拷贝，从而我们无法做到将 index.html 模板文件放到静态资源目录。

比如我们预期拷贝 public/* 到产物目录，但 index.html 我们无法放到 public/index.html 里，因为不支持配置忽略就会造成多份相同资源 emit 冲突，解决方法是 html 模板只能放到项目根目录。

builtins.react

swc 的 react 开发时配置，如下配置即可：

  builtins: {react: {development: isDev,refresh: isDev,runtime: 'automatic'}}

builtins.bar

相当于 webpackbar 的替代，但打印容易错位，同时 rspack 非常快，没有必要展示进度条，不建议配置该选项。

builtins.html

内置的 html 能力，缺点是没有提供 HtmlWebpackPlugin 插件实例，无法和其他插件联动，同时配置项不够完整。

值得庆幸的是 lodash template 语法无论是 builtins.html 还是 @rspack/plugin-html 均支持，如 <%= htmlWebpackPlugin.options.title %> 。

若你需支持类似 CRA 的 %PUBLIC_URL% 变量替换，请使用 react-dev-utils/InterpolateHtmlPlugin 搭配 @rspack/plugin-html ，使用方式见 CRA eject 结果。

plugins - 其他

到这里，如果严格和 webpack 插件相比，我们还缺少一些，比如 MiniCssExtractPlugin 、ReactRefreshWebpackPlugin 、ProvidePlugin ，这些由 rspack 内置支持，我们无需配置。

当你需要更多功能时，请优先寻找平替，他可能是一个 builtins.xxx 内置能力，或是某个选项，或是某个 @rspack/plugin-xxx 包。

optimization

对于 optimization.minimize 两者一致。

对于 optimization.minimizer ，我们无需外部提供压缩能力，已经内置。

对于 optimization.splitChunks ，目前支持的分包选项不够全面，不支持调用函数（如 name() 、test() 等），此处推荐手动使用 webpack 拆包语法分包（ () => import() ）；可以尝试配置非函数选项，但是否生效未知。

cache

虽然 rspack 有 cache 选项，但截止本文发稿时，只能配置 true / false ，并未发现有缓存出现。

由于截止本文发稿时，rspack 暂未开源文档未释出，请后续自行探索。

其他

经作者探索，将某个 JavaScript 对象传递至 webpack 构建流程中，是可以通过引用的方式双向同步数据的，但在 rspack 不可以，推测这与 Rust 不支持有关。

总结

本文介绍了 webpack 迁移至 rspack 的基本流程和相关探索，至此，已经完成了 CRA 所有基本能力的平替，代码详见 xn-sakina / xn 。

在作者尝试开发过程中，热更新仍存在丢失样式等问题，经刷新页面后恢复，请酌情采用（如开发时 rspack 构建时 webpack）。

关于更多 rspack 能力，请自行探索开源后的文档的选项。

以上。