docs: add modifyEnvironmentConfig hook (#2756)

Co-authored-by: neverland <[email protected]>

website/docs/en/plugins/dev/hooks.mdx

@@ -194,6 +194,71 @@ const myPlugin = () => ({
 });
 ```
 
+### modifyEnvironmentConfig
+
+
+Modify the Rsbuild configuration of a specific environment.
+
+In the callback function, the config object in the parameters has already been merged with the common Rsbuild configuration. You can directly modify this config object, or you can return a new object to replace it.
+
+- **Type:**
+
+```ts
+type ModifyEnvironmentConfigUtils = {
+  /** Current environment name */
+  name: string;
+  mergeEnvironmentConfig: (
+    ...configs: EnvironmentConfig[]
+  ) => EnvironmentConfig;
+};
+
+function ModifyEnvironmentConfig(
+  callback: (
+    config: EnvironmentConfig,
+    utils: ModifyEnvironmentConfigUtils,
+  ) => MaybePromise<EnvironmentConfig | void>,
+): void;
+```
+
+- **Example:** Set a default value for the Rsbuild config of a specified environment:
+
+```ts
+const myPlugin = () => ({
+  setup: (api) => {
+    api.modifyEnvironmentConfig((config, { name }) => {
+      if (name !== 'web') {
+        return config;
+      }
+      config.html ||= {};
+      config.html.title = 'My Default Title';
+    });
+  },
+});
+```
+
+- **Example:** Using `mergeEnvironmentConfig` to merge config objects, and return the merged object.
+
+```ts
+import type { EnvironmentConfig } from '@rsbuild/core';
+
+const myPlugin = () => ({
+  setup: (api) => {
+    api.modifyEnvironmentConfig((userConfig, { mergeEnvironmentConfig }) => {
+      const extraConfig: EnvironmentConfig = {
+        source: {
+          // ...
+        },
+        output: {
+          // ...
+        },
+      };
+
+      return mergeEnvironmentConfig(userConfig, extraConfig);
+    });
+  },
+});
+```
+
 ### modifyRspackConfig
 
 To modify the final Rspack config object, you can directly modify the config object, or return a new object to replace the previous object.

website/docs/zh/plugins/dev/hooks.mdx

@@ -193,6 +193,70 @@ const myPlugin = () => ({
 });
 ```
 
+### modifyEnvironmentConfig
+
+修改特定 environment 的 Rsbuild 配置。
+
+在回调函数中，入参里的 config 对象已经合并了公共的 Rsbuild 配置，你可以直接修改这个 config 对象，也可以返回一个新的对象来替换它。
+
+- **类型：**
+
+```ts
+type ModifyEnvironmentConfigUtils = {
+  /** 当前 environment 名称 */
+  name: string;
+  mergeEnvironmentConfig: (
+    ...configs: EnvironmentConfig[]
+  ) => EnvironmentConfig;
+};
+
+function ModifyEnvironmentConfig(
+  callback: (
+    config: EnvironmentConfig,
+    utils: ModifyEnvironmentConfigUtils,
+  ) => MaybePromise<EnvironmentConfig | void>,
+): void;
+```
+
+- **示例：** 为指定 environment 的 Rsbuild config 设置一个默认值：
+
+```ts
+const myPlugin = () => ({
+  setup: (api) => {
+    api.modifyEnvironmentConfig((config, { name }) => {
+      if (name !== 'web') {
+        return config;
+      }
+      config.html ||= {};
+      config.html.title = 'My Default Title';
+    });
+  },
+});
+```
+
+- **示例：** 通过 `mergeEnvironmentConfig` 合并配置多个对象，并返回合并后的对象。
+
+```ts
+import type { EnvironmentConfig } from '@rsbuild/core';
+
+const myPlugin = () => ({
+  setup: (api) => {
+    api.modifyEnvironmentConfig((userConfig, { mergeEnvironmentConfig }) => {
+      const extraConfig: EnvironmentConfig = {
+        source: {
+          // ...
+        },
+        output: {
+          // ...
+        },
+      };
+
+      return mergeEnvironmentConfig(userConfig, extraConfig);
+    });
+  },
+});
+```
+
 ### modifyRspackConfig
 
 修改最终的 Rspack 配置对象，你可以直接修改传入的 config 对象，也可以返回一个新的对象来替换传入的对象。