简体中文

Rsbuild Instance

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

rsbuild.context

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

context.version

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

类型：

type Version = string;

context.entry

构建入口对象，对应 source.entry 选项。

类型：

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

context.targets

构建产物类型，对应调用 Rsbuild 配置里的 output.targets 选项。

类型：

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

type Context = {
  targets: RsbuildTarget[];
};

context.rootPath

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

类型：

type RootPath = string;

context.distPath

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

类型：

type DistPath = string;

context.cachePath

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

类型：

type CachePath = string;

context.tsconfigPath

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

类型：

type TsconfigPath = string | undefined;

context.devServer

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

类型：

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

context.bundlerType

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

类型：

type bundlerType = 'rspack' | 'webpack';

rsbuild.build

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

类型：

type BuildOptions = {
  mode?: 'development' | 'production';
  watch?: boolean;
  // 自定义 Compiler 对象
  compiler?: Compiler | MultiCompiler;
};

function Build(options?: BuildOptions): 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);
}

开发环境构建

如果需要执行一次开发环境构建，可以将 mode 参数设置为 'development'。

await rsbuild.build({
  mode: 'development',
});

监听文件变化

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

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

自定义 Compiler

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

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

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

rsbuild.startDevServer

启动本地 dev server。

类型：

type StartDevServerOptions = {
  // 是否输出 URL 信息，默认为 true
  printURLs?: boolean | Function;
  // 自定义 Compiler 对象
  compiler?: Compiler | MultiCompiler;
  // 是否在启动时静默获取端口号，默认为 false
  getPortSilently?: boolean;
  // 自定义日志输出对象
  logger?: Logger;
};

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:8080
  > Network:  http://192.168.0.1:8080

startDevServer 会返回以下参数：

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

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

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

自定义 URL 输出

将 printURLs 设置为 false 可以禁用默认的 URL 输出，此时你可以输出自定义的日志内容。

await rsbuild.startDevServer({
  printURLs: false,
});

你也可以直接将 printURLs 配置为一个函数来修改 URL，比如给每个 URL 增加一个子路径：

await rsbuild.startDevServer({
  printURLs: (urls) => {
    return urls.map(({ label, url }) => ({
      label,
      url: `${url}/path`,
    }));
  },
});

自定义 Compiler

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

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

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

静默获取端口号

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

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

自定义日志输出对象

默认情况下，Rsbuild 会使用 rslog 来输出日志，你可以通过 logger 参数来自定义日志输出对象。

const customLogger = {
  // 你需要定义以下的方法
  info(msg: string) {
    console.log(msg);
  },
  error(msg: string) {
    console.error(msg);
  },
  warn(msg: string) {
    console.warn(msg);
  },
  success(msg: string) {
    console.log(`✅ msg`);
  },
  debug(msg: string) {
    if (process.env.DEBUG) {
      console.log(msg);
    }
  },
  log(msg: string) {
    console.log(msg);
  };
}

await rsbuild.startDevServer({
  logger: customLogger,
});

这样，Rsbuild 会使用你自定义的日志输出对象来输出日志。

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 hanble 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:8080', 'http://192.168.0.1:8080']
console.log(port); // 8080

// 关闭 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: RsbuildPlugins[],
  options?: AddPluginsOptions,
): Promise<void>;

示例：

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

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

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

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

查看 Rsbuild 内部最终生成的 Rsbuild 配置和 bundler 配置。

TIP

inspectConfig 方法不支持与 startDevServer / build 方法同时使用。

当你需要在构建过程中查看完整的 Rsbuild 和 bundler 配置时，可以使用调试模式，也可以通过 onBeforeBuild、onBeforeCreateCompile 等钩子函数来获取。

类型：

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

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

示例：

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

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

console.log(rsbuildConfig, bundlerConfigs);

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

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

rsbuild.onBeforeCreateCompiler

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

你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置数组：

如果当前打包工具为 Rspack，则获取到的是 Rspack 配置数组。
如果当前打包工具为 webpack，则获取到的是 webpack 配置数组。
配置数组中可能包含一份或多份配置，这取决于你是否开启了 SSR 等功能。

你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置对象。

类型：

function OnBeforeCreateCompiler(
  callback: (params: {
    bundlerConfigs: WebpackConfig[] | RspackConfig[];
  }) => Promise<void> | void,
): void;

示例：

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

rsbuild.onAfterCreateCompiler

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

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

如果当前打包工具为 Rspack，则获取到的是 Rspack Compiler 对象。
如果当前打包工具为 webpack，则获取到的是 webpack Compiler 对象。
类型：

function OnAfterCreateCompiler(callback: (params: {
  compiler: Compiler | MultiCompiler;
}) => Promise<void> | void;): void;

