monorepo项目升级react-router-dom v6后报TS2786错误如何解决？

报错信息 #

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

该报错在将子项目dashboard的react-router-dom升级到v6版本后触发，此前尝试在根目录package.json配置resolutions、optionalDependencies强制统一@types/react@17.0.47、@types/react-dom@17.0.17版本未生效。

问题根因 #

• 子项目dashboard单独声明react-router-dom@6依赖，同时子项目依赖的react-scripts@4.0.3、错装的@types/react-router-dom@5.3.3会在子项目node_modules下拉取独立版本的@types/react，和根目录锁定的类型版本形成多副本。TypeScript 识别到两份来源不同的React类型定义时，会直接判定类型不兼容，抛出TS2786错误。
• resolutions字段仅对Yarn包管理器生效，使用npm/pnpm时该配置完全不生效，无法实现全仓依赖版本强制统一。
• optionalDependencies字段仅用于声明可选安装的依赖，安装失败不会阻断流程，完全不具备全局版本强制能力，配置该字段对解决类型冲突无任何作用。
• 子项目未显式声明@types/react、@types/react-dom依赖，TS类型查找时会优先命中嵌套依赖中的版本，进一步放大了多副本类型冲突的概率。

可落地修复步骤 #

1. 清理全仓冗余依赖缓存
   在项目根目录执行命令删除所有node_modules目录和锁文件，避免旧缓存干扰依赖解析：

   # 删除根目录和子项目的node_modules
   rm -rf node_modules apps/dashboard/node_modules
   # 根据所用包管理器删除对应锁文件
   # Yarn用户执行 rm -f yarn.lock
   # npm用户执行 rm -f package-lock.json
   # pnpm用户执行 rm -f pnpm-lock.yaml
   

2. 修正package.json配置
   • 删除子项目dashboard/package.json devDependencies下的@types/react-router-dom@5.3.3：react-router-dom v6版本已内置完整TS类型定义，无需额外安装v5版本的类型包，版本错配是本次报错的核心触发点。
   • 删除子项目dependencies下重复声明的react-router-dom依赖，统一在根目录管理该依赖版本，避免子目录拉取重复依赖副本。
   • 根目录版本锁定配置适配所用包管理器：
     • 若使用Yarn，保留原有resolutions字段即可，删除optionalDependencies中关于@types/react、@types/react-dom的声明。
     • 若使用npm（v8.3.0及以上版本），删除resolutions字段，新增overrides字段做全局版本锁定：

       {
         "overrides": {
           "@types/react": "17.0.47",
           "@types/react-dom": "17.0.17"
         }
       }
       

     • 若使用pnpm，删除resolutions字段，在package.json中新增pnpm配置块做版本锁定：

       {
         "pnpm": {
           "overrides": {
             "@types/react": "17.0.47",
             "@types/react-dom": "17.0.17"
           }
         }
       }
       

   • 在子项目dashboard/package.json的devDependencies中显式添加和根目录版本完全一致的@types/react、@types/react-dom，避免子项目依赖解析时拉取独立版本：

     {
       "devDependencies": {
         "@types/react": "17.0.47",
         "@types/react-dom": "17.0.17",
         "@types/qrcode": "1.4.2",
         "@typescript-eslint/eslint-plugin": "5.3.1",
         "@typescript-eslint/parser": "5.3.1",
         "eslint": "7.32.0",
         "typescript": "4.6.4"
       }
     }
     

3. 修正TypeScript基础配置
   在Nx monorepo默认的根目录tsconfig.base.json中增加路径映射，强制全仓所有包引用同一份React及类型定义，从根源上杜绝多副本类型冲突：

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "react": ["./node_modules/react"],
         "react-dom": ["./node_modules/react-dom"],
         "@types/react": ["./node_modules/@types/react"],
         "@types/react-dom": ["./node_modules/@types/react-dom"]
       }
     }
   }
   

4. 重新安装依赖并验证
   回到根目录执行对应包管理器的安装命令：

   # Yarn用户
   yarn install
   # npm用户
   npm install
   # pnpm用户
   pnpm install
   

   安装完成后重启TS服务：VS Code下按Cmd+Shift+P（macOS）/Ctrl+Shift+P（Windows），选择TypeScript: Restart TS Server，等待服务加载完成后TS2786报错会完全消失。

内容的提问来源于stack exchange，提问作者Khant