Rsbuild instance

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

rsbuild.context

context 是一个只读对象，提供一些上下文信息，能够通过两种方式访问：

通过 Rsbuild 实例的 context 属性访问：

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

const rsbuild = createRsbuild({
  // ...
});

console.log(rsbuild.context);

通过 Rsbuild 插件的 api.context 访问：

export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    console.log(api.context);
  },
};

context.version

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

类型：

type Version = string;

context.rootPath

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

类型：

type RootPath = string;

context.configFile

通过 loadConfig 加载的配置文件绝对路径。未加载配置文件时为 undefined。

类型： string | undefined

context.configFileDependencies

配置文件所导入文件的绝对路径，由 loadConfig 收集。

类型： readonly string[]
默认值： []

context.distPath

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

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

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

类型：

type DistPath = string;

context.cachePath

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

类型：

type CachePath = string;

context.callerName

当前调用 Rsbuild 的框架或工具的名称，与 createRsbuild 方法中的 callerName 选项相同。

类型： string
默认值： 'rsbuild'
示例：

myPlugin.ts

export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    const { callerName } = api.context;

    if (callerName === 'rslib') {
      // ...
    } else if (callerName === 'rsbuild') {
      // ...
    }
  },
};

一些基于 Rsbuild 的工具已经设置了 callerName 的值：

名称	callerName
Rslib	`'rslib'`
Rstest	`'rstest'`
Rspress	`'rspress'`
Rspeedy	`'rspeedy'`

context.devServer

在开发模式下运行时的 dev server 信息。仅在 dev server 创建后可访问。

类型：

type DevServer = {
  /** 服务器运行时使用的 hostname */
  hostname: string;
  /** 服务器实际监听的端口号 */
  port: number;
  /** 是否使用 HTTPS 协议 */
  https: boolean;
};

示例：

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

async function main() {
  const rsbuild = createRsbuild({
    // ...
  });
  await rsbuild.startDevServer();

  // { hostname: 'localhost', port: 3000, https: false }
  console.log(rsbuild.context.devServer);
}

context.action

当前的动作类型。

类型：

type Action = 'dev' | 'build' | 'preview' | undefined;

context.action 在运行 CLI 命令或调用 Rsbuild 实例方法时设置：

dev: 当运行 rsbuild dev 或 rsbuild.startDevServer() 时设置。
build: 当运行 rsbuild build 或 rsbuild.build() 时设置。
preview: 当运行 rsbuild preview 或 rsbuild.preview() 时设置。

示例：

if (rsbuild.context.action === 'dev') {
  // do something
}

rsbuild.logger

rsbuild.logger 表示当前 Rsbuild 实例所关联的 logger，详见日志。

类型： Logger
示例：

const rsbuild = await createRsbuild();

rsbuild.logger.info('build started');

rsbuild.build

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

类型：

type BuildOptions = {
  /**
   * 是否监听文件变化并重新构建
   *
   * @default false
   */
  watch?: boolean;
};

function Build(options?: BuildOptions): Promise<{
  /**
   * Rspack 的 [stats](https://rspack.rs/zh/api/javascript-api/stats) 对象。
   */
  stats?: Rspack.Stats | Rspack.MultiStats;
  /**
   * 关闭构建并调用 `onCloseBuild` 钩子。
   * 在监听模式下，此方法将停止监听。
   */
  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,
});

结束构建

rsbuild.build() 返回一个 close() 方法，用于结束本次构建。

在 watch 模式下，调用 close() 方法将会结束监听：

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

在非 watch 模式下，你也应该调用 close() 方法来结束构建，这会触发 onCloseBuild 钩子，执行清理操作。

const buildResult = await rsbuild.build();
await buildResult.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);
}

rsbuild.startDevServer

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

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

类型：

type StartDevServerOptions = {
  /**
   * 是否在启动时静默获取端口号，不输出任何日志
   * @default false
   */
  getPortSilently?: boolean;
};

type StartDevServerResult = {
  /**
   * 服务器监听的 URLs
   */
  urls: string[];
  /**
   * 服务器实际使用的端口号
   */
  port: number;
  server: RsbuildDevServer;
};

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

示例：

启动 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:  use --host to expose

startDevServer 会返回以下参数：

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

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

关闭 server

调用 server.close() 方法会关闭开发服务器，触发 onCloseDevServer 钩子，并执行必要的清理操作。

