React Router v5 升级到 v6 完全指南

React Router v5 升级到 v6 完全指南

react-router 项目地址: https://gitcode.com/gh_mirrors/react/react-router

前言

React Router 作为 React 生态中最流行的路由解决方案，在 v6 版本中带来了许多重大改进。本文将详细介绍如何从 v5 版本平滑升级到 v6 版本，涵盖所有关键变更点和最佳实践。

为什么需要升级？

React Router v6 相比 v5 有以下显著优势：

1. 更简洁直观的 API 设计
2. 全面拥抱 React Hooks
3. 更智能的路由匹配算法
4. 原生支持嵌套路由配置
5. 更小的包体积

升级路径规划

为了确保升级过程平稳可控，建议按照以下步骤进行：

1. 首先确保 React 版本 ≥16.8
2. 升级到 React Router v5.1 并完成相关改造
3. 最后升级到 v6 版本

第一步：升级 React 到 16.8+

由于 v6 大量使用 Hooks，必须确保 React 版本 ≥16.8。好消息是 v5 兼容 React ≥15，所以可以先单独升级 React。

npm install react@^16.8 react-dom@^16.8

完成此步骤后，建议先部署测试，确保基础功能正常。

第二步：升级到 React Router v5.1

v5.1 是通往 v6 的重要过渡版本，主要变化是推荐使用 <Route children> 替代 <Route component> 和 <Route render>。

改造示例

v5 及之前版本写法：

<Route path="/users/:id" component={User} />
// 或
<Route 
  path="/users/:id" 
  render={({ match }) => <User id={match.params.id} />} 
/>

v5.1 推荐写法：

<Route path="/users/:id">
  <User />
</Route>
// 或使用命名属性
<Route path="/users/:id" children={<User />} />

在组件内部使用 useParams 获取参数：

function User() {
  let { id } = useParams();
  // ...
}

其他必要改造

1. 移除 <Switch> 内部的 <Redirect>

   // 改造前
   <Switch>
     <Redirect from="about" to="about-us" />
   </Switch>
   
   // 改造后
   <Switch>
     <Route path="about" render={() => <Redirect to="about-us" />} />
   </Switch>
   

2. 重构自定义 Route 组件

   • 将任何非标准 <Route> 的自定义路由组件转换为标准形式

完成 v5.1 改造后，再次测试部署确保一切正常。

第三步：升级到 React Router v6

安装 v6

npm install react-router-dom@6
# React Native 应用使用
npm install react-router-native@6

可以移除项目中的 history 依赖，因为它现在是 v6 的内部依赖。

核心变更点

1. <Switch> 升级为 <Routes>

v6 的 <Routes> 相比 v5 的 <Switch> 有以下优势：

• 所有路由和链接都是相对的
• 基于最佳匹配而非顺序匹配
• 支持集中式嵌套路由配置

改造示例：

v5 写法：

<Switch>
  <Route exact path="/" component={Home} />
  <Route path="/users" component={Users} />
</Switch>

v6 写法：

<Routes>
  <Route path="/" element={<Home />} />
  <Route path="users" element={<Users />} />
</Routes>

2. 相对路径和链接

v6 中路径和链接自动相对于父路由：

// v5 需要手动拼接路径
<Link to={`${match.url}/me`}>My Profile</Link>
<Route path={`${match.path}/me`} component={OwnUserProfile} />

// v6 自动相对
<Link to="me">My Profile</Link>
<Route path="me" element={<OwnUserProfile />} />

3. 嵌套路由配置

v6 支持更优雅的嵌套路由：

<Routes>
  <Route path="users" element={<Users />}>
    <Route path=":id" element={<UserProfile />} />
    <Route path="me" element={<OwnUserProfile />} />
  </Route>
</Routes>

// Users 组件中需要渲染 <Outlet/> 来显示子路由
function Users() {
  return (
    <div>
      <nav>{/* 链接 */}</nav>
      <Outlet />
    </div>
  );
}

4. 路由路径模式变更

v6 使用更简单的路径语法：

• 支持 :id 形式参数
• * 通配符只能用在路径末尾
• 移除了正则表达式风格的模式

有效路径示例：

/users/:id
/files/*
/files/:id/*

不再支持的路径：

/users/:id?       // 可选参数
/tweets/:id(\d+)  // 正则约束

5. 导航变更

v6 使用新的 useNavigate 替代 useHistory：

// v5
let history = useHistory();
history.push("/home");

// v6
let navigate = useNavigate();
navigate("/home");

6. 其他重要变更

• exact 属性已移除，默认就是精确匹配
• strict 属性已移除，尾部斜杠总是被忽略
• <Route children> 专用于嵌套路由，使用 element 属性指定渲染内容

升级策略建议

对于大型项目，推荐使用官方提供的向后兼容包，允许 v5 和 v6 并行运行，逐步迁移。对于小型项目，可以按照本文指导一次性完成升级。

常见问题解决

1. 如何处理重定向？

   • 服务端重定向：推荐在服务器配置
   • 客户端重定向：使用 <Navigate> 组件

2. 如何访问路由参数？

   // v6 统一使用 useParams
   let { id } = useParams();
   

3. 如何获取当前路由信息？

   // 使用 useLocation
   let location = useLocation();
   

总结

React Router v6 通过简化 API、拥抱 Hooks 和提供更智能的路由匹配，带来了更好的开发体验。虽然升级过程需要一些工作量，但长期收益显著。按照本文的渐进式升级路径，可以最大限度地降低升级风险。

react-router 项目地址: https://gitcode.com/gh_mirrors/react/react-router