react18-dep-compatibility

React 依赖兼容性矩阵

React 18.3.1 与 React 19 兼容所需的最低版本。

在检查某个依赖是否支持目标 React 版本、解决 peer dependency 冲突、决定是升级还是使用 legacy-peer-deps，或评估 react-router v5 到 v6 迁移风险时，请使用此技能。

在 React 升级期间运行 npm install 之前，以及在接受 npm 依赖冲突解决方案之前，请先查看此矩阵，尤其是在并发模式兼容性可能受到影响的情况下。

核心升级目标

Package	React 17（当前）	React 18.3.1（最低）	React 19（最低）	Notes
react	17.x	18.3.1	19.0.0	为 R18 orchestra 精确锁定到 18.3.1
react-dom	17.x	18.3.1	19.0.0	必须与 react 版本完全一致

测试库

Package	React 18 最低	React 19 最低	Notes
@testing-library/react	14.0.0	16.0.0	RTL 13 内部使用 ReactDOM.render - 在 R18 中已失效
@testing-library/jest-dom	6.0.0	6.0.0	v5 可用，但 v6 包含 React 18 matcher 更新
@testing-library/user-event	14.0.0	14.0.0	v13 是同步的，v14 是异步的 - 需要更改 API
jest	27.x	27.x	React 18 需要 jest 27+ 配合 jsdom 16+
jest-environment-jsdom	27.x	27.x	必须与 jest 版本一致

Apollo Client

Package	React 18 最低	React 19 最低	Notes
@apollo/client	3.8.0	3.11.0	3.8 为并发模式添加了 useSyncExternalStore
graphql	15.x	16.x	Apollo 3.8+ peer 要求 graphql 15 或 16

阅读 references/apollo-details.md 了解并发模式问题和 MockedProvider 变更。

Emotion

Package	React 18 最低	React 19 最低	Notes
@emotion/react	11.10.0	11.13.0	11.10 添加了 React 18 并发模式支持
@emotion/styled	11.10.0	11.13.0	必须与 @emotion/react 版本一致
@emotion/cache	11.10.0	11.13.0	如果直接使用

React Router

Package	React 18 最低	React 19 最低	Notes
react-router-dom	v6.0.0	v6.8.0	v5 → v6 是破坏性迁移 - 详见下文
react-router-dom v5	5.3.4（变通方案）	❌ 不支持	参见 legacy peer deps 说明

react-router v5 → v6 是一个独立的迁移冲刺。 阅读 references/router-migration.md。

Redux

Package	React 18 最低	React 19 最低	Notes
react-redux	8.0.0	9.0.0	v7 仅在 R18 legacy root 上可用 - 在并发模式下会失效
redux	4.x	5.x	Redux 本身与框架无关 - react-redux 版本才是关键
@reduxjs/toolkit	1.9.0	2.0.0	RTK 1.9 已针对 React 18 测试

其他常用包

Package	React 18 最低	React 19 最低	Notes
react-query / @tanstack/react-query	4.0.0	5.0.0	v3 不支持并发模式
react-hook-form	7.0.0	7.43.0	v6 存在并发模式问题
formik	2.2.9	2.4.0	v2.2.9 已为 React 18 修补
react-select	5.0.0	5.8.0	v4 与 R18 存在 peer dep 冲突
react-datepicker	4.8.0	6.0.0	v4.8+ 添加了 React 18 支持
react-dnd	16.0.0	16.0.0	v15 及以下存在 R18 并发模式问题
prop-types	任意	任意	独立包 - 不受 React 版本影响

---

冲突解决决策树

npm ls shows peer conflict for package X
         │
         ▼
Does package X have a version that supports React 18?
  YES → npm install X@[min-compatible-version]
  NO  ↓
         │
Is the package critical to the app?
  YES → check GitHub issues for React 18 branch/fork
      → check if maintainer has a PR open
      → last resort: --legacy-peer-deps (document why)
  NO  → consider removing the package

--legacy-peer-deps 规则

仅在以下情况下使用 --legacy-peer-deps：

• 该包没有兼容 React 18 的版本
• 该包仍在积极维护（未被废弃）
• 冲突仅是 peer dep 声明不匹配（而非实际 API 不兼容）

记录每一次 --legacy-peer-deps 的使用，在 package.json 顶部的注释或 MIGRATION.md 文件中说明为何有必要使用。