作为前端开发者，想必大家都被 Webpack 缓慢的构建速度、繁琐的配置折磨过。尤其是项目体积变大后，冷启动等待几十秒、热更新卡顿，直接拉低开发效率。而基于 Rust 开发的 Rspack，凭借极致的构建速度、近乎零成本的 Webpack 迁移成本，成为了当下前端构建工具的热门选择。
这篇文章就带大家从零搭建一个 Rspack + React 实战项目，从项目初始化、核心配置、资源处理，到生产优化全覆盖，手把手带你上手这款高性能构建工具，全文干货，建议收藏跟着实操。
一、先搞懂：Rspack 到底强在哪？
在开始实战前，先简单梳理 Rspack 的核心优势，方便大家理解为什么要选用它：
- 极致性能：底层由 Rust 编写，支持多线程并行编译，构建速度比 Webpack 快 5-10 倍，大型项目二次构建几乎秒开，热更新体验拉满；
- 生态兼容：完美兼容 Webpack 配置语法、Loader 和 Plugin，现有 Webpack 项目可低成本迁移，不用重头学习新配置；
- 开箱即用：内置 SWC 编译、CSS 解析、资源处理、代码分割等能力，零配置也能启动基础项目，大幅简化配置流程；
- 工程化完善：内置 Tree Shaking、热更新、产物优化等功能，原生支持 React、Vue、TypeScript 等主流框架，适配现代前端开发。
相比于 Vite，Rspack 在开发环境和生产环境构建逻辑更统一，没有开发与生产的构建差异问题，更适合中大型企业级项目。接下来我们直接进入实战环节。
二、环境准备
Rspack 对运行环境有一定要求，提前配置好避免踩坑：
- Node.js 版本 ≥ 18.12.0（推荐 LTS 版本，过低版本会导致依赖安装失败）
- 包管理器：npm / yarn / pnpm 均可（本文使用 pnpm 演示）
- 基础前端开发知识，熟悉 React 与构建工具基本用法
三、项目初始化：两种快速上手方式
方式1：脚手架一键创建（推荐新手）
Rspack 官方提供了一键初始化脚手架，不用手动写基础配置，适合快速上手：
# 执行初始化命令
pnpm create rspack@latest
# 按照终端提示操作
# 1. 输入项目名称
# 2. 选择框架：React
# 3. 选择语言：JavaScript / TypeScript
# 4. 等待依赖安装完成
方式2：手动搭建（理解核心配置）
想深入理解 Rspack 配置逻辑，建议跟着手动搭建，步骤如下：
1. 创建项目目录并初始化
# 创建目录并进入
mkdir rspack-react-demo && cd rspack-react-demo
# 初始化 package.json
pnpm init -y
2. 安装核心依赖
# 安装 Rspack 核心依赖
pnpm add @rspack/core @rspack/cli -D
# 安装 React 相关依赖
pnpm add react react-dom
# 安装 HTML 插件（替代 webpack 的 html-webpack-plugin）
pnpm add @rspack/plugin-html -D
3. 搭建基础项目结构
按照前端工程化规范，搭建如下目录，结构清晰便于后续维护：
rspack-react-demo
├── public/ # 静态资源
│ └── index.html # HTML 模板
├── src/ # 源码目录
│ ├── App.jsx # 根组件
│ └── main.jsx # 项目入口
├── rspack.config.js # Rspack 核心配置文件
└── package.json
四、核心文件编写
1. HTML 模板（public/index.html）
这是项目的页面载体，预留 React 挂载节点：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Rspack React Demo</title>
</head>
<body>
<div id="root"></div>
</body>
</html>
2. React 入口文件（src/main.jsx）
项目入口，负责渲染根组件：
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(
<React.StrictMode>
<App />
</React.StrictMode>
)
3. 根组件（src/App.jsx）
编写基础页面内容，测试项目运行状态：
function App() {
return (
<div style={{ textAlign: 'center', marginTop: '50px' }}>
<h1>Hello Rspack 🚀</h1>
<p>基于 Rspack 搭建的 React 项目</p>
</div>
)
}
export default App
五、Rspack 核心配置详解
这是项目的核心部分，新建rspack.config.js，配置入口、出口、loader、插件、开发服务等，每一项都配有注释，新手也能看懂：
const path = require('path')
const HtmlRspackPlugin = require('@rspack/plugin-html')
// Rspack 配置
module.exports = {
// 开发模式，生产环境改为 production
mode: 'development',
// 项目入口
entry: './src/main.jsx',
// 打包出口配置
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'js/[name].[hash:8].js',
// 每次打包清空 dist 目录
clean: true
},
// 模块解析规则
resolve: {
// 自动补全文件后缀
extensions: ['.jsx', '.js', '.json']
},
// 模块处理规则
module: {
rules: [
// 处理 JSX/JS，内置 SWC 编译，比 Babel 更快
{
test: /.jsx?$/,
exclude: /node_modules/,
loader: 'builtin:swc-loader',
options: {
jsc: {
parser: {
syntax: 'ecmascript',
jsx: true
},
transform: {
react: {
runtime: 'automatic'
}
}
}
}
},
// 处理 CSS
{
test: /.css$/,
use: ['style-loader', 'css-loader']
},
// 处理图片、字体等静态资源
{
test: /.(png|jpe?g|svg|gif|woff|woff2|eot|ttf)$/i,
type: 'asset/resource',
generator: {
filename: 'assets/[hash:8][ext]'
}
}
]
},
// 插件配置
plugins: [
// 生成 HTML 文件
new HtmlRspackPlugin({
template: './public/index.html',
favicon: './public/favicon.ico'
})
],
// 开发服务器配置
devServer: {
port: 3000,
// 自动打开浏览器
open: true,
// 开启热更新
hot: true,
// 监听文件变化
liveReload: true
}
}
六、配置启动脚本，运行项目
打开 package.json，在 scripts 中添加启动和打包命令：
"scripts": {
"dev": "rspack serve",
"build": "rspack build --mode production"
}
配置完成后，执行启动命令，即可运行项目：
pnpm dev
项目启动后会自动打开浏览器，默认端口 3000，能正常看到页面就说明基础搭建成功。此时修改代码，会发现热更新速度极快，完全没有卡顿感。
七、生产环境优化（进阶必备）
基础项目跑通后，生产环境需要做优化，减小产物体积、提升加载速度，常用优化配置如下：
1. 提取 CSS 为单独文件
开发环境用 style-loader 即可，生产环境建议提取 CSS，避免样式阻塞渲染：
# 安装依赖
pnpm add @rspack/plugin-mini-css -D
在配置文件中引入并替换 CSS 处理规则：
const MiniCssExtractPlugin = require('@rspack/plugin-mini-css')
// 替换 module.rules 中的 CSS 规则
{
test: /.css$/,
use: [MiniCssExtractPlugin.loader, 'css-loader']
}
// 插件新增
new MiniCssExtractPlugin({
filename: 'css/[name].[hash:8].css'
})
2. 代码分割，抽离公共依赖
将 React、ReactDOM 等第三方依赖单独打包，避免重复打包，提升缓存利用率：
// 优化配置
optimization: {
// 代码分割
splitChunks: {
chunks: 'all',
cacheGroups: {
vendor: {
name: 'vendor',
test: /node_modules/,
priority: -10
}
}
},
// 生成运行时文件
runtimeChunk: 'single'
}
3. 关闭 SourceMap（生产环境）
生产环境关闭 SourceMap，减小打包体积，避免源码泄露：
module.exports = {
// ...其他配置
devtool: false
}
八、项目打包与部署
执行打包命令，即可生成生产环境代码：
pnpm build
打包完成后，项目根目录会生成 dist 文件夹，里面就是可直接部署的静态资源，上传到服务器或者静态托管平台即可。
九、Rspack 踩坑小贴士
- 部分 Webpack 小众插件不兼容，优先选用 Rspack 官方适配插件；
- Node 版本过低会导致启动失败，务必升级到 18.12.0 以上；
- 热更新失效时，检查 devServer.hot 是否开启，以及文件路径是否正确；
- 打包报错优先查看终端日志，大多是路径或 loader 配置问题。
十、总结
通过本篇实战，我们从零完成了 Rspack + React 项目的搭建、配置、优化全流程，能直观感受到 Rspack 远超 Webpack 的构建速度，同时配置逻辑简洁易懂，Webpack 用户可以无缝切换。
对于中小型项目，Rspack 零配置就能满足需求；对于中大型项目，Rspack 的性能优势和工程化能力能大幅提升开发与构建效率。后续大家还可以在此基础上，接入 TypeScript、TailwindCSS、路由等功能，完善项目生态。
相比于传统构建工具，Rspack 真正做到了性能与易用性兼顾，还没上手的同学，赶紧跟着教程实操一遍，彻底告别打包等待的煎熬！
原创不易，觉得有用的话欢迎点赞、收藏、关注，后续会持续更新 Rspack 进阶优化、Vue 适配等干货内容～
