指南
配置
插件
API
指南
配置
插件
API
简体中文

Rsbuild Core

本章节描述了 Rsbuild 提供的一些核心方法。

createRsbuild

创建一个 Rsbuild 实例对象。

  • 类型：
function createRsbuild(options: CreateRsbuildOptions): Promise<RsbuildInstance>;
  • 示例：
import { createRsbuild } from '@rsbuild/core';

const rsbuild = await createRsbuild({
  // options
});

options

createRsbuild 的第一个参数是一个配置对象，你可以传入以下选项：

type RsbuildEntry = Record<string, string | string[]>;

type CreateRsbuildOptions = {
  cwd?: string;
  rsbuildConfig?: RsbuildConfig;
};

各个选项的作用：

  • cwd：当前执行构建的根路径，默认值为 process.cwd()
  • provider：用于切换底层的打包工具。
  • rsbuildConfig：Rsbuild 配置对象。Rsbuild 提供了丰富的配置项，允许你对构建行为进行灵活定制，你可以在配置中找到所有可用的配置项。

loadConfig

加载 Rsbuild 配置文件。

  • 类型：
function loadConfig(params: {
  // 默认为 process.cwd()
  cwd: string;
  // 指定配置文件路径，可以为相对路径或绝对路径
  path?: string;
}): Promise<RsbuildConfig>;
  • 示例：
const config = await loadConfig();

console.log(config); // -> RsbuildConfig

loadEnv

加载 .env 文件，并返回所有以 prefixes 开头的环境变量。

  • 类型：
function loadEnv(params: {
  // 默认为 process.cwd()
  cwd?: string;
  // 默认为 ['PUBLIC_']
  prefixes?: string[];
}): Promise<{
  // .env 文件包含的所有环境变量
  parsed: Record<string, string>;
  // 以 prefixes 开头的环境变量
  publicVars: Record<string, string>;
}>;
  • 示例：
const { parsed, publicVars } = await loadEnv();

mergeRsbuildConfig(
  {
    source: {
      define: publicVars,
    },
  },
  userConfig,
);

该方法也会加载 .env.local 和 .env.[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 对象。

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');