React从入门到出门第五章 React Router 配置与原理初探

大家好～前面我们已经掌握了 React 19 的组件、Hooks、状态管理等核心基础，今天咱们聚焦 React 应用开发中的另一个关键模块------路由管理。

在单页应用（SPA）中，路由是实现"页面切换"的核心：它能让我们在不刷新浏览器的前提下，根据 URL 路径展示不同的组件，模拟多页面应用的体验。React 官方并未提供路由解决方案，社区中最主流的就是 React Router，而 React 19 适配的最新稳定版本是 React Router v7（目前常用的是 v6.22+，v7 为后续主力版本，API 基本兼容 v6 并做了优化）。

很多新手在使用 React Router 时，只会照搬文档配置路由，却不理解"URL 变化如何触发组件切换""路由参数如何传递"等底层逻辑。今天这篇文章，我们就从"实战配置"到"原理拆解"，用完整的代码示例+直观的图例，把 React Router v7 的核心用法和工作原理讲透，让你既能快速上手开发，也能知其所以然～

一、前置准备：React Router v7 环境搭建

在开始之前，我们先完成 React Router v7 的环境搭建。React Router 分为多个包，核心包有 3 个，根据应用场景选择安装：

react-router：核心路由逻辑（与框架无关，提供路由核心 API）；
react-router-dom：用于浏览器环境的路由实现（最常用，提供、等 DOM 相关组件）；
react-router-native：用于 React Native 环境的路由实现（移动端开发用）。

我们以浏览器环境为例，安装核心依赖：

perl 复制代码

# npm 安装
npm install react-router-dom@latest

# yarn 安装
yarn add react-router-dom@latest

# pnpm 安装
pnpm add react-router-dom@latest

安装完成后，我们就可以开始配置路由了。

二、React Router v7 核心路由配置方式

React Router v7 的路由配置方式主要有两种：声明式配置（JSX 标签） 和 编程式配置（数组配置+useRoutes） 。声明式配置直观简单，适合简单应用；编程式配置更灵活，适合复杂应用（如路由权限控制、动态路由）。我们分别通过实战案例讲解。

1. 基础声明式配置：实现简单页面切换

声明式配置是 React Router 最基础的用法，通过核心组件组合实现路由功能。先了解几个核心组件的作用：

<BrowserRouter>：路由根组件，包裹整个应用，提供路由核心上下文（如历史记录、当前路径等）；
<Routes>：路由容器，用于包裹组件，会根据 URL 路径匹配唯一的并渲染对应的组件；
<Route path="" element={}>：路由规则，path 是 URL 路径，element 是路径匹配成功后渲染的组件；
<Link to="">：路由跳转组件，类似 HTML 的标签，但不会刷新页面（通过修改 URL 实现跳转）；
* <Outlet />：嵌套路由的占位符，用于渲染子路由对应的组件。

