不eject如何给CRA项目添加Webpack插件:rescripts注入式配置实战指南
不eject如何给CRA项目添加Webpack插件:rescripts注入式配置实战指南
🚀 还在为 CRA(create-react-app)项目无法自定义 Webpack 配置而纠结吗?rescripts 让你无需 eject、无需维护 react-scripts 分支,就能通过"注入式 rescript"给 Webpack 添加插件、修改配置,同时保留升级到最新 react-scripts 的能力。本文带你从安装到实战,快速掌握这套 CRA 自定义配置方案。
一、为什么需要 rescripts?eject 真的那么香吗?
CRA 的 eject 脚本虽然能开放全部配置,但代价也很明显:
- ⚠️ 不可逆:一旦 eject,就再也无法平滑升级到新版 react-scripts
- ⚠️ 暴露繁琐代码:大量 webpack 配置文件直接摊在你面前
- ⚠️ 维护成本高:版本迭代后所有自定义都要手工合并
rescripts 的思路是:用一个轻量 CLI 包拦截 CRA 的 start / build / test 流程,在 react-scripts 加载 Webpack 配置之前,把一串"rescript"转换函数依次应用到配置上(核心逻辑见 patch.js 和 loader.js)。配置改完了,CRA 本体一行代码都不用动。
简单说:rescripts = 官方配置的"中间件",改完即走,项目可随时升级。
二、三步完成接入:rescripts 快速安装与基础配置
第 1 步:安装 CLI
npm i -D @rescripts/cli
第 2 步:替换 package.json 中的 scripts
把 react-scripts 换成 rescripts:
{
"scripts": {
"start": "rescripts start",
"build": "rescripts build",
"test": "rescripts test"
}
}
💡 可以直接删掉
eject脚本,你已经不需要它了。
第 3 步:声明根 rescript
在 package.json 里加一个 rescripts 字段,或者在项目根目录创建 .rescriptsrc(支持 .js / .json 等任意写法)。加载优先级在 loader.js 中定义:package.json 字段 → 根目录 .rescriptsrc 文件 → 命令行 --config 参数。
"rescripts": [
"./my-webpack-rescript"
]
至此,rescripts start 运行时就会按顺序应用你声明的所有 rescript。
三、核心实战:给 CRA 注入 Webpack 插件
这是 rescripts 最高频的用法——往 Webpack 的 plugins 数组里加插件。官方示例 editing-webpack-plugins 展示了完整套路。
方法 1:使用 @rescripts/utilities 工具函数(推荐)
@rescripts/cli 自带 @rescripts/utilities,提供了全套插件操作 API,源码位于 plugins.js:
| 工具函数 | 作用 |
|---|---|
getWebpackPlugin |
按构造器名查找插件实例 |
prependWebpackPlugin |
把新插件插到 plugins 数组最前面 |
appendWebpackPlugin |
把新插件追加到 plugins 数组末尾 |
editWebpackPlugin |
修改指定插件的选项 |
replaceWebpackPlugin |
用新插件替换指定插件 |
removeWebpackPlugin |
移除指定插件 |
以追加 webpack-build-notifier 插件为例,创建 .rescriptsrc:
const {appendWebpackPlugin} = require('@rescripts/utilities')
const WebpackBuildNotifierPlugin = require('webpack-build-notifier')
module.exports = appendWebpackPlugin(
new WebpackBuildNotifierPlugin({title: 'My App'}),
)
一个 rescript 本质上就是"接收 Webpack 配置、返回新配置"的函数,所以多个操作可以串起来:
const {appendWebpackPlugin, editWebpackPlugin, removeWebpackPlugin} =
require('@rescripts/utilities')
module.exports = config => {
let c = appendWebpackPlugin(new WebpackBuildNotifierPlugin({}), config)
c = editWebpackPlugin(p => (p.someOption = 'changed') || p, 'DefinePlugin', c)
return removeWebpackPlugin('IgnorePlugin', c)
}
方法 2:直接操作 config 对象
如果你熟悉 Webpack,也可以手写:
module.exports = config => {
config.plugins.push(new MyPlugin({options: 1}))
return config
}
简单粗暴,但插件多了容易和别的 rescript 打架,建议优先用 utilities 的函数式 API(所有方法都是柯里化的,写法可以进一步精简)。
四、进阶玩法:复用社区 rewire 与中间件
兼容 react-app-rewired 生态
react-app-rewired 的 rewire 可以无缝跑在 rescripts 里,通过官方 rescript use-rewire 接入(文档:use-rewire/README.md):
"rescripts": [
["use-rewire", "react-app-rewire-compression-plugin", {"cache": true}]
]
数组第一项是 rescript 名,后面的元素就是透传给它的参数——这就是 rescripts 的"参数化"机制,由 loader.js 中的 loadCreatorAndApplyArgs 完成展开。
middleware:追踪配置如何被逐层修改
给 rescript 函数加上 isMiddleware = true 标记,它会在每一个 rescript 执行前后都运行一次(分发逻辑见 patch.js),非常适合调试:
const logConfig = config => {
console.log(JSON.stringify(config.plugins.map(p => p.constructor.name)))
return config
}
logConfig.isMiddleware = true
五、常见问题与排错 ⚡
- 报 "haven't defined a root rescript":你没配置
rescripts字段或.rescriptsrc文件,见 loader.js 中的错误提示。 - 报 "No plugin with constructor name XXX was found":
editWebpackPlugin等按构造器函数名精确匹配插件,请核对plugins里实际的类名。 - 插件顺序很重要吗? 重要。
prepend/append的插入位置可能影响某些插件的执行时机,按需选择。 - 能同时改 devServer 和 jest 吗? 可以。rescript 除了纯函数形式,还支持导出
{webpack, devServer, jest}对象,分别对三种流程做转换(rescript 结构说明见 README.md)。
六、写在最后
rescripts 用"函数管道"的方式解决了 CRA 自定义配置的痛点:不 eject、可升级、可组合。核心要点回顾:
npm i -D @rescripts/cli,scripts 里的react-scripts换成rescripts- 在
package.json的rescripts字段或根目录.rescriptsrc中声明配置 - 用
@rescripts/utilities的appendWebpackPlugin/editWebpackPlugin等函数优雅地增删改 Webpack 插件
更多内置 rescript(Babel、ESLint、TSLint、Stylelint 等)可以在 packages/rescripts/ 下浏览,完整文档参考 README.md。现在,去给你的 CRA 项目加上那个"一直想要"的 Webpack 插件吧!🎯
