指南
配置
插件
API
社区
指南
配置
插件
API
社区
简体中文

多环境构建

Rsbuild 支持同时为多个环境构建产物。你可以使用 environments 来并行构建多个环境，并为每个环境设置不同的 Rsbuild 配置。

通过 environments 定义多环境配置

Rsbuild 支持通过 environments 为每个环境定义不同的 Rsbuild 配置。

例如，假如你的项目希望支持 SSR 功能，你需要分别为 client 和 SSR 定义不同的配置，你可以分别定义一个 web 和 node 的 environment。

rsbuild.config.ts
export default {
  environments: {
    // client 环境配置
    web: {
      source: {
        alias: {
          '@common1': './src/web/common1',
        },
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        // 定义构建产物类型适用于浏览器端
        target: 'web',
      },
    },
    // SSR 环境配置
    node: {
      source: {
        alias: {
          '@common1': './src/ssr/common1',
        },
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        // 定义构建产物类型适用于 Node.js
        target: 'node',
      },
    },
  },
};

以上配置完成后，Rsbuild 会基于这两份 environment 配置计算最终生效的 Rsbuild 及 Rspack 配置，并进行构建。

当你在项目根目录下执行命令 npx rsbuild inspect 后，会发现有如下输出：

  • rsbuild.config.[name].mjs: 表示在构建时某个 environment 对应使用的 Rsbuild 配置。
  • rspack.config.[name].mjs: 表示在构建时某个 environment 对应使用的 Rspack 配置。
➜ npx rsbuild inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config (web): /project/dist/rsbuild.config.web.mjs
  - Rsbuild Config (node): /project/dist/rsbuild.config.node.mjs
  - Rspack Config (web): /project/dist/rspack.config.web.mjs
  - Rspack Config (node): /project/dist/rspack.config.node.mjs

默认 environment

当 environments 未指定时，Rsbuild 默认会根据当前设置的产物类型 (output.target 的值) 创建一个同名的环境。

rsbuild.config.ts
export default {
  output: {
    target: 'web',
  },
};

以上配置相当于下面配置的语法糖：

rsbuild.config.ts
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
  },
};

通过插件 API 修改 environment 配置

新增 / 修改 environment 配置

Rsbuild 支持通过 modifyRsbuildConfig 钩子修改 / 新增 environment 配置。

const myPlugin = () => ({
  setup: (api) => {
    api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
      return mergeRsbuildConfig(config, {
        environments: {
          web1: {
            source: {
              entry: {
                index: './src/web1/index',
              },
            },
          },
        },
      });
    });
  },
});

修改单个 environment 配置

Rsbuild 支持通过 modifyEnvironmentConfig 钩子修改特定 environment 的 Rsbuild 配置。

const myPlugin = () => ({
  setup: (api) => {
    api.modifyEnvironmentConfig((config, { name }) => {
      if (name !== 'web') {
        return config;
      }
      config.html ||= {};
      config.html.title = 'My Default Title';
    });
  },
});

获取 environment 上下文

Environment context 是一个只读对象，提供一些和当前环境有关的上下文信息。Rsbuild 支持在 plugin hook 中获取 environment context 信息。

对于一些与构建环境相关的 plugin hooks (如 modifyBundlerChain、modifyRspackConfig 等), Rsbuild 支持通过 environment 参数获取当前 environment 上下文。

const myPlugin = () => ({
  setup: (api) => {
    api.modifyBundlerChain((chain, { environment }) => {
      const { name, config, entry } = environment;

      if (config.output.minify !== false) {
        chain.optimization
          .minimizer(CHAIN_ID.MINIMIZER.JS)
          .use(SwcJsMinimizerRspackPlugin)
          .end();
      }
    });
  },
});

对于一些全局的 plugin hooks (如 onDevCompileDone、onBeforeStartDevServer 等)， Rsbuild 支持通过 environments 参数获取所有环境的上下文。

const myPlugin = () => ({
  setup: (api) => {
    api.onDevCompileDone(({ environments }) => {
      const entries = Object.values(environments).map((e) => e.entry);
    });
  },
});

使用 environment API

Rsbuild Server 提供了一系列和构建环境相关的 API，用户可通过 Rsbuild environment API 在服务器端操作特定环境下的构建产物。

你可以在 Rsbuild DevMiddleware 或自定义 Server 中使用 environment API。

例如，你可以通过 Rsbuild environment API 在开发模式下快速实现一个 SSR 功能：

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

const serverRender = (serverAPI) => async (_req, res) => {
  const indexModule = await serverAPI.environments.ssr.loadBundle('index');

  const markup = indexModule.render();

  const template = await serverAPI.environments.web.getTransformedHtml('index');

  const html = template.replace('<!--app-content-->', markup);

  res.writeHead(200, {
    'Content-Type': 'text/html',
  });
  res.end(html);
};

export async function startDevServer() {
  const { content } = await loadConfig({});

  // Init Rsbuild
  const rsbuild = await createRsbuild({
    rsbuildConfig: content,
  });

  const app = express();

  // Create Rsbuild DevServer instance
  const rsbuildServer = await rsbuild.createDevServer();

  const serverRenderMiddleware = serverRender(rsbuildServer);

  app.get('/', async (req, res, next) => {
    try {
      await serverRenderMiddleware(req, res, next);
    } catch (err) {
      logger.error('SSR render error, downgrade to CSR...\n', err);
      next();
    }
  });

  // Apply Rsbuild’s built-in middlewares
  app.use(rsbuildServer.middlewares);

  // ...
}

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