[#### 实战案例 1：基础路由（首页、关于页、404 页）

javascript 复制代码

// src/App.jsx
import { BrowserRouter as Router, Routes, Route, Link } from 'react-router-dom';

// 页面组件
const Home = () => <h2>首页：React Router v7 实战</h2>;
const About = () => <h2>关于页：专注 React 19 路由管理</h2>;
// 404 页面（path="*" 匹配所有未定义的路径）
const NotFound = () => <h2>404：页面不存在</h2>;

function App() {
return (
{/* 路由根组件，必须包裹所有路由相关组件 */}
<Router>
<div style={{ padding: '20px' }}>
{/* 导航栏：通过 Link 组件实现路由跳转 */}
<nav style={{ marginBottom: '20px', display: 'flex', gap: '20px' }}>
<Link to="/" style={{ textDecoration: 'none' }}>首页</Link>
<Link to="/about" style={{ textDecoration: 'none' }}>关于页</Link>
</nav>

{/* 路由容器：匹配 URL 并渲染对应组件 */}
<Routes>
{/* 首页：path="/" 匹配根路径 */}
<Route path="/" element={<Home />} />
{/* 关于页：path="/about" 匹配 /about 路径 */}
<Route path="/about" element={<About />} />
{/* 404 页：path="*" 是通配符，匹配所有未匹配的路径 */}
<Route path="*" element={<NotFound />} />
</Routes>
</div>
</Router>
);
}

export default App;

效果说明：运行应用后，点击"首页""关于页"会切换 URL 并渲染对应组件，输入未定义的路径（如 /xxx）会渲染 404 页面，整个过程不刷新浏览器。

实战案例 2：嵌套路由（实现页面布局复用）

在实际开发中，很多页面会共享相同的布局（如顶部导航、侧边栏），这时可以用嵌套路由实现布局复用。核心思路：父路由渲染布局组件，子路由通过占位符渲染。

javascript 复制代码

// src/App.jsx
import { BrowserRouter as Router, Routes, Route, Link, Outlet } from 'react-router-dom';

// 布局组件（共享导航栏）
const Layout = () => (
<div>
{/* 共享导航栏 */}
<nav style={{ marginBottom: '20px', display: 'flex', gap: '20px' }}>
<Link to="/" style={{ textDecoration: 'none' }}>首页</Link>
<Link to="/user/profile" style={{ textDecoration: 'none' }}>个人中心</Link>
<Link to="/user/setting" style={{ textDecoration: 'none' }}>设置页面</Link>
</nav>
{/* 子路由占位符：子路由组件会渲染在这里 */}
<Outlet />
</div>
);

// 页面组件
const Home = () => <h2>首页：React Router v7 嵌套路由实战</h2>;
const UserProfile = () => <h2>个人中心：查看用户信息</h2>;
const UserSetting = () => <h2>设置页面：修改用户配置</h2>;
const NotFound = () => <h2>404：页面不存在</h2>;

function App() {
return (
<Router>
<div style={{ padding: '20px' }}>
<Routes>
{/* 父路由：渲染布局组件 */}
<Route path="/" element={<Layout />}>
{/* 子路由：会渲染到 Layout 组件的 <Outlet /> 位置 */}
<Route index element={<Home />} /> {/* index 表示默认子路由（path 为空） */}
<Route path="user/profile" element={<UserProfile />} /> {/* 路径：/user/profile */}
<Route path="user/setting" element={<UserSetting />} /> {/* 路径：/user/setting */}
</Route>
{/* 404 页 */}
<Route path="*" element={<NotFound />} />
</Routes>
</div>
</Router>
);
}

效果说明：所有子路由（首页、个人中心、设置页面）都会共享 Layout 组件的导航栏，无需重复编写导航代码，实现布局复用。其中index 属性表示"默认子路由"，当 URL 为 / 时，会渲染 Home 组件。

2. 进阶编程式配置：数组配置+useRoutes（复杂应用首选）

当应用规模扩大（如几十上百个路由）时，声明式配置会显得冗长且难以维护。这时可以用"数组配置+useRoutes Hook"实现编程式路由配置：将所有路由规则定义在一个数组中，通过 useRoutes Hook 转换为路由组件，更便于管理和扩展（如动态添加路由、路由权限控制）。

实战案例 3：编程式路由配置（含嵌套路由）

javascript 复制代码

// src/App.jsx
import { BrowserRouter as Router, Link, Outlet, useRoutes } from 'react-router-dom';

// 1. 定义页面组件（与之前一致）
const Layout = () => (
<div>
<nav style={{ marginBottom: '20px', display: 'flex', gap: '20px' }}>
<Link to="/" style={{ textDecoration: 'none' }}>首页</Link>
<Link to="/user/profile" style={{ textDecoration: 'none' }}>个人中心</Link>
<Link to="/user/setting" style={{ textDecoration: 'none' }}>设置页面</Link>
</nav>
<Outlet />
</div>
);

const Home = () => <h2>首页：编程式路由配置</h2>;
const UserProfile = () => <h2>个人中心</h2>;
const UserSetting = () => <h2>设置页面</h2>;
const NotFound = () => <h2>404：页面不存在</h2>;

// 2. 定义路由配置数组（核心：所有路由规则集中在这里）
const routesConfig = [
{
path: '/', // 父路由路径
element: <Layout />, // 父路由组件（布局）
children: [ // 子路由配置
{ index: true, element: <Home /> }, // 默认子路由
{ path: 'user/profile', element: <UserProfile /> }, // 子路由 1
{ path: 'user/setting', element: <UserSetting /> } // 子路由 2
]
},
{ path: '*', element: <NotFound /> } // 404 路由
];

// 3. 路由组件：通过 useRoutes 转换路由配置
const AppRoutes = () => {
// useRoutes：接收路由配置数组，返回对应的 Routes+Route 组件树
const routes = useRoutes(routesConfig);
return routes;
};

// 4. 根组件
function App() {
return (
<Router>
<div style={{ padding: '20px' }}>
<AppRoutes /> {/* 渲染路由组件 */}
</div>
</Router>
);
}

效果说明：与声明式配置的效果完全一致，但路由规则集中在 routesConfig 数组中，便于后续扩展（如添加路由权限控制时，只需修改数组中的路由规则）。

3. 核心补充：路由参数与编程式跳转

在实际开发中，我们经常需要"动态路由参数"（如 /user/:id 中的 id）和"编程式跳转"（如表单提交成功后跳转到首页），这也是 React Router 的核心功能。

实战案例 4：动态路由参数（useParams）

javascript 复制代码

// src/App.jsx
import { BrowserRouter as Router, Routes, Route, Link, useParams } from 'react-router-dom';

// 列表组件：展示用户列表
const UserList = () => {
const users = [
{ id: 1, name: '小明' },
{ id: 2, name: '小红' },
{ id: 3, name: '小李' }
];

return (
<div>
<h2>用户列表</h2>
<ul style={{ listStyle: 'none', padding: 0 }}>
{users.map(user => (
<li key={user.id} style={{ margin: '10px 0' }}>
{/* 跳转到用户详情页，传递 id 参数 */}
<Link to={`/user/${user.id}`} style={{ textDecoration: 'none' }}>
查看 {user.name} 的详情
</Link>
</li>
))}
</ul>
</div>
);
};

// 详情组件：通过 useParams 获取路由参数
const UserDetail = () => {
// useParams：获取动态路由参数（返回一个对象，key 是路由中的占位符）
const { id } = useParams();

// 模拟根据 id 获取用户信息
const userInfo = {
1: { name: '小明', age: 22, gender: '男' },
2: { name: '小红', age: 21, gender: '女' },
3: { name: '小李', age: 23, gender: '男' }
}[id];

return (
<div>
<h2>用户详情（ID：{id}）</h2>
{userInfo ? (
<div>
<p>姓名：{userInfo.name}</p>
<p>年龄：{userInfo.age}</p>
<p>性别：{userInfo.gender}</p>
<Link to="/user" style={{ textDecoration: 'none' }}>返回用户列表</Link>
</div>
) : (
<p>用户不存在</p>
)}
</div>
);
};

function App() {
return (
<Router>
<div style={{ padding: '20px' }}>
<Routes>
{/* 动态路由：path 中的 :id 是占位符，表示动态参数 */}
<Route path="/user/:id" element={<UserDetail />} />
{/* 用户列表路由 */}
<Route path="/user" element={<UserList />} />
{/* 默认跳转到用户列表 */}
<Route path="/" element={<Link to="/user" style={{ textDecoration: 'none' }}>进入用户列表</Link>} />
</Routes>
</div>
</Router>
);
}

实战案例 5：编程式跳转（useNavigate）

javascript 复制代码

// src/App.jsx
import { BrowserRouter as Router, Routes, Route, Link, useNavigate } from 'react-router-dom';

// 登录组件：登录成功后编程式跳转到首页
const Login = () => {
const navigate = useNavigate(); // useNavigate：获取导航函数

const handleLogin = () => {
// 模拟登录逻辑（验证用户名密码）
const isLoginSuccess = true;

if (isLoginSuccess) {
// 编程式跳转：跳转到首页（replace: true 表示替换历史记录，避免回退到登录页）
navigate('/', { replace: true });
} else {
alert('登录失败');
}
};

return (
<div>
<h2>登录页面</h2>
<input type="text" placeholder="用户名" style={{ margin: '10px 0' }} />
<br />
<input type="password" placeholder="密码" style={{ margin: '10px 0' }} />
<br />
<button onClick={handleLogin}>登录</button>
</div>
);
};

const Home = () => {
const navigate = useNavigate();

const handleLogout = () => {
// 退出登录：跳转到登录页
navigate('/login', { replace: true });
};

return (
<div>
<h2>首页</h2>
<p>登录成功！</p>
<button onClick={handleLogout}>退出登录</button>
</div>
);
};

function App() {
return (
<Router>
<div style={{ padding: '20px' }}>
<Routes>
<Route path="/login" element={<Login />} />
<Route path="/" element={<Home />} />
</Routes>
</div>
</Router>
);
}

核心说明：useNavigate 是 React Router v6+ 新增的 Hook，替代了之前的 useHistory。它返回的 navigate 函数支持两种用法：navigate('/path')（跳转到指定路径）和 navigate(-1)（回退到上一页），replace: true 表示替换当前历史记录，避免用户回退到之前的页面。

三、React Router v7 核心原理拆解

掌握了实战用法后，我们来深入理解 React Router 的核心原理。很多人会好奇："为什么修改 URL 不会刷新页面？""React 是如何根据 URL 匹配对应的组件？""路由上下文是如何传递的？" 下面我们从 3 个核心点拆解原理。

1. 核心原理 1：SPA 路由的底层实现（Hash 模式 vs History 模式）

React Router 实现 SPA 路由的核心是"修改 URL 但不触发浏览器刷新"，这依赖于浏览器的两种 API：Hash API 和 History API，对应 React Router 的两种模式：

（1）Hash 模式（默认 fallback 模式）

Hash 模式利用 URL 中的 #（哈希值）实现路由。浏览器的特性是：修改 # 后面的内容不会触发页面刷新 ，但会触发 hashchange 事件。
示例 URL：http://localhost:3000/#/user/profile，其中 #/user/profile 是哈希值，React Router 会根据哈希值匹配对应的组件。
简化代码模拟 Hash 模式核心逻辑：

javascript 复制代码

// 简化模拟 Hash 模式路由
class HashRouter {
constructor() {
// 初始化时匹配当前哈希值对应的组件
this.matchRoute(window.location.hash.slice(1)); // slice(1) 去掉 #

// 监听 hashchange 事件：URL 哈希值变化时重新匹配组件
window.addEventListener('hashchange', () => {
const path = window.location.hash.slice(1);
this.matchRoute(path);
});
}

// 匹配路径并渲染组件
matchRoute(path) {
console.log('当前路径：', path);
// 这里省略与路由配置的匹配逻辑，实际会渲染对应的组件
}
}

（2）History 模式（推荐模式，采用）

History 模式利用 HTML5 新增的 History API（pushState、replaceState）实现路由。这两个 API 可以在不刷新页面的前提下，修改浏览器的历史记录和 URL，同时会触发 popstate 事件（前进/后退按钮触发）。
示例 URL：http://localhost:3000/user/profile（无 #，URL 更美观），但需要后端配合配置（所有路由都指向 index.html，避免刷新页面时 404）。
简化代码模拟 History 模式核心逻辑：

javascript 复制代码

// 简化模拟 History 模式路由
class HistoryRouter {
constructor() {
// 初始化时匹配当前路径对应的组件
this.matchRoute(window.location.pathname);

// 监听 popstate 事件：前进/后退按钮触发时重新匹配组件
window.addEventListener('popstate', () => {
this.matchRoute(window.location.pathname);
});
}

// 模拟 push 跳转（类似 navigate('/path')）
push(path) {
// 修改历史记录和 URL，不刷新页面
window.history.pushState({}, '', path);
// 匹配路径并渲染组件
this.matchRoute(path);
}

// 模拟 replace 跳转（类似 navigate('/path', { replace: true })）
replace(path) {
window.history.replaceState({}, '', path);
this.matchRoute(path);
}

// 匹配路径并渲染组件
matchRoute(path) {
console.log('当前路径：', path);
// 这里省略与路由配置的匹配逻辑，实际会渲染对应的组件
}
}

两种模式对比用图例展示：

2. 核心原理 2：路由上下文（Router Context）的传递机制

React Router 的核心组件（如、、useParams、useNavigate 等）之所以能协同工作，是因为它们共享了一个"路由上下文"（Router Context）。这个上下文由组件提供，包含了当前路径、历史记录、路由匹配逻辑等核心信息。

简化代码模拟路由上下文传递：

javascript 复制代码

import { createContext, useContext, useState, useEffect } from 'react';

// 1. 创建路由上下文
const RouterContext = createContext();

// 2. 提供路由上下文的 Router 组件
function Router({ children }) {
const [currentPath, setCurrentPath] = useState(window.location.pathname);

// 监听 popstate 事件，更新当前路径
useEffect(() => {
const handlePopState = () => {
setCurrentPath(window.location.pathname);
};
window.addEventListener('popstate', handlePopState);
return () => window.removeEventListener('popstate', handlePopState);
}, []);

// 导航函数（push 模式）
const push = (path) => {
window.history.pushState({}, '', path);
setCurrentPath(path);
};

// 上下文值：包含当前路径和导航函数
const contextValue = {
currentPath,
push
};

return (
<RouterContext.Provider value={contextValue}>
{children} {/* 所有子组件都能访问路由上下文 */}
</RouterContext.Provider>
);
}

// 3. 自定义 Hook：获取路由上下文（类似 useNavigate、useParams）
function useRouter() {
const context = useContext(RouterContext);
if (!context) {
throw new Error('useRouter 必须在 Router 组件内部使用');
}
return context;
}

// 4. 路由容器组件（类似 <Routes>）
function Routes({ children }) {
const { currentPath } = useRouter();
// 遍历子 Route 组件，匹配当前路径
return React.Children.map(children, (child) => {
if (child.props.path === currentPath || (child.props.index && currentPath === '/')) {
return child.props.element;
}
return null;
});
}

// 5. 路由规则组件（类似 <Route>）
function Route({ path, index, element }) {
return <>{element}</>;
}

// 6. 导航组件（类似 <Link>）
function Link({ to, children }) {
const { push } = useRouter();
const handleClick = (e) => {
e.preventDefault(); // 阻止默认跳转行为（刷新页面）
push(to); // 调用上下文的 push 方法，修改 URL 并更新状态
};
return <a href={to} onClick={handleClick}>{children}</a>;
}

核心逻辑说明：

组件创建路由上下文，提供当前路径（currentPath）和导航函数（push）；
所有路由相关组件（、、Link、useRouter）通过 useContext 获取路由上下文；
Link 组件点击时，通过 push 方法修改 URL（不刷新页面）并更新 currentPath；
组件根据 currentPath 匹配对应的组件，渲染对应的 element。

3. 核心原理 3：路由匹配逻辑（路径匹配与优先级）

React Router 的路由匹配逻辑是"精准匹配+优先级匹配"，核心规则如下：
4. 精准匹配优先：完全匹配 URL 路径的路由优先渲染（如 /user 匹配 path="/user"，不匹配 path="/user/:id"）；
5. 模糊匹配（动态参数） ：带动态参数的路由（如 /user/:id）会匹配符合格式的路径（如 /user/1、/user/2）；
6. 通配符匹配（最低优先级） ：path="*" 是通配符，匹配所有未匹配的路径（如 404 页面），优先级最低；
7. 嵌套路由匹配：父路由匹配成功后，才会匹配其子路由（如 /user/profile 需先匹配父路由 /user，再匹配子路由 profile）。

简化代码模拟路由匹配逻辑：

javascript 复制代码

// 简化模拟路由匹配逻辑
function matchRoutes(routesConfig, currentPath) {
// 遍历路由配置，寻找匹配的路由
for (const route of routesConfig) {
// 1. 匹配当前路由
if (route.path === currentPath) {
return route; // 精准匹配，直接返回
}

// 2. 匹配动态路由（如 /user/:id 匹配 /user/1）
const dynamicPathRegex = new RegExp(`^${route.path.replace(/:(\w+)/g, '([^/]+)')}$`);
if (dynamicPathRegex.test(currentPath)) {
// 提取动态参数（如 id=1）
const params = {};
const matches = currentPath.match(dynamicPathRegex);
const paramNames = route.path.match(/:(\w+)/g)?.map(name => name.slice(1)) || [];
paramNames.forEach((name, index) => {
params[name] = matches[index + 1];
});
return { ...route, params }; // 返回路由和参数
}

// 3. 嵌套路由匹配（递归匹配子路由）
if (route.children && currentPath.startsWith(route.path)) {
const childPath = currentPath.slice(route.path.length) || '/';
const matchedChild = matchRoutes(route.children, childPath);
if (matchedChild) {
return { ...matchedChild, parent: route }; // 返回匹配的子路由和父路由
}
}
}

// 4. 匹配通配符路由（path="*"）
const wildcardRoute = routesConfig.find(route => route.path === '*');
if (wildcardRoute) {
return wildcardRoute;
}

return null; // 无匹配路由
}

// 测试路由匹配
const routesConfig = [
{ path: '/', element: <Layout />, children: [{ index: true, element: <Home /> }] },
{ path: '/user/:id', element: <UserDetail /> },
{ path: '*', element: <NotFound /> }
];

console.log(matchRoutes(routesConfig, '/user/1'));
// 输出：{ path: '/user/:id', element: <UserDetail />, params: { id: '1' } }

console.log(matchRoutes(routesConfig, '/xxx'));
// 输出：{ path: '*', element: <NotFound /> }

路由匹配流程用图例展示：

四、核心总结与实战避坑指南

核心总结

路由核心作用：在 SPA 中实现"无刷新页面切换"，核心依赖 Hash API 或 History API；
两种配置方式：声明式配置（JSX 标签）适合简单应用，编程式配置（数组+useRoutes）适合复杂应用；
核心 API 记忆：（提供上下文）、+（匹配路由）、Link（声明式跳转）、useNavigate（编程式跳转）、useParams（获取动态参数）；
底层原理核心：路由上下文传递核心信息，URL 变化通过浏览器 API 实现无刷新修改，路由匹配通过"精准→动态→嵌套→通配符"的优先级逻辑实现。

实战避坑指南

坑 1：History 模式刷新 404 ：解决方案：后端配置所有路由指向 index.html（如 Nginx 配置 try_files <math xmlns="http://www.w3.org/1998/Math/MathML"> u r i uri </math>uriuri/ /index.html;）；
坑 2：useParams 获取不到参数：检查路由 path 是否正确定义动态参数（如 /user/:id），且组件是否在组件的 element 中（只有路由组件才能使用 useParams）；
坑 3：嵌套路由不渲染：忘记在父路由组件中添加占位符，子路由组件无法渲染；
坑 4：路由匹配顺序错误：通配符路由（path="*"）必须放在最后，否则会覆盖其他路由；动态路由（/user/:id）要放在精准路由（/user/profile）之后，避免精准路由被覆盖；
坑 5：Link 组件刷新页面：不要在 Link 组件中添加多余的 onClick 事件并调用 window.location.href，Link 组件本身会阻止默认跳转行为，只需通过 to 属性指定路径。

五、下一步学习方向

今天我们掌握了 React Router v7 的核心配置和底层原理，下一步可以重点学习：

路由权限控制：结合 React 状态管理实现登录拦截、角色权限控制（如未登录用户跳转到登录页）；
路由懒加载：用 React.lazy 和 Suspense 实现路由组件懒加载，优化应用加载性能；
React Router 高级 API：如 useSearchParams（获取 URL 查询参数）、useLocation（获取当前路由位置信息）、useMatch（匹配路由路径）；
React Router v7 新特性：如数据路由（Data Router）、加载状态管理等（v7 重点优化方向）。
如果这篇文章对你有帮助，欢迎点赞、收藏、转发～有任何问题也可以在评论区留言交流～我们下期再见！](https://link.juejin.cn?target= "")

React从入门到出门 第五章 React Router 配置与原理初探

一、前置准备：React Router v7 环境搭建

二、React Router v7 核心路由配置方式

1. 基础声明式配置：实现简单页面切换

实战案例 2：嵌套路由（实现页面布局复用）

2. 进阶编程式配置：数组配置+useRoutes（复杂应用首选）

实战案例 3：编程式路由配置（含嵌套路由）

3. 核心补充：路由参数与编程式跳转

实战案例 4：动态路由参数（useParams）

实战案例 5：编程式跳转（useNavigate）

三、React Router v7 核心原理拆解

1. 核心原理 1：SPA 路由的底层实现（Hash 模式 vs History 模式）

（1）Hash 模式（默认 fallback 模式）

（2）History 模式（推荐模式， 采用）

2. 核心原理 2：路由上下文（Router Context）的传递机制

简化代码模拟路由上下文传递：

3. 核心原理 3：路由匹配逻辑（路径匹配与优先级）

简化代码模拟路由匹配逻辑：

四、核心总结与实战避坑指南

核心总结

实战避坑指南

五、下一步学习方向

React从入门到出门第五章 React Router 配置与原理初探

（2）History 模式（推荐模式，采用）