useHistory 与 useNavigate：React Router 版本迁移指南

问题描述

在使用 React Router 进行路由跳转时，开发者常常会遇到以下错误：

Attempted import error: 'useHistory' is not exported from 'react-router-dom'

这个编译时错误通常发生在使用较新版本的 React Router（v6+）时，却使用了 v5 的 useHistory API。错误信息明确表示指定的模块不存在，无法导入。

根本原因

React Router 在 v6 版本中进行了一次重大重构，移除了 useHistory 钩子函数，取而代之的是全新的 useNavigate API。这是一个破坏性变更，导致所有使用旧版本代码在新版本中无法正常工作。

解决方案

根据你的项目需求和版本选择，有以下几种解决方案：

方案一：升级到 React Router v6（推荐）

这是官方推荐的做法，使用新的 useNavigate 钩子替代 useHistory。

// 从 react-router-dom v6 导入 useNavigate
import { useNavigate } from 'react-router-dom';

function MyComponent() {
  const navigate = useNavigate();
  
  const handleClick = () => {
    // 基本导航
    navigate('/home');
    
    // 替换当前历史记录（相当于 v5 的 replace）
    navigate('/home', { replace: true });
    
    // 带状态的导航
    navigate('/home', { state: { from: 'previousPage' } });
  };
  
  return (
    <button onClick={handleClick}>
      跳转到首页
    </button>
  );
}

方案二：保持使用 React Router v5

如果你不想升级到 v6，可以明确指定安装 v5.2.0 或更高版本的 v5 系列：

npm install react-router-dom@5.2.0
# 或
yarn add react-router-dom@5.2.0

这样你可以继续使用 useHistory：

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

function MyComponent() {
  const history = useHistory();
  
  const handleClick = () => {
    history.push('/home');
  };
  
  return (
    <button onClick={handleClick}>
      跳转到首页
    </button>
  );
}

useHistory 到 useNavigate 的迁移指南

版本兼容性

确保你的项目使用的是 react-router-dom v6 或更高版本，否则 useNavigate 将不可用。

基本导航替换

v5 useHistory	v6 useNavigate
history.push('/path')	navigate('/path')
history.replace('/path')	navigate('/path', { replace: true })

历史记录操作替换

v6 中使用数值参数来控制历史记录导航：

// React Router v5
const { go, goBack, goForward } = useHistory();

// React Router v6 等效操作
const navigate = useNavigate();

// 等价操作对照
() => go(-2)      // => () => navigate(-2)
goBack()          // => () => navigate(-1)
goForward()       // => () => navigate(1)
() => go(2)       // => () => navigate(2)

带状态的导航

// v5 方式
history.push('/path', { state: { data: 'value' } });

// v6 方式
navigate('/path', { 
  state: { 
    data: 'value' 
  } 
});

完整示例

以下是一个完整的表单提交后跳转的示例：

import React, { useState } from 'react';
import { useNavigate } from 'react-router-dom';

function SignupForm() {
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    password: ''
  });
  
  const navigate = useNavigate();

  async function handleSubmit(event) {
    event.preventDefault();
    
    try {
      // 发送表单数据到API
      const response = await fetch('/api/register', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(formData)
      });
      
      const result = await response.json();
      
      // 保存用户数据到本地存储
      localStorage.setItem('user', JSON.stringify(result));
      
      // 导航到成功页面，并替换历史记录
      navigate('/success', { 
        replace: true,
        state: { user: result }
      });
    } catch (error) {
      console.error('注册失败:', error);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* 表单字段 */}
      <button type="submit">注册</button>
    </form>
  );
}

总结

• React Router v6 用 useNavigate 替换了 v5 的 useHistory
• 如果你需要使用 v5 的 API，请安装 react-router-dom@5.2.0
• 迁移到 v6 时，使用数值参数进行历史记录导航（前进/后退）
• navigate 函数的第二个参数可以配置替换行为和传递状态数据

选择适合你项目需求的方案，确保路由功能正常工作。对于新项目，推荐直接使用 v6 版本的 API，因为它提供了更简洁和一致的路由体验。