const { server } = await rsbuild.startDevServer();
await server.close();

静默获取端口号

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

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

rsbuild.createDevServer

类型：

type CreateDevServerOptions = {
  /**
   * 是否在启动时静默获取端口号，不输出任何日志
   * @default false
   */
  getPortSilently?: boolean;
  /**
   * 是否触发 Rsbuild 编译
   * @default true
   */
  runCompile?: boolean;
};

function createDevServer(options?: CreateDevServerOptions): Promise<RsbuildDevServer>;

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

如果你需要将 Rsbuild dev server 集成到自定义的 server 中，可以通过 createDevServer 方法创建一个 dev server 实例，请参考 Server API 了解所有可用的 API。
如果你需要直接使用 Rsbuild dev server 启动项目，可以直接使用 rsbuild.startDevServer 方法。 rsbuild.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 StartPreviewServerResult = {
  /**
   * 服务器监听的 URLs
   */
  urls: string[];
  /**
   * 服务器实际使用的端口号
   */
  port: number;
  server: RsbuildPreviewServer;
};

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

示例：

启动 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 实例对象，详见 Server API

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

关闭 server

调用 close() 方法会关闭预览服务器。

const { server } = await rsbuild.preview();
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(options?: {
  /**
   * Get the plugins in the specified environment.
   * If environment is not specified, get the global plugins.
   */
  environment: string;
}): RsbuildPlugin[];

示例：

// get all plugins
console.log(rsbuild.getPlugins());

// get plugins in `web` environment
console.log(rsbuild.getPlugins({ environment: 'web' }));

rsbuild.removePlugins

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

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

类型：

function RemovePlugins(
  pluginNames: string[],
  options?: {
    /**
     * 移除指定 environment 中的插件。
     * 如果未指定 environment，则会从所有 environment 中移除。
     */
    environment?: string;
  },
): void;

示例：

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

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

rsbuild.isPluginExists

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

如果未指定 environment 参数，则判断全局注册的插件中是否存在该插件。
如果指定了 environment 参数，则判断在指定环境中是否存在该插件。
类型：

function IsPluginExists(
  pluginName: string,
  options?: {
    /**
     * Whether it exists in the specified environment.
     * If environment is not specified, determine whether the plugin is a global plugin.
     */
    environment: string;
  },
): boolean;

示例：

const pluginFoo = {
  name: 'plugin-foo',
  setup(api) {
    // ...
  },
};

const rsbuild = createRsbuild({
  config: {
    plugins: [pluginFoo],
  },
});

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

或者检查指定环境中是否存在插件：

const rsbuild = createRsbuild({
  config: {
    environments: {
      web: {
        plugins: [pluginFoo],
      },
    },
  },
});

rsbuild.isPluginExists(pluginFoo.name, {
  environment: 'web',
}); // true

rsbuild.initConfigs

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

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

类型：

type InitConfigsOptions = {
  /**
   * 当前的动作类型。
   * - dev: 当运行 `rsbuild dev` 或 `rsbuild.startDevServer()` 时设置。
   * - build: 当运行 `rsbuild build` 或 `rsbuild.build()` 时设置。
   * - preview: 当运行 `rsbuild preview` 或 `rsbuild.preview()` 时设置。
   */
  action?: 'dev' | 'build' | 'preview';
};

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

示例：

const rspackConfigs = await rsbuild.initConfigs();

console.log(rspackConfigs);

const buildConfigs = await rsbuild.initConfigs({
  action: 'build',
});

console.log(buildConfigs);

rsbuild.inspectConfig

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

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

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

类型：

type InspectConfigOptions = {
  /**
   * 检查指定 mode 下的配置
   * 可选值：'development' 或 'production'
   * @default 'development'
   */
  mode?: RsbuildMode;
  /**
   * 启用详细模式，显示配置中函数的完整内容
   * @default false
   */
  verbose?: boolean;
  /**
   * 指定检查结果的输出路径
   * @default 'output.distPath.root'
   */
  outputPath?: string;
  /**
   * 是否将检查结果写入磁盘
   * @default false
   */
  writeToDisk?: boolean;
  /**
   * 需要额外输出的配置
   * - key: 配置的名称
   * - value: 配置对象
   */
  extraConfigs?: Record<string, unknown>;
};

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 插件 hook 一致。

onBeforeCreateCompiler 是在创建 Rspack 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 插件 hook 一致。

