Rsbuild Core
本章节描述了 Rsbuild 提供的一些核心方法。
createRsbuild
创建一个 Rsbuild 实例对象。
function createRsbuild(
options?: CreateRsbuildOptions,
): Promise<RsbuildInstance>;
import { createRsbuild } from '@rsbuild/core';
const rsbuild = await createRsbuild({
rsbuildConfig: {
// rsbuild configs
},
});
Options
createRsbuild
的第一个参数是一个 options
对象,你可以传入以下选项:
type CreateRsbuildOptions = {
cwd?: string;
environment?: string[];
rsbuildConfig?: RsbuildConfig;
};
cwd
:当前执行构建的根路径,默认值为 process.cwd()
environment
:只构建指定的 environments。
rsbuildConfig
:Rsbuild 配置对象。参考 配置总览 查看所有可用的配置项。
loadConfig
加载 Rsbuild 配置文件。
function loadConfig(params?: {
// 默认为 process.cwd()
cwd?: string;
// 指定配置文件路径,可以为相对路径或绝对路径
path?: string;
meta?: Record<string, unknown>;
envMode?: string;
}): Promise<{
content: RsbuildConfig;
filePath: string | null;
}>;
import { loadConfig } from '@rsbuild/core';
// 默认加载 `rsbuild.config.*` 配置文件
const { content } = await loadConfig();
console.log(content); // -> Rsbuild config object
const rsbuild = await createRsbuild({
rsbuildConfig: content,
});
如果 cwd 目录下不存在 Rsbuild 配置文件,loadConfig 方法的返回值为 { content: {}, filePath: null }
。
指定配置文件
使用 path
选项加载 my-config.ts
配置文件:
import { join } from 'node:path';
import { loadConfig } from '@rsbuild/core';
const { content } = await loadConfig({
path: join(__dirname, 'my-config.ts'),
});
传入 meta 对象
加载配置文件,并传入自定义的 meta 对象:
import { join } from 'node:path';
import { loadConfig } from '@rsbuild/core';
const { content } = await loadConfig({
meta: {
foo: 'bar',
},
});
在 defineConfig
定义的配置函数中,你可以通过 meta
对象访问到 foo
变量:
rsbuild.config.ts
export default defineConfig((config, { meta }) => {
console.log(meta.foo); // bar
return config;
});
loadEnv
加载 .env
文件,并返回所有以 prefixes 开头的环境变量。
type LoadEnvOptions = {
/**
* 加载 env 文件的根路径
* @default process.cwd()
*/
cwd?: string;
/**
* 用于指定 .env.[mode] 文件的名称
* 等价于 Rsbuild CLI 的 `--env-mode` 选项
* @default process.env.NODE_ENV
*/
mode?: string;
/**
* public 变量的前缀
* @default ['PUBLIC_']
*/
prefixes?: string[];
};
function loadEnv(options: LoadEnvOptions): {
/** .env 文件包含的所有环境变量 */
parsed: Record<string, string>;
/** 所有 env 文件的绝对路径 */
filePaths: string[];
/**
* 以 prefixes 开头的环境变量
*
* @example
* ```ts
* {
* PUBLIC_FOO: 'bar',
* }
* ```
**/
rawPublicVars: Record<string, string | undefined>;
/**
* 以 prefix 开头的环境变量,并经过格式化。
* key 包含前缀 `process.env.*` 和 `import.meta.env.*`。
* value 经过 `JSON.stringify` 处理。
*
* @example
* ```ts
* {
* 'process.env.PUBLIC_FOO': '"bar"',
* 'import.meta.env.PUBLIC_FOO': '"bar"',
* }
* ```
**/
publicVars: Record<string, string>;
/** 从 `process.env` 上清除挂载的环境变量 */
cleanup: () => void;
};
import { loadEnv, mergeRsbuildConfig } from '@rsbuild/core';
const { parsed, publicVars } = loadEnv();
const mergedConfig = mergeRsbuildConfig(
{
source: {
define: publicVars,
},
},
userConfig,
);
该方法也会加载 .env.local
和 .env.[mode]
等文件,详见 环境变量。
TIP
Rsbuild CLI 会自动调用 loadEnv()
方法,如果你在使用 Rsbuild CLI,可以通过 --env-mode 选项来设置 mode
参数。
mergeRsbuildConfig
用于合并多份 Rsbuild 配置对象。
mergeRsbuildConfig
函数接收多个配置对象作为参数,它会将每一个配置对象进行深层合并,自动将多个函数项合并为顺序执行的函数数组,返回一个合并后的配置对象。
function mergeRsbuildConfig(...configs: RsbuildConfig[]): RsbuildConfig;
基础示例
import { mergeRsbuildConfig } from '@rsbuild/core';
const config1 = {
dev: {
https: false,
},
};
const config2 = {
dev: {
https: true,
},
};
const mergedConfig = mergeRsbuildConfig(config1, config2);
console.log(mergedConfig); // { dev: { https: true } }
该方法不会修改入参中的 config 对象。
合并规则
除了深层合并外,mergeRsbuildConfig
函数还会对部分选项进行特殊处理。
比如 tools.rspack 可以被设置为一个函数,当多份配置对象都包含 tools.rspack
时,mergeRsbuildConfig
不会简单地保留最后一个函数。相反,它会将所有的 tools.rspack
函数或对象合并到一个数组中。
import { mergeRsbuildConfig } from '@rsbuild/core';
const config1 = {
tools: {
rspack: {
someOption: true,
},
},
};
const config2 = {
tools: {
rspack: (config) => {
console.log('function 1');
return config;
},
},
};
const config3 = {
tools: {
rspack: (config) => {
console.log('function 2');
return config;
},
},
};
const mergedConfig = mergeRsbuildConfig(config1, config2, config3);
在以上示例中,合并后的配置为以下形式,该数组首先包含了一个对象 { someOption: true }
,然后是按合并顺序排列的两个函数。
数组中的每一项会依次执行,并且上一个函数的输出将作为下一个函数的输入,最终生成一份 Rspack 配置。
const mergedConfig = {
tools: {
rspack: [
{
someOption: true,
},
(config) => {
console.log('function 1');
return config;
},
(config) => {
console.log('function 2');
return config;
},
],
},
};
通过这种方法,我们可以确保合并多份配置对象时,相同的多个 tools.rspack
字段均能够生效。
在 Rsbuild 中,大部分支持函数值的选项都使用上述规则,比如 tools.postcss
、tools.less
、tools.bundlerChain
等。
logger
用于输出格式统一的日志信息,基于 rslog。
import { logger } from '@rsbuild/core';
// A gradient welcome log
logger.greet(`\n➜ Rsbuild v1.0.0\n`);
// Info
logger.info('This is a info message');
// Start
logger.start('This is a start message');
// Warn
logger.warn('This is a warn message');
// Ready
logger.ready('This is a ready message');
// Success
logger.success('This is a success message');
// Error
logger.error('This is a error message');
logger.error(new Error('This is a error message with stack'));
// Debug
logger.debug('This is a debug message');
// Same as console.log
logger.log('This is a log message');
自定义 Logger
你可以使用 logger.override
方法来覆盖默认 logger 的部分或全部方法:
import { logger } from '@rsbuild/core';
logger.override({
log: (message) => {
console.log(`[log] ${message}`);
},
info: (message) => {
console.log(`[info] ${message}`);
},
warn: (message) => {
console.warn(`[warn] ${message}`);
},
start: (message) => {
console.log(`[start] ${message}`);
},
ready: (message) => {
console.log(`[ready] ${message}`);
},
error: (message) => {
console.error(`[error] ${message}`);
},
success: (message) => {
console.error(`[success] ${message}`);
},
debug: (message) => {
if (process.env.DEBUG) {
console.log(`[debug] ${message}`);
}
},
});
logger.info('hello'); // [info] hello
rspack
由 @rspack/core
导出的 rspack
对象。
你可以直接从 @rsbuild/core
中引用 rspack
对象,而无须额外安装 @rspack/core
依赖。
import { rspack } from '@rsbuild/core';
console.log(rspack.rspackVersion); // 1.0.0
console.log(rspack.util.createHash);
请参考 Rspack - JavaScript API 了解更多。
version
当前使用的 @rsbuild/core
的版本。
import { version } from '@rsbuild/core';
console.log(version); // 1.0.0
ensureAssetPrefix
ensureAssetPrefix
函数用于将给定的 assetPrefix
拼接到一个可能是 URL 的字符串前面。如果传入的字符串已经是一个完整的 URL,则直接返回该字符串。
function ensureAssetPrefix(
// 需要处理的 URL 字符串。可以是相对路径或绝对 URL
url: string,
// 需要拼接的 URL 前缀
assetPrefix: string
) => string;
import { ensureAssetPrefix } from '@rsbuild/core';
ensureAssetPrefix('foo/bar.js', '/static/');
// -> '/static/foo/bar.js'
ensureAssetPrefix('foo/bar.js', 'https://example.com/static/');
// -> 'https://example.com/static/foo/bar.js'
ensureAssetPrefix(
'https://example.com/index.html',
'https://example.com/static/',
);
// -> 'https://example.com/index.html'