Modern.js 项目依赖问题排查指南

前言

在使用 Modern.js 框架进行开发时，依赖管理是项目构建和运行的基础环节。本文将针对开发过程中常见的依赖相关问题进行系统梳理，帮助开发者快速定位和解决依赖问题。

如何查看项目中依赖的实际安装版本

使用包管理器命令

不同包管理器提供了查看依赖树的命令，可以帮助开发者确认项目中实际安装的依赖版本。

npm/yarn 项目

npm ls @modern-js/core

执行结果示例：

project
└─┬ @modern-js/app-tools@2.0.0
  └── @modern-js/core@2.0.0

pnpm 项目

pnpm ls @modern-js/core --depth Infinity

执行结果示例：

devDependencies:
@modern-js/app-tools 2.0.0
└── @modern-js/core 2.0.0

技术提示：--depth Infinity 参数可以显示完整的依赖树，对于深层次依赖分析特别有用。

Node.js 版本不兼容问题

常见错误信息

The engine "node" is incompatible with this module.
Expected version ">=16.2.0". Got "12.20.1"

解决方案

Modern.js 推荐使用 Node.js 18.x 及以上版本。如果遇到版本不兼容问题：

1. 使用 nvm 管理 Node.js 版本：

nvm install 18
nvm use 18
nvm default 18

2. 或者使用性能更优的 fnm 工具

版本选择建议：

• 生产环境：推荐使用最新的 LTS 版本（当前为 18.x）
• 开发环境：可以使用较新的非 LTS 版本测试新特性

React 类型定义冲突问题

典型错误

Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/react/index").ReactNode'.

问题原因

这是由于项目中安装了多个不同版本的 @types/react，导致 ReactNode 类型定义冲突。特别是 React 18 与 React 16/17 的类型定义有显著差异。

解决方案

在 package.json 中锁定类型定义版本：

{
  "@types/react": "^17",
  "@types/react-dom": "^17"
}

进阶建议：

• 对于大型项目，建议使用 yarn resolutions 或 pnpm overrides 强制统一依赖版本
• 定期执行 npx modern upgrade 保持 Modern.js 相关依赖版本一致

peerDependencies 警告处理

现象描述

执行 pnpm install 后出现 peerDependencies 警告。

处理建议

1. 大多数情况下这些警告不会影响项目运行，可以忽略
2. 如果警告来自核心依赖，建议检查相关包的兼容性
3. 对于频繁出现的警告，可以在项目根目录添加 .npmrc 文件配置：

strict-peer-dependencies=false

React 版本支持策略

版本要求

React 版本	支持情况	功能限制
≥18.0.0	完全支持	无
17.x	部分支持	无法使用 Streaming SSR 等新特性
16.x	有限支持	仅能使用构建功能，无法使用运行时和服务器能力

升级建议

1. 新项目直接使用 React 18
2. 现有项目逐步迁移到 React 18
3. 关注 Modern.js 的版本更新公告，未来将逐步停止对 React 16/17 的支持

配置类型错误排查

典型错误

Type 'CliPlugin<{}, {}, {}, {}>' is not assignable to type 'CliPlugin<any, {}, {}, {}>'

解决方案

1. 执行版本统一命令：

npx modern upgrade

2. 对于 monorepo 项目：

• 检查各子项目的 Modern.js 依赖版本是否一致
• 在根目录的 package.json 中添加公共依赖

最佳实践建议

1. 依赖锁定：对于生产环境，建议使用 package-lock.json 或 pnpm-lock.yaml 锁定依赖版本
2. 定期更新：每季度检查一次核心依赖的更新情况
3. 版本一致性：确保所有 Modern.js 相关包使用相同主版本号
4. 环境隔离：使用 Docker 或 nvm 保持开发、测试、生产环境的一致性

通过遵循这些指南，开发者可以有效地避免和解决 Modern.js 项目中的大多数依赖相关问题，确保项目稳定运行。