简体中文

Rsbuild instance

本章节描述了 Rsbuild 实例对象上所有的属性和方法。

rsbuild.context

rsbuild.context 是一个只读对象，提供一些上下文信息。

context.version

当前使用的 @rsbuild/core 版本。

类型：

type Version = string;

context.rootPath

当前执行构建的根路径，对应调用 createRsbuild 时传入的 cwd 选项。

类型：

type RootPath = string;

context.distPath

构建产物输出目录的绝对路径，对应 RsbuildConfig 中的 output.distPath.root 配置项。

当有多个环境时，Rsbuild 会尝试获取所有环境的父 distPath 作为 context.distPath。

如果要获取指定环境的输出目录的绝对路径，建议使用 environment.distPath。

类型：

type DistPath = string;

context.cachePath

构建过程中生成的缓存文件所在的绝对路径。

类型：

type CachePath = string;

context.devServer

Dev server 相关信息，包含了当前 dev server 的 hostname 和端口号。

类型：

type DevServer = {
  hostname: string;
  port: number;
};

context.bundlerType

当前执行构建的构建工具类型。

类型：

type bundlerType = 'rspack' | 'webpack';

Rsbuild 内部支持切换到 webpack 进行对照测试，因此提供了该字段进行区分，通常你不需要使用此字段。

rsbuild.environments

target

构建产物类型，对应 Rsbuild 的 output.target 配置。

类型：

type RsbuildTarget = 'web' | 'node' | 'web-worker';

tsconfigPath

tsconfig.json 文件的绝对路径，若项目中不存在 tsconfig.json 文件，则为 undefined。

类型：

type TsconfigPath = string | undefined;

rsbuild.build

执行生产模式构建。该方法会生成优化后的生产构建产物，并输出到输出目录。

类型：

type BuildOptions = {
  /**
   * 是否监听文件变化并重新构建
   *
   * @default false
   */
  watch?: boolean;
  /**
   * 使用自定义的 Rspack Compiler 对象
   */
  compiler?: Compiler | MultiCompiler;
};

function Build(options?: BuildOptions): Promise<{
  /**
   * Rspack 的 [stats](https://rspack.dev/api/javascript-api/stats) 对象。
   */
  stats?: Rspack.Stats | Rspack.MultiStats;
  /**
   * 停止监听文件变化。
   */
  close: () => Promise<void>;
}>;

示例：

import { logger } from '@rsbuild/core';

// Example 1: run build
await rsbuild.build();

// Example 2: build and handle the error
try {
  await rsbuild.build();
} catch (err) {
  logger.error('Failed to build.');
  logger.error(err);
  process.exit(1);
}

// Example 3: build and get all assets
const { stats } = await rsbuild.build();

if (stats) {
  const { assets } = stats.toJson({
    // 排除不需要的字段以提高性能
    all: false,
    assets: true,
  });
  console.log(assets);
}

监听文件变化

如果需要自动监听文件变化并重新执行构建，可以将 watch 参数设置为 true。

await rsbuild.build({
  watch: true,
});

在 watch 模式下，rsbuild.build() 会返回一个 close 方法，调用该方法将会结束监听：

const result = await rsbuild.build({
  watch: true,
});

await result.close();

Stats 对象

在非 watch 模式下，rsbuild.build() 会返回一个 Rspack 的 stats 对象。

例如，使用 stats.toJson() 方法获取所有 assets 信息：

const result = await rsbuild.build();
const { stats } = result;

if (stats) {
  const { assets } = stats.toJson({
    // 排除不需要的字段以提高性能
    all: false,
    assets: true,
  });
  console.log(assets);
}

自定义 Compiler

个别情况下，你可能希望使用自定义的 compiler：

import { rspack } from '@rsbuild/core';

const compiler = rspack({
  // ...
});
await rsbuild.build({
  compiler,
});

rsbuild.startDevServer

启动本地 dev server。该方法会：

启动一个开发服务器，用于运行你的应用
自动监听文件变化并触发重新编译

