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

Environment API

在这里你可以找到所有与 environment 相关的 API。

参考 多环境构建 了解更多。

Environment Context

Environment context 是一个只读对象，提供一些和当前环境有关的上下文信息。

在 Rsbuild 的 Plugin hooks 中，你可以通过 environment 或 environments 入参获取 environment context 对象。

type EnvironmentContext = {
  name: string;
  browserslist: string[];
  config: NormalizedEnvironmentConfig;
  distPath: string;
  entry: RsbuildEntry;
  htmlPaths: Record<string, string>;
  tsconfigPath?: string;
};

name

当前环境的唯一名称，用于区分和定位环境，对应于 environments 配置中的 key。

  • 类型： string
  • 示例：
api.modifyRspackConfig((config, { environment }) => {
  if (environment.name === 'node') {
    // modify config for node environment
  }
  return config;
});

browserslist

当前环境设置的目标浏览器范围。详见 设置浏览器范围。

  • 类型： string[]
  • 示例：
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.browserslist);
  return config;
});

config

当前环境使用的 Rsbuild 配置（经过归一化处理）。

  • 类型：
type NormalizedEnvironmentConfig = DeepReadonly<{
  dev: NormalizedDevConfig;
  html: NormalizedHtmlConfig;
  tools: NormalizedToolsConfig;
  source: NormalizedSourceConfig;
  server: NormalizedServerConfig;
  output: NormalizedOutputConfig;
  plugins?: RsbuildPlugins;
  security: NormalizedSecurityConfig;
  performance: NormalizedPerformanceConfig;
  moduleFederation?: ModuleFederationConfig;
}>;
  • 示例：
api.modifyRspackConfig((config, { environment }) => {
  // Rspack
  console.log(config);
  // Rsbuild config for current environment
  console.log(environment.config);
  return config;
});

distPath

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

  • 类型： string
  • 示例：
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.distPath);
  return config;
});

entry

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

  • 类型：
type RsbuildEntry = Record<string, string | string[] | EntryDescription>;
  • 示例：
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.entry);
  return config;
});

htmlPaths

HTML 产物的路径信息。

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

  • 类型：
type htmlPaths = Record<string, string>;
  • 示例：
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.htmlPaths);
  return config;
});

tsconfigPath

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

  • 类型：
type TsconfigPath = string | undefined;
  • 示例：
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.tsconfigPath);
  return config;
});

Environment API

Environment API 包了一些与多环境构建相关的 API。

你可以通过 rsbuild.createDevServer() 或 dev.setupMiddlewares 使用 environment API，这允许你在服务端获取特定环境下的构建产物信息。

type EnvironmentAPI = {
  [name: string]: {
    getStats: () => Promise<Stats>;
    loadBundle: <T = unknown>(entryName: string) => Promise<T>;
    getTransformedHtml: (entryName: string) => Promise<string>;
  };
};

getStats

获取当前环境的产物信息。

  • 类型：
type GetStats = () => Promise<Stats>;
  • 示例：
const webStats = await environments.web.getStats();

console.log(webStats.toJson({ all: false }));

loadBundle

在服务端加载并执行构建产物。该方法会返回入口模块导出的内容。

  • 类型：
/**
 * @param entryName - 入口名称，和 Rsbuild `source.entry` 的某一个 key 值对应
 * @returns 入口模块的返回值
 */
type LoadBundle = <T = unknown>(entryName: string) => Promise<T>;
  • 示例：
// 加载 `main` 入口的 bundle
const result = await environments.node.loadBundle('main');

getTransformedHtml

获取经过编译和转换后的 HTML 模版内容。

  • 类型：
type GetTransformedHtml = (entryName: string) => Promise<string>;
  • 示例：
// 获取 main 入口的 HTML 内容
const html = await environments.web.getTransformedHtml('main');

该方法会返回完整的 HTML 字符串，包含了所有通过 HTML 插件注入的资源和内容。