简体中文

Environment API

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

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

Environment context

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

类型：

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

Environment context 可以通过以下方式获取：

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

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

构建产物输出目录的绝对路径，对应 Rsbuild 的 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 产物的路径信息。

这个值是一个对象，对象的 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;
});

manifest

manifest 文件数据。仅在 output.manifest 配置被启用时才能访问。

类型： Record<string, unknown> | ManifestData | undefined
示例：

api.onAfterBuild(({ environments }) => {
  // Get the manifest data of web environment
  console.log(environments.web.manifest);
});

api.onAfterDevCompile(({ environments }) => {
  console.log(environments.web.manifest);
});

api.onAfterEnvironmentCompile(({ environment }) => {
  console.log(environment.manifest);
});

manifest 数据仅在构建完成后才能被访问，你可以在以下 hooks 中访问：

webSocketToken

WebSocket 认证 token，用于认证 WebSocket 连接，防止未授权访问。

仅在开发模式下可用，生产模式下为空字符串。

类型： string
版本： 添加于 v1.4.4

当你需要在浏览器中建立与 Rsbuild dev server 的 WebSocket 连接时，需要使用这个 token 作为 query 参数。

const { webSocketToken } = environments.web.context;

const webSocketUrl = `ws://localhost:${port}${pathname}?token=${webSocketToken}`;

Environment API

Environment API 提供一些与多环境构建相关的 API。

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

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

context

你可以通过 Environment API 获取和当前环境有关的上下文信息。

类型： EnvironmentContext
示例：

const webManifest = environments.web.context.manifest;

console.log(webManifest.entries);

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 插件注入的资源和内容。

Environment API

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

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

Environment context

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

类型：

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

Environment context 可以通过以下方式获取：

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

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

构建产物输出目录的绝对路径，对应 Rsbuild 的 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 产物的路径信息。

这个值是一个对象，对象的 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;
});

manifest

manifest 文件数据。仅在 output.manifest 配置被启用时才能访问。

类型： Record<string, unknown> | ManifestData | undefined
示例：

api.onAfterBuild(({ environments }) => {
  // Get the manifest data of web environment
  console.log(environments.web.manifest);
});

api.onAfterDevCompile(({ environments }) => {
  console.log(environments.web.manifest);
});

api.onAfterEnvironmentCompile(({ environment }) => {
  console.log(environment.manifest);
});

manifest 数据仅在构建完成后才能被访问，你可以在以下 hooks 中访问：

webSocketToken

WebSocket 认证 token，用于认证 WebSocket 连接，防止未授权访问。

仅在开发模式下可用，生产模式下为空字符串。

类型： string
版本： 添加于 v1.4.4

当你需要在浏览器中建立与 Rsbuild dev server 的 WebSocket 连接时，需要使用这个 token 作为 query 参数。

const { webSocketToken } = environments.web.context;

const webSocketUrl = `ws://localhost:${port}${pathname}?token=${webSocketToken}`;

Environment API

Environment API 提供一些与多环境构建相关的 API。

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

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

context

你可以通过 Environment API 获取和当前环境有关的上下文信息。

类型： EnvironmentContext
示例：

const webManifest = environments.web.context.manifest;

console.log(webManifest.entries);

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 插件注入的资源和内容。

#Environment API

#Environment context

#name

#browserslist

#config

#distPath

#entry

#htmlPaths

#tsconfigPath

#manifest

#webSocketToken

#Environment API

#context

#getStats

#loadBundle

#getTransformedHtml

#Environment API

#Environment context

#name

#browserslist

#config

#distPath

#entry

#htmlPaths

#tsconfigPath

#manifest

#webSocketToken

#Environment API

#context

#getStats

#loadBundle

#getTransformedHtml

Environment API

Environment context

name

browserslist

config

distPath

entry

htmlPaths

tsconfigPath

manifest

webSocketToken

Environment API

context

getStats

loadBundle

getTransformedHtml

Environment API

Environment context

name

browserslist

config

distPath

entry

htmlPaths

tsconfigPath

manifest

webSocketToken

Environment API

context

getStats

loadBundle

getTransformedHtml