类型：

type StartDevServerOptions = {
  /**
   * 使用自定义的 Rspack Compiler 对象
   */
  compiler?: Compiler | MultiCompiler;
  /**
   * 是否在启动时静默获取端口号，不输出任何日志
   * @default false
   */
  getPortSilently?: boolean;
};

type StartServerResult = {
  urls: string[];
  port: number;
  server: Server;
};

function StartDevServer(
  options?: StartDevServerOptions,
): Promise<StartServerResult>;

示例：

启动 dev server：

import { logger } from '@rsbuild/core';

// Start dev server
await rsbuild.startDevServer();

// Start dev server and handle the error
try {
  await rsbuild.startDevServer();
} catch (err) {
  logger.error('Failed to start dev server.');
  logger.error(err);
  process.exit(1);
}

成功启动 dev server 后，可以看到以下日志信息：

  ➜ Local:    http://localhost:3000
  ➜ Network:  http://192.168.0.1:3000

startDevServer 会返回以下参数：

urls：访问 dev server 的 URLs
port 实际监听的端口号
server：Server 实例对象

const { urls, port, server } = await rsbuild.startDevServer();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000

// 关闭 dev server
await server.close();

自定义 Compiler

个别情况下，你可能希望使用自定义的 compiler：

import { rspack } from '@rsbuild/core';

const compiler = rspack({
  // ...
});
await rsbuild.startDevServer({
  compiler,
});

静默获取端口号

某些情况下，默认启动的端口号已经被占用，此时 Rsbuild 会自动递增端口号，直至找到一个可用端口。这个过程会输出提示日志，如果你不希望这段日志，可以将 getPortSilently 设置为 true。

await rsbuild.startDevServer({
  getPortSilently: true,
});

rsbuild.createDevServer

Rsbuild 配备了一个内置的开发服务器，当你执行 rsbuild dev 时，将启动 Rsbuild dev server，并提供页面预览、路由、模块热更新等功能。

如果你希望将 Rsbuild dev server 集成到自定义的 server 中，可以通过 createDevServer 方法创建一个 dev server 实例，请参考 Dev server API 了解所有可用的 API。

如果你希望直接使用 Rsbuild dev server 启动项目，可以直接使用 Rsbuild - startDevServer 方法。 startDevServer 实际上是以下代码的语法糖：

const server = await rsbuild.createDevServer();

await server.listen();

rsbuild.preview

在本地启动 server 来预览生产模式构建的产物，需要在 rsbuild.build 方法之后执行。

类型：

type PreviewOptions = {
  /**
   * 是否在启动时静默获取端口号，不输出任何日志
   * @default false
   */
  getPortSilently?: boolean;
  /**
   * 是否检查 dist 目录存在且不为空
   * @default true
   */
  checkDistDir?: boolean;
};

type StartServerResult = {
  urls: string[];
  port: number;
  server: {
    close: () => Promise<void>;
  };
};

function preview(options?: PreviewOptions): Promise<StartServerResult>;

示例：

启动 Server：

import { logger } from '@rsbuild/core';

// Start preview server
await rsbuild.preview();

// Start preview server and handle the error
try {
  await rsbuild.preview();
} catch (err) {
  logger.error('Failed to start preview server.');
  logger.error(err);
  process.exit(1);
}

preview 会返回以下参数：

urls：访问 Server 的 URLs
port 实际监听的端口号
server：Server 实例对象

const { urls, port, server } = await rsbuild.preview();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000

// 关闭 Server
await server.close();

rsbuild.createCompiler

创建一个 Rspack Compiler 实例；如果本次构建存在多个 environments，则返回值为 MultiCompiler。

类型：

function CreateCompiler(): Promise<Compiler | MultiCompiler>;

示例：

const compiler = await rsbuild.createCompiler();

大部分场景下，你不需要使用该 API，除非需要进行自定义 dev server 等高级操作。

rsbuild.addPlugins

