配置项#

Rsbuild 提供了丰富的配置项，并为每个配置项预设了一个通用的默认值，它可以满足大部分使用场景。因此，在大多数情况下，你不需要声明任何 Rsbuild 配置，直接开箱使用即可。

如果你需要定制一些构建行为，那么可以这些配置项。

配置分类#

Rsbuild 中的配置可以分为以下几类：

• Dev：与本地开发有关的配置。
• Html：与 HTML 有关的配置。
• Tools：与底层工具有关的配置。
• Server：与 Rsbuild 服务器有关的配置，在本地开发和预览时都会生效。
• Source：与源代码解析、编译方式相关的配置。
• Output：与构建产物有关的配置。
• Performance：与编译性能、产物性能有关的配置。

你可以在 配置 页面找到所有配置项的详细说明。

使用配置#

当你使用 Rsbuild 的 CLI 命令时，Rsbuild 会自动读取当前项目根目录下的配置文件，按照以下顺序进行解析：

• rsbuild.config.ts
• rsbuild.config.js
• rsbuild.config.mjs
• rsbuild.config.cjs
• rsbuild.config.mts
• rsbuild.config.cts

我们推荐使用 .ts 格式的配置文件，并从 @rsbuild/core 中导入 defineConfig 工具函数, 它提供了友好的 TypeScript 类型推导和自动补全，可以帮助你避免配置中的错误。

比如在 rsbuild.config.ts 中，你可以定义 Rsbuild 的 source.alias 配置：

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

export default defineConfig({
  source: {
    alias: {
      '@common': './src/common',
    },
  },
});

如果你在开发一个非 TypeScript 项目，可以使用 .js 格式的配置文件：

module.exports = {
  source: {
    alias: (opts) => {
      opts['@common'] = './src/common';
    },
  },
};

使用环境变量#

在配置文件中，你可以使用 process.env.NODE_ENV 等 Node.js 环境变量，来动态写入不同的配置：

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

export default defineConfig({
  source: {
    alias: {
      '@request':
        process.env.NODE_ENV === 'development'
          ? './src/request.dev.js'
          : './src/request.prod.js',
    },
  },
});

导出配置函数#

Rsbuild 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Rsbuild。

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

export default defineConfig(({ env, command }) => ({
  source: {
    alias: {
      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
    },
  },
}));

该函数接受以下入参：

• env：对应 process.env.NODE_ENV 的值。
  • 当运行 rsbuild dev 时，env 的值为 development。
  • 当运行 rsbuild build 或 rsbuild preview 时，env 的值为 production。
• command：对应当前运行的命令，如 dev、build、preview。

导出异步函数#

Rsbuild 也支持在配置文件中导出一个异步函数，你可以在函数中进行一些异步操作：

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

export default defineConfig(async ({ env, command }) => {
  const result = await someAsyncFunction();

  return {
    html: {
      title: result,
    },
  };
});

合并配置#

你可以使用 @rspack/core 导出的 mergeRsbuildConfig 函数来合并多个配置。

import { defineConfig, mergeRsbuildConfig } from '@rsbuild/core';

const config1 = defineConfig({
  dev: { port: '8080' },
});
const config2 = defineConfig({
  dev: { port: '8081' },
});

// { dev: { port: '8081' }
export default mergeRsbuildConfig(config1, config2);

调试配置#

在执行构建时，你可以添加 DEBUG=rsbuild 环境变量来开启 Rsbuild 的调试模式。

DEBUG=rsbuild pnpm dev

在调试模式下，Rsbuild 会将内部最终生成的 Rsbuild 配置写入到产物目录下，便于开发者查看和调试。

打开生成的 /dist/rsbuild.config.js 文件，即可查看 Rsbuild 配置的完整内容。

关于调试模式的完整介绍，请查看 开启调试模式 章节。