onAfterCreateCompiler 是在创建 Rspack 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 插件 hook 一致。

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 插件 hook 一致。

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

功能与 onCloseBuild 插件 hook 一致。

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

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

类型：

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

示例：

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

rsbuild.onBeforeStartDevServer

功能与 onBeforeStartDevServer 插件 hook 一致。

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

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

类型：

type MaybePromise<T> = T | Promise<T>;

type OnBeforeStartDevServerFn = (params: {
  /**
   * The dev server instance, the same as the return value of `createDevServer`.
   */
  server: RsbuildDevServer;
  /**
   * Context information for all environments.
   */
  environments: Record<string, EnvironmentContext>;
}) => MaybePromise<(() => MaybePromise<void>) | 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

功能与 onAfterStartDevServer 插件 hook 一致。

在启动开发服务器后调用。你可以通过 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

功能与 onCloseDevServer 插件 hook 一致。

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

Rsbuild CLI 会自动在合适的时机调用此钩子，使用 JavaScript API 的用户需要手动调用 server.close() 方法来触发此钩子。

类型：

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

示例：

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

rsbuild.onBeforeStartPreviewServer

功能与 onBeforeStartPreviewServer 插件 hook 一致。

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

可以通过 server 参数访问预览服务器并注册自定义的中间件。

类型：

type MaybePromise<T> = T | Promise<T>;

type OnBeforeStartPreviewServerFn = (params: {
  /**
   * 预览服务器实例
   */
  server: RsbuildPreviewServer;
  /**
   * 所有 environments 的上下文信息
   */
  environments: Record<string, EnvironmentContext>;
}) => MaybePromise<void>;

function OnBeforeStartPreviewServer(callback: OnBeforeStartPreviewServerFn): void;

示例：

rsbuild.onBeforeStartPreviewServer(({ server, environments }) => {
  console.log('before start!');
  console.log('the server is ', server);
  console.log('the environments contexts are: ', environments);
});

rsbuild.onAfterStartPreviewServer

功能与 onAfterStartPreviewServer 插件 hook 一致。

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

类型：

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

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

示例：

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

rsbuild.onBeforeDevCompile

功能与 onBeforeDevCompile 插件 hook 一致。

onBeforeDevCompile 是在执行开发环境构建前触发的回调函数。

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

另外，你可以通过 isFirstCompile 来判断是否为首次构建。

类型：

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

版本： 新增于 v1.5.0

示例：

rsbuild.onBeforeDevCompile(({ bundlerConfigs }) => {
  console.log('the Rspack configs are ', bundlerConfigs);
});

rsbuild.onAfterDevCompile

功能与 onAfterDevCompile 插件 hook 一致。

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

类型：

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

Tip

onAfterDevCompile 钩子在 Rsbuild v1.5.0 中新增。对于之前的版本，你可以使用功能完全相同的 onDevCompileDone 钩子。

示例：

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

rsbuild.onBeforeEnvironmentCompile

功能与 onBeforeEnvironmentCompile 插件 hook 一致。

版本： 添加于 v1.5.7
示例：

rsbuild.onBeforeEnvironmentCompile(({ bundlerConfig, environment }) => {
  console.log(`the bundler config for the ${environment.name} is `, bundlerConfig);
});

rsbuild.onAfterEnvironmentCompile

功能与 onAfterEnvironmentCompile 插件 hook 一致。

版本： 添加于 v1.5.7
示例：

rsbuild.onAfterEnvironmentCompile(({ isFirstCompile, stats }) => {
  console.log(stats?.toJson(), isFirstCompile);
});

rsbuild.onRestart

功能与 onRestart 插件 hook 一致。

当 dev server 或监听构建被请求重启时调用。

该 hook 会在以下情况中触发：

Rsbuild CLI 检测到配置文件或其依赖发生变化。
dev.watchFiles 中 type 为 'restart' 的文件发生变化。
通过 CLI 快捷键手动重启 dev server。

普通的重新构建不会触发该 hook。

使用 JavaScript API 时，rsbuild.startDevServer()、rsbuild.createDevServer() 和 rsbuild.build({ watch: true }) 会安装 restart watcher。被监听的文件发生变化时会调用该 hook。默认情况下，Rsbuild 不会关闭或重启当前任务；你可以传入 restart 选项来处理重启请求。

类型：

