React Router v6 嵌套路由不渲染？排查与修复实战

快速答案

• 核心结论：React Router v6 嵌套路由不渲染的绝大多数原因是父路由组件缺少 <Outlet /> 组件，或子路由路径使用了绝对路径（如 /child）而非相对路径（如 child）。
• 第一检查项：打开父路由组件，确认已从 react-router-dom 导入 Outlet，并在 JSX 中渲染了 <Outlet />。
• 最小修复方案：在父组件中添加 <Outlet />，并将子路由 path 改为相对路径（去掉开头的 /）。
• 适用版本：React Router v6.0.0 及以上版本（v6.4+ 支持 data router，但嵌套路由机制不变）。
• 边界注意：如果使用 createBrowserRouter 等 data API，嵌套路由定义在 children 数组中，父路由组件仍需渲染 <Outlet />。

它解决什么问题

React Router v6 的嵌套路由机制允许你在一个父路由下定义多个子路由，子路由的组件会在父路由组件的 <Outlet /> 位置渲染。这种模式天然支持共享布局（如页眉、侧边栏、页脚），无需手动管理组件状态。

但许多开发者（尤其是从 v5 迁移过来的）会遇到子路由不渲染、页面空白或 404 的问题。本文直接给出根因分析和可复现的修复步骤。

核心配置与参数说明

嵌套路由的两种定义方式

关键参数

与 React Router v5 的对比

v6 的亮点：嵌套路由通过 <Outlet /> 天然支持布局复用，无需额外状态管理，代码更简洁。

常见报错与排查

错误 1：子路由组件不渲染，页面空白

根因：父路由组件没有渲染 <Outlet />。

修复：

JSX
import { Outlet } from 'react-router-dom';

function Parent() {
  return (
    <div>
      <h1>父页面</h1>
      <Outlet /> {/* 必须添加这一行 */}
    </div>
  );
}

错误 2：路由路径匹配错误，导航到子路由时显示 404

根因：子路由的 path 使用了绝对路径（如 /child），而不是相对路径（如 child）。

修复：

JSX
// 错误：使用绝对路径
<Route path="parent" element={<Parent />}>
  <Route path="/child" element={<Child />} /> {/* 这里会匹配 /child，而不是 /parent/child */}
</Route>

// 正确：使用相对路径
<Route path="parent" element={<Parent />}>
  <Route path="child" element={<Child />} /> {/* 匹配 /parent/child */}
</Route>

错误 3：使用 useParams() 获取不到参数

根因：父路由和子路由的参数名称冲突（如都使用 :id），导致子路由的参数被覆盖。

修复：

JSX
// 父路由
<Route path="user/:userId" element={<User />}>
  {/* 子路由使用不同的参数名 */}
  <Route path="post/:postId" element={<Post />} />
</Route>

// 在 Post 组件中
import { useParams } from 'react-router-dom';
function Post() {
  const { userId, postId } = useParams(); // 两个参数都能获取
}

错误 4：路由切换时组件状态丢失

根因：React Router v6 默认会卸载并重新挂载路由组件，导致状态丢失。

修复：使用 <Routes> 包裹所有路由，并确保每个路由组件有唯一的 key 属性，或使用 React.memo 避免不必要的重新渲染。

常见问题 FAQ

Q: 为什么我的嵌套路由在 React Router v6 中不渲染，即使我正确导入了 <Outlet />？

A: 最常见的原因是父路由的 element 属性没有正确渲染 <Outlet />。请确保在父路由的组件中，<Outlet /> 被放置在 JSX 中你想要子路由显示的位置。另外，检查路由定义是否使用了绝对路径（如 /parent/child），v6 中嵌套路由应使用相对路径（如 child）。

Q: 如何在 React Router v6 中实现多级嵌套路由（如 /parent/child/grandchild）？

A: 只需在父路由组件中渲染 <Outlet />，然后在父路由的 <Route> 内部继续嵌套子 <Route>。例如：

JSX
<Route path="parent" element={<Parent />}>
  <Route path="child" element={<Child />}>
    <Route path="grandchild" element={<Grandchild />} />
  </Route>
</Route>

每个层级的组件都需要渲染 <Outlet />。

Q: 从 React Router v5 迁移到 v6，嵌套路由的配置有什么关键变化？

A: v5 使用 <Switch> 和 <Route> 的 component 属性，v6 改用 <Routes> 和 <Route> 的 element 属性。v5 中嵌套路由需要手动渲染组件，v6 通过 <Outlet /> 自动渲染。v6 还移除了 exact 属性，路由匹配默认是精确的，且路径默认是相对路径。

生产环境实践与注意事项

1. 确保所有父路由组件都包含 <Outlet />：这是最常见的遗漏点，建议在创建父组件时立即添加 <Outlet /> 占位符。
2. 避免过度嵌套：在大型应用中，超过 3 层的嵌套可能导致性能问题，建议合理拆分路由层级，或使用布局组件替代深层嵌套。
3. 路径参数安全：避免在路由路径中直接暴露敏感信息（如用户ID），应使用加密或哈希处理后再作为参数传递。
4. 使用 useParams() 时注意参数名冲突：父路由和子路由的参数名应保持唯一，避免覆盖。
5. v6.4+ 的 data router：如果使用 createBrowserRouter，嵌套路由定义在 children 数组中，父组件仍需渲染 <Outlet />，且路由路径规则与声明式嵌套一致。

注意：本文基于 React Router v6 的通用机制撰写。具体版本的行为差异（如 v6.0 与 v6.4 的 data API）请以 React Router 官方文档 为准。