注册一个或多个 Rsbuild 插件，可以被多次调用。

该方法需要在开始编译前调用，如果在开始编译之后调用，则不会影响编译结果。

类型：

type AddPluginsOptions = { before?: string; environment?: string };

function AddPlugins(
  plugins: Array<RsbuildPlugin | Falsy>,
  options?: AddPluginsOptions,
): void;

示例：

rsbuild.addPlugins([pluginFoo(), pluginBar()]);

// 在 bar 插件之前插入
rsbuild.addPlugins([pluginFoo()], { before: 'bar' });

// 为 node 环境添加插件
rsbuild.addPlugins([pluginFoo()], { environment: 'node' });

rsbuild.getPlugins

获取当前 Rsbuild 实例中注册的所有 Rsbuild 插件。

类型：

function GetPlugins(): RsbuildPlugin[];

示例：

console.log(rsbuild.getPlugins());

rsbuild.removePlugins

移除一个或多个 Rsbuild 插件，可以被多次调用。

该方法需要在开始编译前调用，如果在开始编译之后调用，则不会影响编译结果。

类型：

function RemovePlugins(pluginNames: string[]): void;

示例：

// 添加插件
const pluginFoo = pluginFoo();
rsbuild.addPlugins(pluginFoo);

// 移除插件
rsbuild.removePlugins([pluginFoo.name]);

rsbuild.isPluginExists

判断某个插件是否已经在当前 Rsbuild 实例中注册。

类型：

function IsPluginExists(pluginName: string): boolean;

示例：

rsbuild.addPlugins([pluginFoo()]);

rsbuild.isPluginExists(pluginFoo().name); // true

rsbuild.initConfigs

初始化并返回 Rsbuild 内部使用的 Rspack 配置。该方法会处理所有插件和配置，生成最终的 Rspack 配置。

通常你不需要直接调用该方法，因为调用 rsbuild.build 和 rsbuild.startDevServer 等方法时会自动调用 initConfigs。

类型：

function InitConfigs(): Promise<{
  rspackConfigs: Rspack.Configuration[];
}>;

示例：

const rspackConfigs = await rsbuild.initConfigs();

console.log(rspackConfigs);

rsbuild.inspectConfig

检查和调试 Rsbuild 的内部配置。它允许你访问：

解析后的 Rsbuild 配置
特定 environment 的 Rsbuild 配置
生成的 Rspack 配置

该方法将这些配置序列化为字符串，并支持写入磁盘以进行检查。

类型：

type InspectConfigOptions = {
  // 查看指定环境下的配置
  // 默认为 "development"，可以设置为 "production"
  mode?: RsbuildMode;
  // 是否开启冗余模式，展示配置中函数的完整内容
  // 默认为 `false`
  verbose?: boolean;
  // 指定输出路径
  // 默认为 `output.distPath.root` 的值
  outputPath?: string;
  // 是否将结果写入到磁盘中
  // 默认为 `false`
  writeToDisk?: boolean;
};

async function InspectConfig(options?: InspectConfigOptions): Promise<{
  rsbuildConfig: string;
  bundlerConfigs: string[];
  environmentConfigs: string[];
  origin: {
    rsbuildConfig: RsbuildConfig;
    environmentConfigs: Record<string, EnvironmentConfig>;
    bundlerConfigs: BundlerConfigs[];
  };
}>;

TIP

如果你需要在构建过程中查看 Rsbuild 和 Rspack 配置，可以使用调试模式，也可以通过 onBeforeBuild、onBeforeCreateCompile 等 hooks 来获取。

示例

拿到字符串格式的 configs 内容：

const { rsbuildConfig, bundlerConfigs } = await rsbuild.inspectConfig();

console.log(rsbuildConfig, bundlerConfigs);

直接将配置内容写入到磁盘上：

await rsbuild.inspectConfig({
  writeToDisk: true,
});

输出路径

你可以通过 outputPath 来设置输出目录，默认为 output.distPath.root 的值。

