> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 依赖安装问题

### 如何查看项目里某个依赖实际安装的版本？

可以使用包管理器自带的 `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"
}
```

关于锁定依赖版本的方法，请参考 [锁定子依赖](/zh/guides/get-started/upgrade.md#锁定子依赖)。

***

### 执行 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 框架版本不一致也可能出现以上问题。

关于如何统一升级依赖版本，请参考[版本升级](/zh/guides/get-started/upgrade.md)文档。