React Router v7 测试环境下 useNavigate 失效问题分析与解决方案

问题背景

在使用 React Router v7.0.1 时，开发者在测试环境中遇到了一个特定问题：当通过 React Testing Library 运行测试时，useNavigate 钩子会抛出错误提示"useNavigate() may be used only in the context of a component"。这个问题在 v6.28.0 版本中并不存在，但在升级到 v7.0.1 后开始出现。

问题表现

该问题具有以下特征：

1. 仅出现在测试环境中，生产环境和开发环境运行正常
2. 无论使用 createMemoryRouter 还是 createBrowserRouter 都会出现
3. 错误表明路由上下文未被正确提供，尽管组件确实被包裹在 Router 组件中

根本原因

经过分析，问题的根源在于 React Router v7 的模块导入方式发生了变化。在 v7 版本中，RouterProvider 应该从 react-router 包导入，而不是从 react-router-dom 导入。这种变化是为了更好地分离核心路由逻辑和 DOM 特定实现。

解决方案

要解决这个问题，开发者需要做以下修改：

1. 将 RouterProvider 的导入语句从：

import { RouterProvider } from 'react-router-dom';

改为：

import { RouterProvider } from 'react-router';

2. 确保测试环境中的路由配置正确，例如：

const router = createMemoryRouter(routes);
render(<RouterProvider router={router} />);

注意事项

1. 虽然从 react-router 导入解决了测试问题，但需要注意这可能会影响某些特定功能，如使用 flushSync: true 选项进行导航时，会提示需要从 react-router/dom 导入。

2. 对于新项目，建议直接使用 react-router 包中的 RouterProvider。

3. 对于现有项目升级，建议按照以下步骤进行：

   • 先升级到 v7 版本（保持原有导入方式）
   • 然后修改导入语句
   • 最后可以移除对 react-router-dom 的依赖（如果不再需要其特定功能）

版本兼容性说明

这个问题凸显了 React Router v7 在模块组织上的一个重要变化。v7 版本更加明确地区分了核心路由逻辑和 DOM 特定实现，这种架构上的改进虽然带来了更好的模块分离，但也需要开发者在升级时注意相应的导入方式调整。

对于测试环境特别需要注意，因为测试运行器（如 Jest）通常使用 jsdom 模拟浏览器环境，这种情况下从 react-router-dom 导入可能会导致意外的行为。