当 outputPath 是一个相对路径时，会相对于 output.distPath.root 的值进行拼接。你也可以将 outputPath 设置为一个绝对路径，此时会直接将文件写入到该路径下。比如：

import path from 'node:path';

await rsbuild.inspectConfig({
  writeToDisk: true,
  outputPath: path.join(__dirname, 'custom-dir'),
});

rsbuild.onBeforeCreateCompiler

onBeforeCreateCompiler 是在创建底层 Compiler 实例前触发的回调函数，当你执行 rsbuild.startDevServer、rsbuild.build 或 rsbuild.createCompiler 时，都会调用此钩子。

你可以通过 bundlerConfigs 参数获取到 Rspack 配置数组，数组中可能包含一份或多份 Rspack 配置，这取决于是否配置了多个 environments。

类型：

function OnBeforeCreateCompiler(
  callback: (params: {
    bundlerConfigs: Rspack.Configuration[];
    environments: Record<string, EnvironmentContext>;
  }) => Promise<void> | void,
): void;

示例：

rsbuild.onBeforeCreateCompiler(({ bundlerConfigs }) => {
  console.log('the Rspack config is ', bundlerConfigs);
});

rsbuild.onAfterCreateCompiler

onAfterCreateCompiler 是在创建 Compiler 实例后、执行构建前触发的回调函数，当你执行 rsbuild.startDevServer、rsbuild.build 或 rsbuild.createCompiler 时，都会调用此钩子。

你可以通过 compiler 参数获取到 Compiler 实例对象:

类型：

function OnAfterCreateCompiler(callback: (params: {
  compiler: Compiler | MultiCompiler;
  environments: Record<string, EnvironmentContext>;
}) => Promise<void> | void;): void;

示例：

rsbuild.onAfterCreateCompiler(({ compiler }) => {
  console.log('the compiler is ', compiler);
});

rsbuild.onBeforeBuild

onBeforeBuild 是在执行生产模式构建前触发的回调函数。

你可以通过 bundlerConfigs 参数获取到 Rspack 配置数组，数组中可能包含一份或多份 Rspack 配置，这取决于是否配置了多个 environments。

另外，你可以通过 isWatch 判断是否是 watch 模式，并在 watch 模式下通过 isFirstCompile 来判断是否为首次构建。

类型：

function OnBeforeBuild(
  callback: (params: {
    isWatch: boolean;
    isFirstCompile: boolean;
    bundlerConfigs?: Rspack.Configuration[];
    environments: Record<string, EnvironmentContext>;
  }) => Promise<void> | void,
): void;

示例：

rsbuild.onBeforeBuild(({ bundlerConfigs }) => {
  console.log('the Rspack config is ', bundlerConfigs);
});

rsbuild.onAfterBuild

onAfterBuild 是在执行生产模式构建后触发的回调函数，你可以通过 stats 参数获取到构建结果信息。

另外，你可以通过 isWatch 判断是否是 watch 模式，并在 watch 模式下通过 isFirstCompile 来判断是否为首次构建。

类型：

function OnAfterBuild(
  callback: (params: {
    isFirstCompile: boolean;
    isWatch: boolean;
    stats?: Stats | MultiStats;
    environments: Record<string, EnvironmentContext>;
  }) => Promise<void> | void,
): void;

示例：

rsbuild.onAfterBuild(({ stats }) => {
  console.log(stats?.toJson());
});

rsbuild.onCloseBuild

在关闭构建时调用，可用于在构建关闭时执行清理操作。

Rsbuild CLI 会在执行 rsbuild build 完成后自动调用此钩子，使用 JavaScript API 的用户需要手动调用 rsbuild.close() 方法来触发此钩子。

类型：

function onCloseBuild(callback: () => Promise<void> | void): void;

示例：

rsbuild.onCloseBuild(async () => {
  console.log('close build!');
});

rsbuild.onBeforeStartDevServer

在启动开发服务器前调用。

