fix(rsbuild-plugin): support app SSR node target with custom environment (#4427)

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

Author: ScriptedAlchemy

.changeset/quick-forks-wonder.md

@@ -0,0 +1,5 @@
+---
+'@module-federation/rsbuild-plugin': patch
+---
+
+Fix app-mode `target: 'node'` handling to respect custom `environment` names, improve missing-environment errors, auto-detect default environment names by caller/tooling when `environment` is omitted, and ensure selected node-target environments still receive federation plugin injection for commonjs-like SSR outputs.

apps/website-new/docs/en/guide/build-plugins/plugins-rsbuild.mdx

@@ -92,7 +92,10 @@ If you need to use the Module Federation runtime capabilities, please install [@
 export declare const pluginModuleFederation: (moduleFederationOptions: ModuleFederationOptions, rsbuildOptions?: RSBUILD_PLUGIN_OPTIONS) => RsbuildPlugin;
 
 type RSBUILD_PLUGIN_OPTIONS = {
+  target?: 'web' | 'node' | 'dual';
   ssr?: boolean;
+  ssrDir?: string;
+  environment?: string;
 }
 ```
 
@@ -109,7 +112,7 @@ Additional configuration for the Rsbuild plugin.
 
 :::tip
 
-Only supported when used as a global plugin in Rslib.
+`target: 'dual'` is only supported when used as a global plugin in Rslib/Rspress.
 
 :::
 
@@ -120,6 +123,46 @@ Used to specify the target runtime environment for the output. When set to `dual
 
 After generating SSR output with `target: 'dual'`, you can refer to [Create a Modern.js Consumer](../../../practice/frameworks/modern/index), create a consumer, and integrate the corresponding Rslib SSR producer for development.
 
+For Rsbuild app SSR, use `target: 'node'` with `environment` to apply Module Federation to a specific app environment.
+
+```ts title='rsbuild.config.ts'
+import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
+import { defineConfig } from '@rsbuild/core';
+
+export default defineConfig({
+  environments: {
+    client: {},
+    ssr: {},
+  },
+  plugins: [
+    pluginModuleFederation(
+      {
+        name: 'host',
+        remotes: {
+          remote: 'remote@http://localhost:3001/mf-manifest.json',
+        },
+      },
+      {
+        target: 'node',
+        environment: 'ssr',
+      },
+    ),
+  ],
+});
+```
+
+#### environment
+
+* Type: `string`
+* Default: auto-detected by caller/tooling:
+  * Rslib: `'mf'`
+  * Rsbuild app + `target: 'web'`: `'web'`
+  * Rsbuild app + `target: 'node'`: `'node'`
+  * Rspress + `target: 'web'`: `'web'`
+  * Rspress + `target: 'node'`: `'node'`
+
+Environment name used by `target: 'node'` to select which environment config receives Node-target federation behavior.
+
 
 #### ssr
 

apps/website-new/docs/zh/guide/build-plugins/plugins-rsbuild.mdx

@@ -92,7 +92,10 @@ export default defineConfig({
 export declare const pluginModuleFederation: (moduleFederationOptions: ModuleFederationOptions, rsbuildOptions?: RSBUILD_PLUGIN_OPTIONS) => RsbuildPlugin;
 
 type RSBUILD_PLUGIN_OPTIONS = {
+  target?: 'web' | 'node' | 'dual';
   ssr?: boolean;
+  ssrDir?: string;
+  environment?: string;
 }
 ```
 
@@ -108,7 +111,7 @@ Rsbuild 插件额外配置。
 
 :::tip
 
-仅支持 Rslib 全局插件。
+`target: 'dual'` 仅支持 Rslib/Rspress 全局插件。
 
 :::
 
@@ -119,6 +122,46 @@ Rsbuild 插件额外配置。
 
 使用 `target: 'dual'` 生成 SSR 产物后，可参考 [创建 Modern.js 消费者](../../../practice/frameworks/modern/index) 创建消费者，并接入对应的 Rslib SSR 生产者进行开发。
 
+对于 Rsbuild App 的 SSR，可使用 `target: 'node'` + `environment`，将 Module Federation 应用到指定环境。
+
+```ts title='rsbuild.config.ts'
+import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
+import { defineConfig } from '@rsbuild/core';
+
+export default defineConfig({
+  environments: {
+    client: {},
+    ssr: {},
+  },
+  plugins: [
+    pluginModuleFederation(
+      {
+        name: 'host',
+        remotes: {
+          remote: 'remote@http://localhost:3001/mf-manifest.json',
+        },
+      },
+      {
+        target: 'node',
+        environment: 'ssr',
+      },
+    ),
+  ],
+});
+```
+
+#### environment
+
+* 类型：`string`
+* 默认值：按调用方/工具自动推断：
+  * Rslib：`'mf'`
+  * Rsbuild App + `target: 'web'`：`'web'`
+  * Rsbuild App + `target: 'node'`：`'node'`
+  * Rspress + `target: 'web'`：`'web'`
+  * Rspress + `target: 'node'`：`'node'`
+
+在 `target: 'node'` 下用于指定要应用 Node Federation 行为的环境名称。
+
 
 #### ssr
 

packages/rsbuild-plugin/README.md

@@ -34,6 +34,53 @@ export default defineConfig({
 });
 ```
 
+### Rsbuild App SSR (Node target with custom environment)
+
+Use `target: 'node'` with an explicit `environment` to apply federation to a
+specific Rsbuild app environment (for example `ssr`).
+
+```ts
+import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
+import { defineConfig } from '@rsbuild/core';
+
+export default defineConfig({
+  environments: {
+    client: {},
+    ssr: {},
+  },
+  plugins: [
+    pluginModuleFederation(
+      {
+        name: 'host',
+        remotes: {
+          remote: 'remote@http://localhost:3001/mf-manifest.json',
+        },
+      },
+      {
+        target: 'node',
+        environment: 'ssr',
+      },
+    ),
+  ],
+});
+```
+
+`target: 'dual'` support remains scoped to Rslib/Rspress workflows.
+
+### Default environment detection
+
+If `environment` is omitted, the plugin will choose a default per tool:
+
+- **Rslib**: `mf`
+- **Rsbuild app**:
+  - `target: 'web'` → `web`
+  - `target: 'node'` → `node`
+- **Rspress**:
+  - `target: 'web'` → `web`
+  - `target: 'node'` → `node`
+
+You can still override with `environment` when your project uses custom names.
+
 ### Rslib Module
 
 ```js