@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/guides/topic-detail/module-federation/ssr.mdx

@@ -0,0 +1,168 @@
+# 服务端渲染
+
+`@module-federation/modern-js-v3` 提供了非常强大的能力，开发者可以非常方便的在 Modern.js 应用中，组合使用 Module Federation 和服务端渲染（SSR）的能力。
+
+## 开启 SSR
+
+我们以 [使用模块联邦](/guides/topic-detail/module-federation/usage) 创建的应用为例，只需要在生产者和消费者上，都添加 `server.ssr` 配置即可：
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream',
+    },
+  },
+});
+```
+
+为更好的性能体验，我们仅支持 Streaming SSR 情况使用这种能力组合。
+
+:::warning
+应用级别模块（使用 `createBridgeComponent` 和 `createRemoteAppComponent` 的模块）在 SSR 场景下采用**分阶段稳定性契约**。
+
+请在 host 和 remote 两侧都显式开启：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'stream',
+      moduleFederationAppSSR: true,
+    },
+  },
+});
+```
+
+建议在生产环境保留远程加载失败的 fallback 边界，并在日志 / 监控中跟踪 fallback 标记。
+:::
+
+## Node SSR 打包兼容性
+
+当开启 Module Federation 并同时开启 `server.ssr` 时，Modern.js 会自动将 Node SSR 构建切换到 Module Federation 兼容模式：
+
+- `target: 'async-node'`
+- `output.module: false`
+- `output.chunkFormat: 'commonjs'`
+- `output.chunkLoading: 'async-node'`
+- `output.library.type: 'commonjs-module'`
+
+这样可以避免 ESM 服务端产物与 `@module-federation/node` 运行时之间的兼容性问题，并保证 host / remote 在 SSR 与 SSG 场景下的 hydration 行为一致。
+
+## Battle-Tested 上线检查清单
+
+在扩大到生产全量流量前，建议覆盖以下场景：
+
+1. Host 与全部 remote 统一使用 `server.ssr.mode: 'stream'` 和同一 MF SSR 契约开关。
+2. `dev` / `build` / `serve` 三种模式都验证通过 happy-path SSR。
+3. 远程不可用场景有明确 fallback 边界，且不会触发服务端崩溃。
+4. 数据获取 timeout 与 contract-error 场景都有确定性降级 UI。
+5. Host/remote 边界上的 trace 与 telemetry 标记可观测。
+6. 灰度发布采用渐进放量并配置明确回滚条件。
+
+## 示例上线场景
+
+1. 基线启用（host + remote）：
+  - host 与 remote 均配置 `server.ssr.mode: 'stream'` 和 `moduleFederationAppSSR: true`。
+  - 验证 SSR HTML 包含 remote shell 标记，且没有 fallback 标记。
+2. remote 不可用降级：
+  - 保持 host 开关开启，停止一个 remote 服务后访问对应远程路由。
+  - 验证响应仍为 `200`、fallback 边界正确渲染、服务端不崩溃。
+3. timeout 与 contract-error 演练：
+  - 在 CI 注入远程/数据延迟响应以及异常 payload。
+  - 验证降级 UI 可确定复现，并产出匹配的 telemetry reason code。
+
+## 数据获取
+
+:::tip
+该能力仍处于分阶段推进中。建议在 CI 中执行上面的检查清单后再扩大流量。
+:::
+
+Module Federation 在新版本中支持了[数据获取](https://module-federation.io/zh/guide/basic/data-fetch/index.html#%E7%AE%80%E4%BB%8B)的能力。每个生产者文件都可以有一个对应的数据获取文件，文件名格式为 `[name].data.ts`。
+
+在 Modern.js 中，数据获取可以配合 SSR 使用。我们以前面章节的 Demo 为例子，创建一个数据获取文件：
+
+```ts title="src/components/Button.data.ts"
+import type { DataFetchParams } from '@module-federation/modern-js-v3/react';
+
+export type Data = {
+  data: string;
+};
+
+export const fetchData = async (params: DataFetchParams): Promise<Data> => {
+  return new Promise(resolve => {
+    setTimeout(() => {
+      resolve({
+        data: `data: ${new Date()}`,
+      });
+    }, 1000);
+  });
+};
+```
+
+在 Button 中，我们从 `Props` 中获取到数据：
+
+```ts title="src/components/Button.tsx"
+import React from 'react';
+import type { Data } from './Button.data';
+
+export const Button = (props: { mfData: Data }) => {
+  const { mfData } = props;
+  return (
+    <button type="button" className="test">
+      Remote Button {mfData?.data}
+    </button>
+  );
+};
+```
+
+## 消费组件
+
+消费者必须使用 [`createLazyComponent`](https://module-federation.io/zh/practice/bridge/react-bridge/load-component.html#createlazycomponent-api-%E5%8F%82%E8%80%83) 的方式加载远程组件，并指定 export 为 'default'。
+
+```tsx title="src/routes/page.tsx"
+import type { JSX } from 'react';
+import { getInstance } from '@module-federation/modern-js-v3/runtime';
+import {
+  ERROR_TYPE,
+  lazyLoadComponentPlugin,
+} from '@module-federation/modern-js-v3/react';
+
+const instance = getInstance();
+instance!.registerPlugins([lazyLoadComponentPlugin()]);
+
+const Button = instance!.createLazyComponent({
+  loader: () => {
+    return import('remote/Button');
+  },
+  loading: 'loading...',
+  export: 'Button', // 这里需要配置为远程组件的 export 名称
+  fallback: ({ error, errorType, dataFetchMapKey }) => {
+    console.error(error);
+    if (errorType === ERROR_TYPE.LOAD_REMOTE) {
+      return <div>load remote failed</div>;
+    }
+    if (errorType === ERROR_TYPE.DATA_FETCH) {
+      return (
+        <div>
+          data fetch failed, the dataFetchMapKey key is: {dataFetchMapKey}
+        </div>
+      );
+    }
+    return <div>error type is unknown</div>;
+  },
+});
+
+const Index = (): JSX.Element => {
+  return (
+    <div>
+      <h1>Basic usage with data fetch</h1>
+      <Button />
+    </div>
+  );
+};
+
+export default Index;
+```

package/docs/zh/guides/topic-detail/module-federation/usage.mdx

@@ -0,0 +1,200 @@
+# 开始使用
+
+在 Modern.js 中使用 Module Federation 我们推荐使用官方插件 `@module-federation/modern-js-v3`。
+
+本章节将会介绍如何通过官方插件搭含生产者应用与消费者应用，我们首先根据 [Modern.js 快速上手](/guides/get-started/quick-start) 创建两个应用。
+
+## 安装插件
+
+完成应用创建后，我们分别为两个项目安装插件：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command="add @module-federation/modern-js-v3" />
+
+## 注册插件
+
+安装插件后，你需要在 `modern.config.js` 中注册插件：
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
+
+export default defineConfig({
+  plugins: [appTools(), moduleFederationPlugin()],
+});
+```
+
+## 生产者导出模块
+
+接下来，我们先修改生产者的代码，导出 Module Federation 模块。
+
+我们创建 `src/components/Button.tsx` 文件，导出一个 Button 组件：
+
+```tsx title="src/components/Button.tsx"
+import React from 'react';
+
+export const Button = () => {
+  return <button type="button">Remote Button</button>;
+};
+```
+
+随后，在项目根目录添加 `module-federation.config.ts`，配置 Module Federation 模块的名称、共享依赖和导出内容：
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'remote',
+  manifest: {
+    filePath: 'static',
+  },
+  filename: 'static/remoteEntry.js',
+  exposes: {
+    './Button': './src/components/Button.tsx',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+:::tip
+在上述代码块中，我们为 Module Federation 导出的 `manifest` 和 `remoteEntry.js` 都设置了 `static` 前缀，这是因为 Modern.js 要求将所有需要暴露的资源都放在 `static/` 目录下，Modern.js 的服务器在生产环境时也只会托管 `static/` 目录。
+:::
+
+另外，我们还需要修改 `modern.config.ts`，为生产者提供一个开发环境的端口，让消费者可以通过此端口访问生产者的资源：
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
+
+export default defineConfig({
+  server: {
+    port: 3051,
+  },
+  plugins: [appTools(), moduleFederationPlugin()],
+});
+```
+
+## 消费者使用模块
+
+现在，我们修改消费者的代码，使用生产者导出的模块。
+
+在项目根目录添加 `module-federation.config.ts`，配置 Module Federation 模块的名称、共享依赖和使用的远程模块：
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js-v3';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@http://localhost:3051/static/mf-manifest.json',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+});
+```
+
+`mf-manifest.json` 是生产者在打包后产出的文件，包含了生产者导出的所有模块信息。
+
+我们创建新的路由文件 `src/routes/remote/page.tsx`，引入生产者模块：
+
+```tsx title="src/routes/remote/page.tsx"
+import React, { Suspense, type JSX } from 'react';
+import { Button } from 'remote/Button';
+
+const Index = (): JSX.Element => {
+  return (
+    <div>
+      <Suspense fallback={<div>Loading...</div>}>
+        <Button />
+      </Suspense>
+    </div>
+  );
+};
+
+export default Index;
+```
+
+此时 `remote/Button` 引入会出现类型错误，这是因为本地没有远程模块的类型。Module Federation 2.0 提供了 [类型提示](https://module-federation.io/zh/guide/basic/type-prompt.html) 的能力，会在生产者构建时自动生成远程模块的类型定义，在消费者构建时自动下载。
+
+为此我们需要在 `tsconfig.json` 中添加新的 `path`，保证类型生效：
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      "*": ["./@mf-types/*"]
+    }
+  }
+}
+```
+
+:::tip
+在消费者中，我们通过 `remote/Button` 来引用远程模块。这里简单介绍下这个路径具体代表了什么，可以先将它抽象成 `[remoteAlias]/[remoteExpose]`。
+
+第一段 `remoteAlias` 是生产者在消费者中的别名，它是消费者 `module-federation.config.ts` 中配置的 `remotes` 字段的 `key`：
+
+```ts
+{
+  remotes: {
+    [remoteAlias]: '[remoteModuleName]@[URL_ADDRESS]',
+  }
+}
+```
+
+这里我们也将远程地址抽象为 `[remoteModuleName]@[URL_ADDRESS]`，`@` 前的部分必须对应生产者的模块名。
+
+第二段 `remoteExpose` 是生产者在 `module-federation.config.ts` 中配置的 `exposes` 字段的 `key`。
+:::
+
+## 启动应用
+
+现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `modern dev` 启动两个应用。
+
+启动后，消费者中对生产者模块的引入，不会再出现抛错，类型已经下载到消费者应用中。
+
+:::note
+修改生产者代码后，消费者会自动拉取生产者的类型。
+:::
+
+访问 `http://localhost:8080/remote`，可以看到页面中已经包含了生产者的远程模块 `Button` 组件。
+
+我们也可以在本地执行 `modern serve` 来模拟生产环境。
+
+因为 Module Federation 插件会自动读取 Modern.js 的 `output.assetPrefix` 配置作为远程模块的访问地址，而该值在生产环境下构建后默认是 `/`。如果不做特殊处理，消费者将从自己的域名下拉取远程模块的入口文件。我们可以添加如下配置：
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { moduleFederationPlugin } from '@module-federation/modern-js-v3';
+
+// https://modernjs.dev/en/configure/app/usage
+export default defineConfig({
+  server: {
+    port: 3051,
+  },
+  output: {
+    // Now this configuration is only used in the local when you run modern serve command.
+    // If you want to deploy the application to the platform, use your own domain name.
+    // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
+    assetPrefix: 'http://127.0.0.1:3051',
+  },
+  plugins: [appTools(), moduleFederationPlugin()],
+});
+```
+
+现在，在生产者中运行 `modern build && MODERN_MF_AUTO_CORS=true modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
+
+:::tip
+在使用 `modern serve` 命令时，需要在启动生产者项目时携带 `MODERN_MF_AUTO_CORS=true` 环境变量，以自动处理跨域问题，确保消费者可以正常访问生产者的远程模块资源。
+:::
+
+上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base)。
+
+## 相关文档
+
+- [Module Federation 官方文档](https://module-federation.io/zh/guide/framework/modernjs.html)

package/docs/zh/guides/troubleshooting/_meta.json

@@ -0,0 +1 @@
+["dependencies", "cli", "builder", "hmr"]

package/docs/zh/guides/troubleshooting/builder.mdx

@@ -0,0 +1,134 @@
+---
+sidebar_position: 3
+---
+
+# 构建相关问题
+
+如果你遇到了构建相关的问题，可以参考当前文档进行排查。
+
+---
+
+### Rsbuild FAQ
+
+Modern.js 内部基于 [Rsbuild](https://v2.rsbuild.rs/) 封装了自身的构建工具，因此你可以直接参考 Rsbuild 的 FAQ 文档：
+
+- [Rsbuild - 功能类问题](https://v2.rsbuild.rs/zh/guide/faq/features)
+- [Rsbuild - 异常类问题](https://v2.rsbuild.rs/zh/guide/faq/exceptions)
+- [Rsbuild - 热更新问题](https://v2.rsbuild.rs/zh/guide/faq/hmr)
+
+---
+
+### 如何查看最终生成的 Rspack 配置?
+
+Modern.js 提供 [inspect 命令](/apis/app/commands.html) 用于查看项目最终生成的 Modern.js 配置以及 Rspack 配置。
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+```
+
+### 在 Monorepo 中引用其他模块，代码没有被正确编译？
+
+出于编译性能的考虑，默认情况下，Modern.js 不会编译 `node_modules` 下的文件，也不会编译当前工程目录外部的文件。
+
+因此，当你引用其他子项目的源代码时，可能会遇到类似 `You may need an additional loader to handle the result of these loaders.` 的报错。
+
+这个问题有以下解决方法：
+
+1. 你可以开启源码构建模式来编译 monorepo 中的其他子项目，参考[「源码构建模式」](/guides/advanced-features/source-build.html)。
+2. 你可以添加 `source.include` 配置项，指定需要额外进行编译的目录或模块，参考 [source.include 用法介绍](/configure/app/source/include.html)。
+3. 你可以预先构建需要引用的子项目，生成对应的构建产物，并在当前项目引用构建产物，而不是引用源代码。
+
+---
+
+### 打开页面后报错，提示 exports is not defined？
+
+如果编译正常，但是打开页面后出现 `exports is not defined` 报错，通常是因为在项目中使用 Babel 编译了一个 CommonJS 模块，导致 Babel 出现异常。
+
+在正常情况下，Modern.js 是不会使用 Babel 来编译 CommonJS 模块的。如果项目中使用了 [source.include](/configure/app/source/include.html) 配置项，则可能会把一些 CommonJS 模块加入到 Babel 编译中。
+
+该问题有两种解决方法：
+
+1. 避免将 CommonJS 模块加入到 Babel 编译中。
+2. 将 Babel 的 `sourceType` 配置项设置为 `unambiguous`。将 `sourceType` 设置为 `unambiguous` 可能会产生一些其他影响，请参考 [Babel 官方文档](https://babeljs.io/docs/en/options#sourcetype)。
+
+---
+
+### 编译时报错 "Error: ES Modules may not assign module.exports or exports.\*, Use ESM export syntax"？
+
+如果编译时出现以下报错，通常也是因为在项目中使用 Babel 编译了一个 CommonJS 模块，解决方法与上述的 `exports is not defined` 问题一致。
+
+```bash
+Error: ES Modules may not assign module.exports or exports.*, Use ESM export syntax, instead: 581
+```
+
+更多信息请参考 issue：[babel#12731](https://github.com/babel/babel/issues/12731)。
+
+---
+
+### 编译进度条卡死，但终端无 Error 日志？
+
+当编译进度条卡死，但终端无 Error 日志时，通常是因为编译过程中出现了异常。在某些情况下，当 Error 被构建工具或其他模块捕获后，错误日志不会被正确输出。最为常见的场景是 Babel 配置出现异常，抛出 Error 后被构建工具捕获，而构建工具在个别情况下吞掉了 Error。
+
+**解决方法：**
+
+如果你修改 Babel 配置后出现此问题，建议检查是否有以下错误用法：
+
+1. 配置了一个不存在的 plugin 或 preset，可能是名称拼写错误，或是未正确安装。
+2. 是否配置了多个 babel-plugin-import，但是没有在数组的第三项声明每一个 babel-plugin-import 的名称。
+
+---
+
+### 从 lodash 中引用类型后出现编译报错？
+
+当你的项目中安装了 `@types/lodash` 包时，你可能会从 `lodash` 中引用一些类型，比如引用 `DebouncedFunc` 类型：
+
+```ts
+import { debounce, DebouncedFunc } from 'lodash';
+```
+
+上述代码会在编译后产生如下报错：
+
+```bash
+SyntaxError: /project/src/index.ts: The 'lodash' method `DebouncedFunc` is not a known module.
+Please report bugs to https://github.com/lodash/babel-plugin-lodash/issues.
+```
+
+这个问题的原因是 Modern.js 默认开启了 [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash) 插件来优化 lodash 产物体积，但 Babel 无法区别「值」和「类型」，导致编译后的代码出现异常。
+
+解决方法是使用 TypeScript 的 `import type` 语法，对 `DebouncedFunc` 类型进行显式声明：
+
+```ts
+import { debounce } from 'lodash';
+import type { DebouncedFunc } from 'lodash';
+```
+
+:::tip
+在任意情况下，我们都推荐使用 `import type` 来引用类型，这对于编译器识别类型会有很大帮助。
+:::
+
+---
+
+### 升级 Modern.js 版本后，检查出新的 TypeScript 类型错误？
+
+Modern.js 优化了 Type Checker 的检查范围。在之前的版本中，Type Checker 只输出 src 目录的类型错误，导致其他目录的类型错误无法被正确输出。
+
+在新版本中，Modern.js 的 Type Checker 对齐了TS-Go native preview 的类型检查范围（即 tsconfig.json 的 `include` 和 `exclude` 字段定义的范围），能够完整输出项目中的类型错误。
+
+如果你希望保持之前的行为，只输出 src 目录的类型错误，可以添加以下配置：
+
+```ts title="modern.config.ts"
+export default {
+  tools: {
+    tsChecker: {
+      issue: {
+        include: [{ file: '**/src/**/*' }],
+      },
+    },
+  },
+};
+```

package/docs/zh/guides/troubleshooting/cli.mdx

@@ -0,0 +1,39 @@
+---
+sidebar_position: 2
+---
+
+# 命令行问题
+
+### 使用 pnpm 时无法正确传递命令行参数？
+
+在使用 pnpm 调用 `package.json` 中的命令时，需要注意参数传递的方式：
+
+- **如果需要传递参数至 pnpm**，需要将参数放到命令前。
+
+例如使用 pnpm `--filter` 参数执行 prepare 命令：
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+- **如果需要传递参数至命令**，需要将参数放到命令后。
+
+例如，在如下 `package.json` 配置中：
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+执行 command 命令时携带参数方式为：
+
+```bash
+pnpm run command --options
+```
+
+:::tip
+Modern.js 要求 Node.js >= 20.19.5，而 pnpm v6 不支持 Node.js 20，因此请使用 pnpm v7 或更高版本。
+:::

package/docs/zh/guides/troubleshooting/dependencies.mdx

@@ -0,0 +1,123 @@
+---
+sidebar_position: 1
+---
+
+# 依赖安装问题
+
+### 如何查看项目里某个依赖实际安装的版本？
+
+可以使用包管理器自带的 `ls` 命令来查看项目里依赖的版本。
+
+下面是一些基本的示例，详细用法请查看各个包管理器的文档。
+
+**npm / yarn**
+
+对于使用 npm 或 yarn 的项目，可以使用 `npm ls` 命令。
+
+比如执行 `npm ls @modern-js/plugin`，可以看到如下结果：
+
+```
+project
+└─┬ @modern-js/app-tools@x.y.z
+  └── @modern-js/plugin@x.y.z
+```
+
+**pnpm**
+
+对于使用 pnpm 的项目，可以使用 `pnpm ls` 命令。
+
+比如执行 `pnpm ls @modern-js/plugin --depth Infinity`，可以看到如下结果：
+
+```
+devDependencies:
+@modern-js/app-tools x.y.z
+└── @modern-js/plugin x.y.z
+```
+
+---
+
+### 安装依赖时提示 The engine "node" is incompatible？
+
+安装依赖时如果出现以下报错提示，说明当前环境使用的 Node.js 版本过低，需要升级 Node.js 到更高版本。
+
+```bash
+The engine "node" is incompatible with this module.
+
+Expected version ">=20.19.5". Got "16.20.1"
+```
+
+Modern.js 要求 Node.js 版本 >= 20.19.5，我们强烈推荐使用最新的 LTS 版本（如 [Node.js 22 LTS](https://nodejs.org/)）以获得最佳体验。
+
+如果当前环境的 Node.js 版本低于上述要求的版本，则可以使用 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 等工具进行版本切换。
+
+下面是使用 nvm 的示例：
+
+```bash
+# 安装 Node.js 22 LTS
+nvm install 22 --lts
+
+# 切换到 Node.js 22
+nvm use 22
+
+# 将 Node.js 22 设置为默认版本
+nvm alias default 22
+```
+
+在本地开发环境推荐使用 [fnm](https://github.com/Schniz/fnm)，它的用法与 nvm 相似，但拥有比 nvm 更好的性能。
+
+---
+
+### 升级依赖后出现 ReactNode 类型错误？
+
+升级项目的依赖后，如果出现以下类型报错，说明项目中安装了错误的 `@types/react` 版本。
+
+```bash
+The types returned by 'render()' are incompatible between these types.
+Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/react/index").ReactNode'.
+Type '{}' is not assignable to type 'ReactNode'.
+```
+
+出现这个问题的原因是 React 18/19 与 React 16/17 中的 ReactNode 类型定义不同，如果项目中出现多个不同 `@types/react` 版本，就会出现 ReactNode 类型冲突，导致以上报错。
+
+解决方法为将项目中的 `@types/react` 和 `@types/react-dom` 锁定在统一的版本上，比如 `v19`。
+
+```json
+{
+  "@types/react": "^19",
+  "@types/react-dom": "^19"
+}
+```
+
+关于锁定依赖版本的方法，请参考 [锁定子依赖](/guides/get-started/upgrade.html#锁定子依赖)。
+
+---
+
+### 执行 pnpm install 之后，控制台出现 peer dependencies 相关 warning？
+
+出现该警告的原因是，某些三方 npm 包声明的 peer dependencies 版本范围与 Modern.js 中安装的版本范围不一致。
+
+绝大多数情况下，peer dependencies 的警告不会影响项目运行，不需要额外进行处理，请忽略相关 warning。
+
+---
+
+### Modern.js 框架最低支持的 React 版本是多少？
+
+**Modern.js 框架要求使用的 React 版本为 >= 18.0.0**。
+
+- **如果使用 Modern.js 的 runtime 能力**（包括 SSR、Streaming SSR、数据加载、路由等），必须使用 React 18 或更高版本。React 16 和 React 17 不再支持。
+- **如果仅使用 Modern.js 的构建能力**（不使用 runtime），理论上可以使用 React 16 或 React 17，但强烈建议升级到 React 18 以上版本以获得最佳体验和完整功能支持。
+
+---
+
+### Modern.js 配置出现类型错误？
+
+```bash
+Type 'CliPlugin<{}, {}, {}, {}>' is not assignable to type 'CliPlugin<any, {}, {}, {}>'.
+  Types of property 'setup' are incompatible.
+```
+
+当你在使用 Modern.js 框架时配置文件出现以上报错，可能是由于 Modern.js 相关包的版本号未统一导致。需要手动将所有 `@modern-js/**` 包的版本统一更新到相同版本。
+
+在 monorepo 中由于不同子项目所用的 Modern.js 框架版本不一致也可能出现以上问题。
+
+关于如何统一升级依赖版本，请参考[版本升级](/guides/get-started/upgrade)文档。