通过 server 参数可以获取到开发服务器实例，参考 Dev server API 了解更多。

类型：

type OnBeforeStartDevServerFn = (params: {
  /**
   * The dev server instance, the same as the return value of `createDevServer`.
   */
  server: RsbuildDevServer;
  /**
   * A read-only object that provides some context information about different environments.
   */
  environments: Record<string, EnvironmentContext>;
}) => MaybePromise<void>;

function OnBeforeStartDevServer(callback: OnBeforeStartDevServerFn): void;

示例：

rsbuild.onBeforeStartDevServer(({ server, environments }) => {
  console.log('before starting dev server.');
  console.log('the server is ', server);
  console.log('the environments contexts are: ', environments);
});

查看 Plugin hooks - onBeforeStartDevServer 了解更多用法。

rsbuild.onAfterStartDevServer

在启动开发服务器后调用。你可以通过 port 参数获得开发服务器监听的端口号，通过 routes 获得页面路由信息。

类型：

type Routes = Array<{
  entryName: string;
  pathname: string;
}>;

function OnAfterStartDevServer(
  callback: (params: {
    port: number;
    routes: Routes;
    environments: Record<string, EnvironmentContext>;
  }) => Promise<void> | void,
): void;

示例：

rsbuild.onAfterStartDevServer(({ port, routes }) => {
  console.log('this port is: ', port);
  console.log('this routes is: ', routes);
});

rsbuild.onCloseDevServer

关闭开发服务器时调用，可用于在开发服务器关闭时执行清理操作。

类型：

function onCloseDevServer(callback: () => Promise<void> | void): void;

示例：

rsbuild.onCloseDevServer(async () => {
  console.log('close dev server!');
});

rsbuild.onBeforeStartProdServer

在启动生产预览服务器前调用。

类型：

function OnBeforeStartProdServer(callback: () => Promise<void> | void): void;

示例：

rsbuild.onBeforeStartProdServer(() => {
  console.log('before start!');
});

rsbuild.onAfterStartProdServer

在启动生产预览服务器后调用，你可以通过 port 参数获得生产服务器监听的端口号，通过 routes 获得页面路由信息。

类型：

type Routes = Array<{
  entryName: string;
  pathname: string;
}>;

function OnAfterStartProdServer(
  callback: (params: {
    port: number;
    routes: Routes;
    environments: Record<string, EnvironmentContext>;
  }) => Promise<void> | void,
): void;

示例：

rsbuild.onAfterStartProdServer(({ port, routes }) => {
  console.log('this port is: ', port);
  console.log('this routes is: ', routes);
});

rsbuild.onDevCompileDone

在每次开发模式构建结束后调用，你可以通过 isFirstCompile 来判断是否为首次构建。

类型：

function OnDevCompileDone(
  callback: (params: {
    isFirstCompile: boolean;
    stats: Stats | MultiStats;
    environments: Record<string, EnvironmentContext>;
  }) => Promise<void> | void,
): void;

示例：

rsbuild.onDevCompileDone(({ isFirstCompile }) => {
  if (isFirstCompile) {
    console.log('first compile!');
  } else {
    console.log('re-compile!');
  }
});

rsbuild.onExit

在进程即将退出时调用，这个钩子只能执行同步代码。

类型：

function OnExit(callback: () => void): void;

示例：

rsbuild.onExit(() => {
  console.log('exit!');
});

rsbuild.getRsbuildConfig

获取 Rsbuild 配置。

类型：

type GetRsbuildConfig = {
  (): Readonly<RsbuildConfig>;
  (type: 'original' | 'current'): Readonly<RsbuildConfig>;
  (type: 'normalized'): NormalizedConfig;
};

参数：

你可以通过 type 参数来指定读取的 Rsbuild 配置类型：

// 获取用户定义的原始 Rsbuild 配置。
getRsbuildConfig('original');

