Tools
本章节描述了 Rsbuild 中与底层工具有关的配置。
tools.autoprefixer
- 类型:
Object | Function
- 默认值:
{
flexbox: 'no-2009',
// browserslist 取决于项目中的 browserslist 配置
// 以及 `output.overrideBrowserslist`(优先级更高) 配置
overrideBrowserslist: browserslist,
}
通过 tools.autoprefixer
可以修改 autoprefixer 的配置。
Object 类型
当 tools.autoprefixer
的值为 Object
类型时,会与默认配置通过 Object.assign 合并。比如:
export default {
tools: {
autoprefixer: {
flexbox: 'no-2009',
},
},
};
Function 类型
当 tools.autoprefixer
为 Function 类型时,默认配置作为第一个参数传入,可以直接修改配置对象,也可以返回一个值作为最终结果。比如:
export default {
tools: {
autoprefixer(config) {
// 修改 flexbox 的配置
config.flexbox = 'no-2009';
},
},
};
tools.bundlerChain
- 类型:
Function | undefined
- 默认值:
undefined
你可以通过 tools.bundlerChain
来修改默认的 webpack 和 Rspack 配置,它的值为 Function
类型,接收两个参数:
- 第一个参数为
bundler-chain
对象实例,你可以通过这个实例来修改 webpack 和 Rspack 的配置。
- 第二个参数为一个工具集合,包括
env
、isProd
、CHAIN_ID
等。
什么是 BundlerChain
Bundler chain 是 webpack chain 的子集,其中包含一部分 webpack chain API,你可以用它来同时修改 webpack 和 Rspack 的配置。
通过 bundler chain 修改的配置,在 webpack 和 Rspack 构建时均可生效。需要注意的是,bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如,修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同),或添加一个Rspack 兼容的 webpack 插件。
tools.bundlerChain
的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack,因此会被其他几个配置中的修改所覆盖。
工具集合
env
- 类型:
'development' | 'production' | 'test'
通过 env 参数可以判断当前环境为 development、production 还是 test。比如:
export default {
tools: {
bundlerChain: (chain, { env }) => {
if (env === 'development') {
chain.devtool('cheap-module-eval-source-map');
}
},
},
};
isProd
通过 isProd 参数可以判断当前环境是否为 production。比如:
export default {
tools: {
bundlerChain: (chain, { isProd }) => {
if (isProd) {
chain.devtool('source-map');
}
},
},
};
target
- 类型:
'web' | 'node' | 'web-worker'
通过 target 参数可以判断当前构建的目标运行时环境。比如:
export default {
tools: {
bundlerChain: (chain, { target }) => {
if (target === 'node') {
// ...
}
},
},
};
isServer
判断当前构建的目标运行时环境是否为 node
,等价于 target === 'node'
。
export default {
tools: {
bundlerChain: (chain, { isServer }) => {
if (isServer) {
// ...
}
},
},
};
isWebWorker
判断当前构建的目标运行时环境是否为 web-worker
,等价于 target === 'web-worker'
。
export default {
tools: {
bundlerChain: (chain, { isWebWorker }) => {
if (isWebWorker) {
// ...
}
},
},
};
HtmlPlugin
- 类型:
typeof import('html-webpack-plugin')
通过这个参数你可以拿到 html-webpack-plugin
插件的实例。
export default {
tools: {
bundlerChain: (chain, { HtmlPlugin }) => {
console.log(HtmlPlugin);
},
},
};
CHAIN_ID
Rsbuild 中预先定义了一些常用的 Chain ID,你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
TIP
请留意,下列的一部分 Rule 或 Plugin 并不是默认存在的,当你开启特定配置项、或是注册某些插件后,它们才会被包含在 Rspack 或 webpack 配置中。
比如,RULE.STYLUS
仅在注册了 Stylus 插件后才会存在。
CHAIN_ID.RULE
ID |
描述 |
RULE.MJS |
处理 mjs 的规则 |
RULE.CSS |
处理 css 的规则 |
RULE.LESS |
处理 less 的规则 |
RULE.SASS |
处理 sass 的规则 |
RULE.STYLUS |
处理 stylus 的规则 |
RULE.TOML |
处理 toml 的规则 |
RULE.YAML |
处理 yaml 的规则 |
RULE.WASM |
处理 wasm 的规则 |
RULE.NODE |
处理 node 的规则 |
CHAIN_ID.ONE_OF
通过 ONE_OF.XXX
可以匹配到规则数组中的某一类规则。
ID |
描述 |
ONE_OF.SVG |
处理 SVG 的规则,在 data URI 和单独文件之间自动选择 |
ONE_OF.SVG_URL |
处理 SVG 的规则,输出为单独文件 |
ONE_OF.SVG_INLINE |
处理 SVG 的规则,作为 data URI 内联到 bundle 中 |
ONE_OF.SVG_ASSETS |
处理 SVG 的规则,在 data URI 和单独文件之间自动选择 |
CHAIN_ID.USE
通过 USE.XXX
可以匹配到对应的 loader。
ID |
描述 |
USE.LESS |
对应 less-loader |
USE.SASS |
对应 sass-loader |
USE.STYLUS |
对应 stylus-loader |
USE.VUE |
对应 vue-loader |
USE.TOML |
对应 toml-loader |
USE.YAML |
对应 yaml-loader |
USE.NODE |
对应 node-loader |
USE.SVGR |
对应 @svgr/webpack |
USE.POSTCSS |
对应 postcss-loader |
USE.RESOLVE_URL_LOADER_FOR_SASS |
对应 resolve-url-loader |
CHAIN_ID.PLUGIN
通过 PLUGIN.XXX
可以匹配到对应的 plugin。
ID |
描述 |
PLUGIN.HTML |
对应 HtmlPlugin ,使用时需要拼接 entry 名称:${PLUGIN.HTML}-${entryName} |
PLUGIN.APP_ICON |
对应 AppIconPlugin |
PLUGIN.INLINE_HTML |
对应 InlineChunkHtmlPlugin |
PLUGIN.BUNDLE_ANALYZER |
对应 WebpackBundleAnalyzer |
PLUGIN.ASSETS_RETRY |
对应 Rsbuild 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin |
PLUGIN.VUE_LOADER_PLUGIN |
对应 VueLoaderPlugin |
PLUGIN.AUTO_SET_ROOT_SIZE |
对应 Rsbuild 中的自动设置根字体大小插件 AutoSetRootSizePlugin |
CHAIN_ID.MINIMIZER
通过 MINIMIZER.XXX
可以匹配到对应的压缩工具。
ID |
描述 |
MINIMIZER.JS |
对应 TerserWebpackPlugin 或 SwcJsMinimizerRspackPlugin |
MINIMIZER.CSS |
对应 CssMinimizerWebpackPlugin |
使用示例
使用示例可参考:WebpackChain 使用示例。
tools.cssLoader
- 类型:
Object | Function
- 默认值:
undefined
通过 tools.cssLoader
可以修改 css-loader 的配置项。默认配置如下:
{
modules: {
auto: true,
exportLocalsConvention: 'camelCase',
localIdentName: config.output.cssModules.localIdentName,
// isServer 表示 node (SSR) 构建
// isWebWorker 表示 web worker 构建
exportOnlyLocals: isServer || isWebWorker,
},
// 默认在开发环境下启用 CSS 的 Source Map
sourceMap: isDev,
// importLoaders 在编译 css 文件时为 `1`,在编译 sass/less 文件时为 `2`
importLoaders: 1 || 2,
}
Object 类型
当此值为 Object 类型时,会与默认配置进行深层合并 (deep merge)。比如:
export default {
tools: {
cssLoader: {
modules: {
exportOnlyLocals: true,
},
},
},
};
Function 类型
当此值为 Function 类型时,默认配置作为第一个参数传入,你可以直接修改配置对象,也可以返回一个对象作为最终配置。比如:
export default {
tools: {
cssLoader: (config) => {
config.modules.exportOnlyLocals = true;
return config;
},
},
};
tools.htmlPlugin
- 类型:
false | Object | Function
- 默认值:
const defaultHtmlPluginOptions = {
inject, // 对应 html.inject 配置项
favicon, // 对应 html.favicon 配置项
filename, // 基于 output.distPath 和 entryName 生成
template, // 默认为内置的 HTML 模板路径
templateParameters, // 对应 html.templateParameters 配置项
chunks: [entryName],
minify: {
// 基于 output.disableMinimize 生成
removeComments: false,
useShortDoctype: true,
keepClosingSlash: true,
collapseWhitespace: true,
removeRedundantAttributes: true,
removeScriptTypeAttributes: true,
removeStyleLinkTypeAttributes: true,
removeEmptyAttributes: true,
minifyJS,
minifyCSS: true,
minifyURLs: true,
},
};
通过 tools.htmlPlugin
可以修改 html-webpack-plugin 的配置项。
Object 类型
当 tools.htmlPlugin
的值为 Object
类型时,会与默认配置通过 Object.assign
合并。
export default {
tools: {
htmlPlugin: {
scriptLoading: 'blocking',
},
},
};
Function 类型
当 tools.htmlPlugin
为 Function 类型时:
- 第一个参数是默认配置的对象,可以直接修改该对象。
- 第二个参数是也是一个对象,包含了 entry 的名称和 entry 的值。
- 函数可以 return 一个新的对象作为最终的配置。
export default {
tools: {
htmlPlugin(config, { entryName, entryValue }) {
if (entryName === 'main') {
config.scriptLoading = 'blocking';
}
},
},
};
Boolean 类型
将 tools.htmlPlugin
配置为 false
,可以禁用默认的 html-webpack-plugin
插件。
export default {
tools: {
htmlPlugin: false,
},
};
禁用 JS / CSS 压缩
默认情况下,Rsbuild 会在生产环境构建时压缩 HTML 内的 JavaScript / CSS 代码,从而提升页面性能。此能力通常在使用自定义模版或插入自定义脚本时会有帮助。然而,当开启 output.enableInlineScripts
或 output.enableInlineStyles
时,会出现对 inline JavaScript / CSS 代码重复压缩的情况,对构建性能会有一定影响。你可以通过修改 tools.htmlPlugin.minify
配置项来修改默认的压缩行为。
export default {
tools: {
htmlPlugin: (config) => {
if (typeof config.minify === 'object') {
config.minify.minifyJS = false;
config.minify.minifyCSS = false;
}
},
},
};
tools.less
- 类型:
Object | Function
- 默认值:
const defaultOptions = {
lessOptions: {
javascriptEnabled: true,
},
// 默认在开发环境下启用 CSS 的 Source Map
sourceMap: isDev,
};
你可以通过 tools.less
修改 less-loader 的配置。
Object 类型
当 tools.less
的值为 Object
类型时,会与默认配置通过 Object.assign 进行浅层合并,值得注意的是,lessOptions
会通过 deepMerge 进行深层合并。
export default {
tools: {
less: {
lessOptions: {
javascriptEnabled: false,
},
},
},
};
Function 类型
当 tools.less
为 Function 类型时,默认配置作为第一个参数传入,可以直接修改配置对象,也可以返回一个值作为最终结果,第二个参数提供了一些可以直接调用的工具函数:
export default {
tools: {
less(config) {
// 修改 lessOptions 配置
config.lessOptions = {
javascriptEnabled: false,
};
},
},
};
修改 Less 版本
在某些场景下,如果你需要使用特定的 Less 版本,而不是使用 Rsbuild 内置的 Less v4,可以在项目中安装需要使用的 Less 版本,并通过 less-loader
的 implementation
选项设置。
export default {
tools: {
less: {
implementation: require('less'),
},
},
};
工具函数
addExcludes
- 类型:
(excludes: RegExp | RegExp[]) => void
用来指定 less-loader
不编译哪些文件,你可以传入一个或多个正则表达式来匹配 less 文件的路径。例如:
export default {
tools: {
less(config, { addExcludes }) {
addExcludes(/node_modules/);
},
},
};
tools.postcss
- 类型:
Object | Function
- 默认值:
const defaultOptions = {
postcssOptions: {
plugins: [
require('postcss-flexbugs-fixes'),
require('autoprefixer')({ flexbox: 'no-2009' }),
],
// 默认在开发环境下启用 CSS 的 Source Map
sourceMap: isDev,
},
};
Rsbuild 默认集成 PostCSS,你可以通过 tools.postcss
对 postcss-loader 进行配置。
Function 类型
值为 Function 类型时,内部默认配置作为第一参数传入,可以直接修改配置对象不做返回,也可以返回一个对象作为最终结果;第二个参数为修改 postcss-loader 配置的工具函数集合。
例如,需要在原有插件的基础上新增一个 PostCSS 插件,在 postcssOptions.plugins 数组中 push 一个新的插件即可:
export default {
tools: {
postcss: (opts) => {
opts.postcssOptions.plugins.push(require('postcss-px-to-viewport'));
},
},
};
需要给 PostCSS 插件传递参数时,可以通过函数参数的形式进行传入:
export default {
tools: {
postcss: (opts) => {
const viewportPlugin = require('postcss-px-to-viewport')({
viewportWidth: 375,
});
opts.postcssOptions.plugins.push(viewportPlugin);
},
},
};
tools.postcss
可以返回一个配置对象,并完全替换默认配置:
export default {
tools: {
postcss: () => {
return {
postcssOptions: {
plugins: [require('postcss-px-to-viewport')],
},
};
},
},
};
Object 类型
当此值为 Object 类型时,与默认配置通过 Object.assign
合并。注意 Object.assign
是浅拷贝,会完全覆盖内置的 plugins
数组,请谨慎使用。
export default {
tools: {
postcss: {
// 由于使用 `Object.assign` 合并,因此默认的 postcssOptions 会被覆盖。
postcssOptions: {
plugins: [require('postcss-px-to-viewport')],
},
},
},
};
工具函数
addPlugins
- 类型:
(plugins: PostCSSPlugin | PostCSSPlugin[]) => void
用于添加额外的 PostCSS 插件,你可以传入单个 PostCSS 插件,也可以传入 PostCSS 插件数组。
export default {
tools: {
postcss: (config, { addPlugins }) => {
// 添加一个插件
addPlugins(require('postcss-preset-env'));
// 批量添加插件
addPlugins([require('postcss-preset-env'), require('postcss-import')]);
},
},
};
TIP
Rsbuild 中使用的 PostCSS 版本为 v8,当你引入社区中的 PostCSS 插件时,请注意版本是否适配,部分旧版本插件可能无法在 PostCSS v8 下运行。
tools.sass
- 类型:
Object | Function
- 默认值:
const defaultOptions = {
// 默认在开发环境下启用 CSS 的 Source Map
sourceMap: isDev,
};
你可以通过 tools.sass
修改 sass-loader 的配置。
Object 类型
当 tools.sass
的值为 Object
类型时,会与默认配置通过 Object.assign 进行浅层合并,值得注意的是,sassOptions
会通过 deepMerge 进行深层合并。
export default {
tools: {
sass: {
sourceMap: true,
},
},
};
Function 类型
当 tools.sass
为 Function 类型时,默认配置作为第一个参数传入,可以直接修改配置对象,也可以返回一个值作为最终结果,第二个参数提供了一些可以直接调用的工具函数:
export default {
tools: {
sass(config) {
// 修改 sourceMap 配置
config.additionalData = async (content, loaderContext) => {
// ...
};
},
},
};
修改 Sass 版本
在某些场景下,如果你需要使用特定的 Sass 版本,而不是使用 Rsbuild 内置的 Dart Sass v1,可以在项目中安装需要使用的 Sass 版本,并通过 sass-loader
的 implementation
选项设置。
export default {
tools: {
sass: {
implementation: require('sass'),
},
},
};
工具函数
addExcludes
- 类型:
(excludes: RegExp | RegExp[]) => void
用来指定 sass-loader
不编译哪些文件,你可以传入一个或多个正则表达式来匹配 sass 文件的路径。例如:
export default {
tools: {
sass(config, { addExcludes }) {
addExcludes(/node_modules/);
},
},
};
tools.styleLoader
- 类型:
Object | Function
- 默认值:
{}
通过 tools.styleLoader
可以设置 style-loader 的配置项。
值得注意的是,Rsbuild 默认不会开启 style-loader
,你可以通过 output.disableCssExtract
配置项来开启它。
Object 类型
当此值为 Object 类型时,与默认配置通过 Object.assign 合并。比如:
export default {
tools: {
styleLoader: {
insert: 'head',
},
},
};
Function 类型
当此值为 Function 类型时,默认配置作为第一个参数传入,你可以直接修改配置对象,也可以返回一个对象作为最终配置。比如:
export default {
tools: {
styleLoader: (config) => {
config.insert = 'head';
return config;
},
},
};
tools.rspack
- 类型:
Object | Function | undefined
- 默认值:
undefined
- 打包工具:
仅支持 Rspack
tools.rspack
选项用于配置原生的 Rspack。
Object 类型
tools.rspack
可以配置为一个对象,这个对象将会和内置的 Rspack 配置通过 webpack-merge 进行深层合并。
比如添加 resolve.alias
配置:
export default {
tools: {
rspack: {
resolve: {
alias: {
'@util': 'src/util',
},
},
},
},
};
Function 类型
tools.rspack
也可以配置为一个函数,这个函数接收一个参数,即内置的 Rspack 配置对象,你可以对这个对象进行修改,然后返回一份新的配置。比如:
export default {
tools: {
rspack: (config) => {
config.resolve.alias['@util'] = 'src/util';
return config;
},
},
};
TIP
tools.rspack
函数返回的对象会直接作为最终使用的 Rspack 配置,不会再与内置的 Rspack 配置进行合并。
工具集合
这个函数的第二个参数是一个对象,包含了一些工具函数和属性,详情如下:
env
- 类型:
'development' | 'production' | 'test'
通过 env 参数可以判断当前环境为 development、production 还是 test。比如:
export default {
tools: {
rspack: (config, { env }) => {
if (env === 'development') {
config.devtool = 'cheap-module-eval-source-map';
}
return config;
},
},
};
isProd
通过 isProd 参数可以判断当前环境是否为 production。比如:
export default {
tools: {
rspack: (config, { isProd }) => {
if (isProd) {
config.devtool = 'source-map';
}
return config;
},
},
};
target
- 类型:
'web' | 'node' | 'web-worker'
通过 target 参数可以判断当前构建的目标运行时环境。比如:
export default {
tools: {
rspack: (config, { target }) => {
if (target === 'node') {
// ...
}
return config;
},
},
};
isServer
判断当前构建的目标运行时环境是否为 node
,等价于 target === 'node'
。
export default {
tools: {
rspack: (config, { isServer }) => {
if (isServer) {
// ...
}
return config;
},
},
};
isWebWorker
判断当前构建的目标运行时环境是否为 web-worker
,等价于 target === 'web-worker'
。
export default {
tools: {
rspack: (config, { isWebWorker }) => {
if (isWebWorker) {
// ...
}
return config;
},
},
};
rspack
- 类型:
typeof import('@rspack/core')
通过这个参数你可以拿到 Rspack 实例。比如:
export default {
tools: {
rspack: (config, { rspack }) => {
config.plugins.push(new rspack.BannerPlugin());
return config;
},
},
};
addRules
- 类型:
(rules: RuleSetRule | RuleSetRule[]) => void
添加额外的 Rspack rules。
示例:
export default {
tools: {
rspack: (config, { addRules }) => {
// 添加单条规则
addRules({
test: /\.foo/,
loader: require.resolve('foo-loader'),
});
// 以数组形式添加多条规则
addRules([
{
test: /\.foo/,
loader: require.resolve('foo-loader'),
},
{
test: /\.bar/,
loader: require.resolve('bar-loader'),
},
]);
},
},
};
prependPlugins
- 类型:
(plugins: RspackPluginInstance | RspackPluginInstance[]) => void
在内部 Rspack 插件数组头部添加额外的插件,数组头部的插件会优先执行。
export default {
tools: {
rspack: (config, { prependPlugins }) => {
// 添加单个插件
prependPlugins(new PluginA());
// 以数组形式添加多个插件
prependPlugins([new PluginA(), new PluginB()]);
},
},
};
appendPlugins
- 类型:
(plugins: RspackPluginInstance | RspackPluginInstance[]) => void
在内部 Rspack 插件数组尾部添加额外的插件,数组尾部的插件会在最后执行。
export default {
tools: {
rspack: (config, { appendPlugins }) => {
// 添加单个插件
appendPlugins([new PluginA()]);
// 以数组形式添加多个插件
appendPlugins([new PluginA(), new PluginB()]);
},
},
};
removePlugin
- 类型:
(name: string) => void
删除内部的 Rspack 插件,参数为该插件的 constructor.name
。
例如,删除内部的 webpack-bundle-analyzer:
export default {
tools: {
rspack: (config, { removePlugin }) => {
removePlugin('BundleAnalyzerPlugin');
},
},
};
mergeConfig
- 类型:
(...configs: RspackConfig[]) => RspackConfig
用于合并多份 Rspack 配置,等价于 webpack-merge。
export default {
tools: {
rspack: (config, { mergeConfig }) => {
return mergeConfig(config, {
devtool: 'eval',
});
},
},
};
getCompiledPath
- 类型:
(name: string) => string
获取 Rsbuild 内置依赖的所在路径,例如:
- sass
- sass-loader
- less
- less-loader
- babel-loader
- url-loader
- file-loader
- ...
该方法通常在需要与 Rsbuild 复用同一份依赖时会被用到。
TIP
Rsbuild 内部依赖会随着版本迭代而发生变化,例如产生大版本变更。在非必要的情况下,请避免使用此 API。
export default {
tools: {
rspack: (config, { getCompiledPath }) => {
const loaderPath = getCompiledPath('less-loader');
// ...
},
},
};