react-router-dom报错：<Link>不可在<Router>外使用问题排查

Error Invariant failed: You should not use <Link> outside a <Router>

这个报错的核心原因是项目中存在多份react-router/react-router-dom依赖实例，导致App组件中引入的BrowserRouter和Nav组件中引入的Link不属于同一个react-router运行时实例，Link组件无法读取到Router组件通过Context注入的路由上下文，就会抛出“Link不能在Router外使用”的错误。

你把Link直接写在App组件里时不报错，是因为App文件内引入的Link和BrowserRouter来自同一份依赖实例，Context可以正常传递；抽离到独立的Nav组件后，Nav文件内引入的Link来自另一份重复安装的react-router-dom包，自然读不到上层BrowserRouter提供的上下文，触发报错。

• 第一步先确认依赖重复问题：在项目根目录执行对应包管理器的依赖查询命令：
  • npm用户执行：npm ls react-router react-router-dom
  • yarn用户执行：yarn list react-router react-router-dom
  • pnpm用户执行：pnpm ls react-router react-router-dom
    查看输出结果，如果存在两个及以上不同版本/不同路径的react-router、react-router-dom包，就可以确认是多实例问题。
• 常见触发多实例的场景：
  • 手动安装的react-router-dom版本和项目内其他第三方依赖（比如UI组件库、业务组件包）内部依赖的react-router-dom版本不一致，node_modules内被装入了多份代码。
  • 采用monorepo架构时，不同子包内单独安装了版本不一致的react-router相关依赖。
  • 本地调试自定义组件库时使用了link软链，组件库自身的node_modules里装了独立的react-router-dom，和主项目的实例冲突。
• 对应修复方案：
  1. 统一全项目所有位置的react-router、react-router-dom版本，确保版本号完全一致。如果是本地调试组件库的场景，把组件库内的react-router相关依赖移到peerDependencies中，不要作为普通依赖安装，避免重复打包。
  2. 对于第三方依赖引入的重复版本，可以通过包管理器的强制版本统一配置抹平差异：
     • npm 8.3+ 版本在package.json中添加overrides字段：

     {
       "overrides": {
         "react-router": "$react-router",
         "react-router-dom": "$react-router-dom"
       }
     }
     

     • yarn 版本在package.json中添加resolutions字段：

     {
       "resolutions": {
         "react-router": "5.3.4",
         "react-router-dom": "5.3.4"
       }
     }
     

     注意把版本号替换成你项目中实际安装的react-router-dom对应版本。
  3. 配置修改完成后，删除项目下的node_modules文件夹和对应的锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行依赖安装命令即可。

如果检查后确认项目内只有一份react-router依赖实例，再逐一排查以下问题：

• 检查Nav组件文件内的Link引入路径是否正确，有没有误引入本地自定义的同名Link组件、或者写错导入路径拿到了错误的导出。
• 检查构建工具（webpack/vite等）的alias配置，有没有错误把react-router相关依赖指向了错误的文件路径。
• 检查代码里有没有出现循环引用，导致Nav组件加载时Router的Context还未初始化。

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