// 获取当前的 Rsbuild 配置。
// 在 Rsbuild 的不同执行阶段，该配置的内容会发生变化。
// 比如 `modifyRsbuildConfig` 钩子执行后会修改当前 Rsbuild 配置的内容。
getRsbuildConfig('current');

// 获取归一化后的 Rsbuild 配置。
// 该方法必须在 `modifyRsbuildConfig` 钩子执行完成后才能被调用。
// 等价于 `getNormalizedConfig` 方法。
getRsbuildConfig('normalized');

示例：

rsbuild.onBeforeBuild(() => {
  const config = rsbuild.getRsbuildConfig();
  console.log(config.html?.title);
});

rsbuild.getNormalizedConfig

获取归一化后的全部 Rsbuild 配置，或指定环境的 Rsbuild 配置。该方法必须在 modifyRsbuildConfig 钩子执行完成后才能被调用。

相较于 getRsbuildConfig 方法，该方法返回的配置经过了归一化处理，配置的类型定义会得到收敛，比如 config.html 的 undefined 类型将被移除。

推荐优先使用该方法获取配置。

类型：

/** 获取指定环境的 Rsbuild 配置 */
function GetNormalizedConfig(options: {
  environment: string;
}): Readonly<NormalizedEnvironmentConfig>;

/** 获取全部的 Rsbuild 配置 */
function GetNormalizedConfig(): Readonly<NormalizedConfig>;

示例：

rsbuild.onBeforeBuild(() => {
  const config = rsbuild.getNormalizedConfig();
  console.log(config.html.title);
});

Rsbuild instance#

rsbuild.context#

context.version#

context.rootPath#

context.distPath#

context.cachePath#

context.devServer#

context.bundlerType#

rsbuild.environments#

target#

tsconfigPath#

rsbuild.build#

监听文件变化#

Stats 对象#

自定义 Compiler#

rsbuild.startDevServer#

自定义 Compiler#

静默获取端口号#

rsbuild.createDevServer#

rsbuild.preview#

rsbuild.createCompiler#

rsbuild.addPlugins#

rsbuild.getPlugins#

rsbuild.removePlugins#

rsbuild.isPluginExists#

rsbuild.initConfigs#

rsbuild.inspectConfig#

示例#

输出路径#

rsbuild.onBeforeCreateCompiler#

rsbuild.onAfterCreateCompiler#

rsbuild.onBeforeBuild#

rsbuild.onAfterBuild#

rsbuild.onCloseBuild#

rsbuild.onBeforeStartDevServer#

rsbuild.onAfterStartDevServer#

rsbuild.onCloseDevServer#

rsbuild.onBeforeStartProdServer#

rsbuild.onAfterStartProdServer#

rsbuild.onDevCompileDone#

rsbuild.onExit#

rsbuild.getRsbuildConfig#

rsbuild.getNormalizedConfig#

Rsbuild instance

rsbuild.context

context.version

context.rootPath

context.distPath

context.cachePath

context.devServer

context.bundlerType

rsbuild.environments

target

tsconfigPath

rsbuild.build

监听文件变化

Stats 对象

自定义 Compiler

rsbuild.startDevServer

自定义 Compiler

静默获取端口号

rsbuild.createDevServer

rsbuild.preview

rsbuild.createCompiler

rsbuild.addPlugins

rsbuild.getPlugins

rsbuild.removePlugins

rsbuild.isPluginExists

rsbuild.initConfigs

rsbuild.inspectConfig

示例

输出路径

rsbuild.onBeforeCreateCompiler

rsbuild.onAfterCreateCompiler

rsbuild.onBeforeBuild

rsbuild.onAfterBuild

rsbuild.onCloseBuild

rsbuild.onBeforeStartDevServer

rsbuild.onAfterStartDevServer

rsbuild.onCloseDevServer

rsbuild.onBeforeStartProdServer

rsbuild.onAfterStartProdServer

rsbuild.onDevCompileDone

rsbuild.onExit

rsbuild.getRsbuildConfig

rsbuild.getNormalizedConfig