type RestartContext = {
  action: 'dev' | 'build';
  filePath?: string;
};

function OnRestart(callback: (context: RestartContext) => Promise<void> | void): void;

action：当前正在重启的 Rsbuild 操作类型。
filePath：触发重启的文件绝对路径，手动触发重启时为 undefined。
版本： 新增于 v2.1.7

示例：

rsbuild.onRestart(async ({ action, filePath }) => {
  console.log('restart!', action, filePath);
});

rsbuild.onExit

功能与 onExit 插件 hook 一致。

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

类型：

function OnExit(callback: (context: { exitCode: number }) => void): void;

示例：

rsbuild.onExit(({ exitCode }) => {
  console.log('exit: ', exitCode);
});

rsbuild.getRsbuildConfig

功能与 getRsbuildConfig 插件 API 一致。

获取 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

功能与 getNormalizedConfig 插件 API 一致。

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

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

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

类型：

type GetNormalizedConfig = {
  /** 获取归一化后的全部 Rsbuild 配置 */
  (): NormalizedConfig;
  /** 获取指定环境的归一化 Rsbuild 配置 */
  (options: { environment: string }): NormalizedEnvironmentConfig;
};

示例：

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

rsbuild.expose

功能与 expose 插件 API 一致。

版本： 添加于 v1.5.0
示例：

rsbuild.expose('my-id', {
  value: 1,
  double: (val: number) => val * 2,
});

你也可以为指定 environment（对应 config.environments 的 key）暴露 API：

rsbuild.expose(
  'my-id',
  {
    value: 1,
    double: (val: number) => val * 2,
  },
  {
    environment: 'web',
  },
);

当注册在同一 environment 中的插件调用 api.useExposed 时，Rsbuild 会优先解析 environment 级别的 API，如果不存在，则回退到全局 API。

rsbuild.modifyRsbuildConfig

功能与 modifyRsbuildConfig 插件 API 一致。

版本： 添加于 v1.5.0
示例：

rsbuild.modifyRsbuildConfig((config) => {
  config.html ||= {};
  config.html.title = 'My Default Title';
});

rsbuild.modifyEnvironmentConfig

功能与 modifyEnvironmentConfig 插件 API 一致。

版本： 添加于 v1.5.0
示例：

rsbuild.modifyEnvironmentConfig((config, { name }) => {
  if (name !== 'web') {
    return config;
  }
  config.html.title = 'My Default Title';
});

#Rsbuild instance

#rsbuild.context

#context.version

#context.rootPath

#context.configFile

#context.configFileDependencies

#context.distPath

#context.cachePath

#context.callerName

#context.devServer

#context.action

#rsbuild.logger

#rsbuild.build

#监听文件变化

#结束构建

#Stats 对象

#rsbuild.startDevServer

#关闭 server

#静默获取端口号

#rsbuild.createDevServer

#rsbuild.preview

#关闭 server

#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.onBeforeStartPreviewServer

#rsbuild.onAfterStartPreviewServer

#rsbuild.onBeforeDevCompile

#rsbuild.onAfterDevCompile

#rsbuild.onBeforeEnvironmentCompile

#rsbuild.onAfterEnvironmentCompile

#rsbuild.onRestart

#rsbuild.onExit

#rsbuild.getRsbuildConfig

#rsbuild.getNormalizedConfig

#rsbuild.expose

#rsbuild.modifyRsbuildConfig

#rsbuild.modifyEnvironmentConfig

Rsbuild instance

rsbuild.context

context.version

context.rootPath

context.configFile

context.configFileDependencies

context.distPath

context.cachePath

context.callerName

context.devServer

context.action

rsbuild.logger

rsbuild.build

监听文件变化

结束构建

Stats 对象

rsbuild.startDevServer

关闭 server

静默获取端口号

rsbuild.createDevServer

rsbuild.preview

关闭 server

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.onBeforeStartPreviewServer

rsbuild.onAfterStartPreviewServer

rsbuild.onBeforeDevCompile

rsbuild.onAfterDevCompile

rsbuild.onBeforeEnvironmentCompile

rsbuild.onAfterEnvironmentCompile

rsbuild.onRestart

rsbuild.onExit

rsbuild.getRsbuildConfig

rsbuild.getNormalizedConfig

rsbuild.expose

rsbuild.modifyRsbuildConfig

rsbuild.modifyEnvironmentConfig