简体中文

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

调用 build 方法时，会执行一次生产模式构建。

类型：

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

function Build(options?: BuildOptions): Promise<{
  stats?: Rspack.Stats | Rspack.MultiStats;
  close: () => Promise<void>;
}>;

示例：

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

// build
await rsbuild.build();

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

监听文件变化

如果需要自动监听文件变化并重新执行构建，可以将 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 对象：

const result = await rsbuild.build();

console.log(result.stats);

自定义 Compiler

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

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

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

rsbuild.startDevServer

启动本地 dev server。

类型：

type StartDevServerOptions = {
  // 自定义 Compiler 对象
  compiler?: Compiler | MultiCompiler;
  // 是否在启动时静默获取端口号，默认为 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 中，可以通过该方法获取 dev server 的实例方法，按需进行调用。

类型：

type EnvironmentAPI = {
  [name: string]: {
    /**
     * 获取当前环境的构建信息
     */
    getStats: () => Promise<Stats>;
    /**
     * 在服务端加载并执行构建产物
     *
     * @param entryName - 入口名称，和 Rsbuild source.entry 的某一个 key 值对应
     * @returns 入口模块的返回值
     */
    loadBundle: <T = unknown>(entryName: string) => Promise<T>;
    /**
     * 获取编译后的 HTML 模版内容
     */
    getTransformedHtml: (entryName: string) => Promise<string>;
  };
};

type RsbuildDevServer = {
  /**
   * 监听 Rsbuild server
   * 当你使用自定义 server 时，不需要调用该方法
   */
  listen: () => Promise<{
    port: number;
    urls: string[];
    server: {
      close: () => Promise<void>;
    };
  }>;
  /**
   * Rsbuild server 提供的 environment API
   */
  environments: EnvironmentAPI;
  /**
   * 解析后的端口号
   * 默认情况下，Rsbuild Server 会监听 `3000` 端口，如果端口被占用，则自动递增端口号
   */
  port: number;
  /**
   * `connect` 实例
   * 可用于向 dev server 附加自定义中间件
   */
  middlewares: Connect.Server;
  /**
   * 通知 Rsbuild 自定义 Server 已启动
   * Rsbuild 会在此阶段触发 `onAfterStartDevServer` 钩子
   */
  afterListen: () => Promise<void>;
  /**
   * 激活 socket 连接
   * 这确保了 HMR 正常工作
   */
  connectWebSocket: (options: { server: HTTPServer }) => void;
  /**
   * 关闭 Rsbuild server
   */
  close: () => Promise<void>;
  /**
   * 打印 server URLs
   */
  printUrls: () => void;
};

type CreateDevServerOptions = {
  /** 自定义 Compiler 对象 */
  compiler?: Compiler | MultiCompiler;

  /** 是否在启动时静默获取端口号，默认为 false */
  getPortSilently?: boolean;

  /** 是否触发 Rsbuild 编译，默认为 true */
  runCompile?: boolean;
};

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

示例：

下面是一个在 express 中集成 Rsbuild DevServer 的例子:

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

export async function startDevServer() {
  // 初始化 Rsbuild
  const rsbuild = await createRsbuild({});

  const app = express();

  // 创建 Rsbuild DevServer 实例
  const rsbuildServer = await rsbuild.createDevServer();

  // 使用 Rsbuild 的内置中间件
  app.use(rsbuildServer.middlewares);

  const httpServer = app.listen(rsbuildServer.port, async () => {
    // 通知 Rsbuild 自定义 Server 已启动
    await rsbuildServer.afterListen();
  });

  rsbuildServer.connectWebSocket({ server: httpServer });
}

详细使用情况可参考：示例。

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

const server = await rsbuild.createDevServer();

await server.listen();

connectWebSocket

Rsbuild 内置了 WebSocket 处理器以支持 HMR 功能：

当用户通过浏览器访问页面时，会自动向服务器发起 WebSocket 连接请求。
Rsbuild 开发服务器检测到连接请求后，会指示内置的 WebSocket 处理器进行处理。
浏览器与 Rsbuild WebSocket 处理器成功建立连接后，便可进行实时通信。
每次重新编译完成后，Rsbuild WebSocket 处理器会通知浏览器。随后，浏览器向开发服务器发送 hot-update.(js|json) 请求，以加载编译后的新模块。

当你使用自定义的 server 时，可能会遇到 HMR 连接报错的问题，这是因为自定义的 server 没有将 WebSocket 连接请求转发给 Rsbuild 的 WebSocket 处理器。此时需要通过 connectWebSocket 方法已使 Rsbuild 能够感知并处理来自浏览器的 WebSocket 连接请求。

const rsbuildServer = await rsbuild.createDevServer();

const httpServer = app.listen(rsbuildServer.port);

rsbuildServer.connectWebSocket({ server: httpServer });

rsbuild.preview

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

类型：

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

function server(): 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

创建一个 compiler 对象。

当 createRsbuild 的 target 选项包含一个值时，返回值为 Compiler；当 target 包含多个值时，返回值为 MultiCompiler。

类型：

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

示例：

const compiler = await rsbuild.createCompiler();

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

rsbuild.addPlugins

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

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

类型：

type AddPluginsOptions = { before?: string } | { after?: string };

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

示例：

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

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

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

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

判断某个插件是否已经被注册。

类型：

function IsPluginExists(pluginName: string): boolean;

示例：

rsbuild.addPlugins([pluginFoo()]);

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

rsbuild.initConfigs

initConfigs 方法用于初始化 Rsbuild 内部的配置，并返回 Rsbuild 内部生成的 Rspack 配置。

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

类型：

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

示例：

const { rspackConfigs } = await rsbuild.initConfigs();

console.log(rspackConfigs);

rsbuild.inspectConfig

inspectConfig 方法通常用于调试 Rsbuild 内部的配置，它会返回 Rsbuild 内部生成的 Rsbuild 配置和 Rspack 配置，将它们序列化为字符串，并支持写入到磁盘上。

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

类型：

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[];
  };
}>;

示例

拿到字符串格式的 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.onBeforeStartDevServer

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

类型：

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

示例：

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

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#

connectWebSocket#

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

connectWebSocket

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

rsbuild.onAfterStartDevServer

rsbuild.onCloseDevServer

rsbuild.onBeforeStartProdServer

rsbuild.onAfterStartProdServer

rsbuild.onDevCompileDone

rsbuild.onExit

rsbuild.getRsbuildConfig

rsbuild.getNormalizedConfig