示例：

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

rsbuild.onBeforeBuild

onBeforeBuild 是在执行生产环境构建前触发的回调函数，你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置数组：

如果当前打包工具为 Rspack，则获取到的是 Rspack 配置数组。
如果当前打包工具为 webpack，则获取到的是 webpack 配置数组。
配置数组中可能包含一份或多份配置，这取决于 Rsbuild 当前 target 配置的值。
类型：

function OnBeforeBuild(
  callback: (params: {
    bundlerConfigs?: WebpackConfig[] | RspackConfig[];
  }) => Promise<void> | void,
): void;

示例：

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

rsbuild.onAfterBuild

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

如果当前打包工具为 Rspack，则获取到的是 Rspack Stats。
如果当前打包工具为 webpack，则获取到的是 webpack Stats。
类型：

function OnAfterBuild(
  callback: (params: { stats?: Stats | MultiStats }) => Promise<void> | void,
): void;

示例：

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

rsbuild.onBeforeStartDevServer

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

类型：

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

示例：

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

rsbuild.onAfterStartDevServer

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

类型：

function OnAfterStartDevServer(
  callback: (params: { port: number }) => Promise<void> | void,
): void;

示例：

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

rsbuild.onBeforeStartProdServer

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

类型：

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

示例：

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

rsbuild.onAfterStartProdServer

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

类型：

function OnAfterStartProdServer(
  callback: (params: { port: number }) => Promise<void> | void,
): void;

示例：

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

rsbuild.onDevCompileDone

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

类型：

function OnDevCompileDone(
  callback: (params: {
    isFirstCompile: boolean;
    stats: Stats | MultiStats;
  }) => 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 = api.getRsbuildConfig();
  console.log(config.html?.title);
});

rsbuild.getNormalizedConfig

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

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

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

类型：

function GetNormalizedConfig(): Readonly<NormalizedConfig>;

示例：

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

rsbuild.getHTMLPaths

获取所有 HTML 产物的路径信息。

该方法会返回一个对象，对象的 key 为 entry 名称，value 为 HTML 文件在产物目录下的相对路径。

类型：

function GetHTMLPaths(): Record<string, string>;

示例：

rsbuild.onBeforeBuild(() => {
  const htmlPaths = api.getHTMLPaths();
  console.log(htmlPaths); // { main: 'html/main/index.html' };
});

Rsbuild Instance#

rsbuild.context#

context.version#

context.entry#

context.targets#

context.rootPath#

context.distPath#

context.cachePath#

context.tsconfigPath#

context.devServer#

context.bundlerType#

rsbuild.build#

开发环境构建#

监听文件变化#

自定义 Compiler#

rsbuild.startDevServer#

自定义 URL 输出#

自定义 Compiler#

静默获取端口号#

自定义日志输出对象#

rsbuild.preview#

rsbuild.createCompiler#

rsbuild.addPlugins#

rsbuild.removePlugins#

rsbuild.isPluginExists#

rsbuild.inspectConfig#

rsbuild.onBeforeCreateCompiler#

rsbuild.onAfterCreateCompiler#

rsbuild.onBeforeBuild#

rsbuild.onAfterBuild#

rsbuild.onBeforeStartDevServer#

rsbuild.onAfterStartDevServer#

rsbuild.onBeforeStartProdServer#

rsbuild.onAfterStartProdServer#

rsbuild.onDevCompileDone#

rsbuild.onExit#

rsbuild.getRsbuildConfig#

rsbuild.getNormalizedConfig#

rsbuild.getHTMLPaths#

Rsbuild Instance

rsbuild.context

context.version

context.entry

context.targets

context.rootPath

context.distPath

context.cachePath

context.tsconfigPath

context.devServer

context.bundlerType

rsbuild.build

开发环境构建

监听文件变化

自定义 Compiler

rsbuild.startDevServer

自定义 URL 输出

自定义 Compiler

静默获取端口号

自定义日志输出对象

rsbuild.preview

rsbuild.createCompiler

rsbuild.addPlugins

rsbuild.removePlugins

rsbuild.isPluginExists

rsbuild.inspectConfig

rsbuild.onBeforeCreateCompiler

rsbuild.onAfterCreateCompiler

rsbuild.onBeforeBuild

rsbuild.onAfterBuild

rsbuild.onBeforeStartDevServer

rsbuild.onAfterStartDevServer

rsbuild.onBeforeStartProdServer

rsbuild.onAfterStartProdServer

rsbuild.onDevCompileDone

rsbuild.onExit

rsbuild.getRsbuildConfig

rsbuild.getNormalizedConfig

rsbuild.getHTMLPaths