告别路由配置烦恼：umi约定式与配置式路由实战指南
【免费下载链接】umi A framework in react community ✨ 
项目地址: https://gitcode.com/gh_mirrors/umi8/umi
你是否还在为React应用中的路由配置繁琐而头疼？手动编写路由表、处理嵌套路由关系、维护路由与组件的映射...这些重复劳动不仅耗费时间，还容易出错。作为React社区的主流框架，umi（发音同"you-me"，中文可称为"路由美"）提供了一套优雅的路由解决方案，让你从复杂的路由配置中解放出来。本文将带你深入掌握umi的路由系统，学会如何灵活运用约定式和配置式两种路由模式，轻松应对各种应用场景。读完本文，你将能够：快速搭建基础路由结构、处理动态路由参数、实现嵌套布局、配置权限路由，以及在两种路由模式间自如切换。
路由系统概述
umi路由系统基于React Router（React路由库）构建，提供了两种主要的路由定义方式：约定式路由（基于文件系统）和配置式路由（基于路由配置文件）。约定式路由通过文件和目录结构自动生成路由配置，适合大多数场景；配置式路由则通过显式的配置文件定义路由，提供更高的灵活性。两种方式可以根据项目需求灵活选择或结合使用。
官方文档中对路由系统有详细介绍，你可以通过docs/guide/router.md获取完整信息。
约定式路由：文件即路由
基础路由约定
umi的约定式路由是其最具特色的功能之一。它的核心思想是：文件系统即路由系统。umi会自动扫描pages目录下的文件和目录结构，并据此生成对应的路由配置。这种"零配置"的方式极大简化了路由的创建和维护。
假设pages目录结构如下：
+ pages/
+ users/
- index.js
- list.js
- index.js
umi会自动生成如下路由配置：
[
{ path: '/', exact: true, component: './pages/index.js' },
{ path: '/users/', exact: true, component: './pages/users/index.js' },
{ path: '/users/list', exact: true, component: './pages/users/list.js' },
]
这种约定使得新增页面变得异常简单：只需在pages目录下创建对应的文件或目录，路由会自动生成，无需手动修改路由配置。项目的目录结构本身就直观地反映了应用的路由结构，大大提高了代码的可维护性。
动态路由
在实际应用中，我们经常需要处理动态路由参数，如用户ID、文章ID等。umi通过特殊的文件命名约定来支持动态路由。具体来说，带$前缀的目录或文件会被识别为动态路由参数。
例如，以下目录结构：
+ pages/
+ users/
$id.js
- index.js
会生成路由配置：
[
{ path: '/', exact: true, component: './pages/index.js' },
{ path: '/users/:id', exact: true, component: './pages/users/$id.js' },
]
这样，当访问/users/123时，$id.js组件可以通过props.match.params.id获取到123这个参数值。
umi还支持更复杂的动态路由场景，比如可选的动态路由。只需在动态路由参数名后添加$后缀，即可将其定义为可选参数。例如：
+ pages/
+ users/
$id$.js
- index.js
会生成：
[
{ path: '/', exact: true, component: './pages/index.js' },
{ path: '/users/:id?', exact: true, component: './pages/users/$id$.js' },
]
此时，/users和/users/123都能匹配到$id$.js组件，当没有提供id参数时，props.match.params.id为undefined。
嵌套路由与布局
复杂应用通常需要嵌套路由来组织页面结构，比如在主布局中包含侧边栏和主内容区，主内容区根据不同路由显示不同页面。umi通过_layout.js文件来实现嵌套路由。
目录下存在_layout.js时，umi会以此文件作为该目录的布局组件，并将该目录下的其他文件作为子路由。例如：
+ pages/
+ users/
- _layout.js
- $id.js
- index.js
会生成路由配置：
[
{
path: '/users',
exact: false,
component: './pages/users/_layout.js',
routes: [
{ path: '/users/', exact: true, component: './pages/users/index.js' },
{ path: '/users/:id', exact: true, component: './pages/users/$id.js' },
],
},
]
_layout.js组件需要通过props.children来渲染子路由对应的组件，例如：
// pages/users/_layout.js
export default function UsersLayout(props) {
return (
<div className="users-layout">
<div className="sidebar">用户管理菜单</div>
<div className="content">{props.children}</div>
</div>
);
}
这样，当访问/users或/users/123时，都会先渲染UsersLayout组件，然后在content区域显示对应的子页面内容。
全局布局
除了目录级别的布局（_layout.js），umi还支持全局布局。src/layouts/index.js文件会被作为全局布局，应用于所有路由。全局布局通常用于放置应用的公共元素，如顶部导航栏、底部版权信息等。
全局布局的基本结构如下：
// src/layouts/index.js
export default function GlobalLayout(props) {
return (
<>
<header>这是全局导航栏</header>
<main>{props.children}</main>
<footer>© 2025 umi路由美</footer>
</>
);
}
如果需要为不同路由提供不同的全局布局，可以在全局布局组件中根据当前路径进行条件渲染：
// src/layouts/index.js
export default function GlobalLayout(props) {
// 登录页使用简化布局
if (props.location.pathname === '/login') {
return <SimpleLayout>{props.children}</SimpleLayout>;
}
// 其他页面使用默认布局
return (
<>
<header>这是全局导航栏</header>
<main>{props.children}</main>
<footer>© 2025 umi路由美</footer>
</>
);
}
配置式路由：灵活掌控路由行为
虽然约定式路由能满足大多数场景，但有时我们需要更精细地控制路由行为。umi支持通过配置文件显式定义路由，即配置式路由。当在.umirc.js或config/config.js中定义routes选项时，umi会忽略约定式路由，直接使用配置的路由表。
基础配置
配置式路由的基本结构如下：
// .umirc.js
export default {
routes: [
{ path: '/', exact: true, component: './pages/index.js' },
{ path: '/list', component: './pages/list.js' },
{
path: '/users',
component: './pages/users/_layout.js',
routes: [
{ path: '/users/detail', exact: true, component: './pages/users/detail.js' },
{ path: '/users/:id', exact: true, component: './pages/users/$id.js' }
]
},
],
};
这里的routes是一个路由配置对象数组，每个对象支持以下主要属性：
path：路由路径component：路由对应的组件路径（相对于项目根目录）exact：是否精确匹配路径routes：子路由配置，用于实现嵌套路由Route：自定义路由组件，用于实现权限路由等高级功能
路由优先级
在配置式路由中，路由的定义顺序很重要。umi会按照路由配置的顺序进行匹配，因此更具体的路由应该放在前面。例如：
// .umirc.js
export default {
routes: [
{ path: '/users/detail', component: './pages/users/detail.js' }, // 更具体的路由
{ path: '/users/:id', component: './pages/users/$id.js' }, // 较通用的路由
{ path: '/users', component: './pages/users/index.js' },
],
};
如果将/users/:id放在/users/detail前面，那么/users/detail将永远不会被匹配到，因为:id会匹配detail字符串。
路由组件与权限控制
配置式路由的一大优势是可以通过Route属性指定自定义路由组件，从而实现权限控制等高级功能。例如，我们可以创建一个权限路由组件：
// src/routes/PrivateRoute.js
import { Route, Redirect } from 'react-router-dom';
export default function PrivateRoute({ component: Component, ...rest }) {
const isAuthenticated = localStorage.getItem('token');
return (
<Route
{...rest}
render={props =>
isAuthenticated ? (
<Component {...props} />
) : (
<Redirect to={{ pathname: '/login', state: { from: props.location } }} />
)
}
/>
);
}
然后在路由配置中使用：
// .umirc.js
export default {
routes: [
{ path: '/', exact: true, component: './pages/index.js' },
{ path: '/login', component: './pages/login.js' },
{
path: '/dashboard',
component: './pages/dashboard.js',
Route: './src/routes/PrivateRoute.js' // 使用自定义路由组件
},
],
};
这样，当未登录用户访问/dashboard时，会被重定向到登录页。
路由进阶功能
路由跳转
umi提供了两种路由跳转方式：声明式和命令式。
声明式跳转基于umi/link组件，类似于HTML的<a>标签：
import Link from 'umi/link';
export default () => (
<div>
<Link to="/list">去列表页</Link>
<Link to={{ pathname: '/users', query: { id: 123 } }}>
去用户页
</Link>
</div>
);
详细使用方法可参考docs/guide/navigate-between-pages.md。
命令式跳转基于umi/router模块，适用于需要在事件处理函数中进行跳转的场景：
import router from 'umi/router';
function handleClick() {
// 基本跳转
router.push('/list');
// 带查询参数
router.push({
pathname: '/users',
query: { id: 123 },
});
// 替换当前历史记录（不产生新的历史条目）
router.replace('/login');
// 后退
router.goBack();
}
路由动效与滚动行为
为提升用户体验，我们可以为路由切换添加过渡动画，并控制页面滚动行为。
路由动效可以通过react-transition-group库实现。首先安装依赖：
npm install react-transition-group --save
然后在布局组件中使用：
// src/layouts/index.js
import withRouter from 'umi/withRouter';
import { TransitionGroup, CSSTransition } from 'react-transition-group';
export default withRouter(({ location, children }) => (
<TransitionGroup>
<CSSTransition key={location.key} classNames="fade" timeout={300}>
{children}
</CSSTransition>
</TransitionGroup>
));
接着在全局样式中定义过渡效果：
/* src/global.css */
.fade-enter {
opacity: 0;
}
.fade-enter-active {
opacity: 1;
transition: opacity 300ms;
}
.fade-exit {
opacity: 1;
}
.fade-exit-active {
opacity: 0;
transition: opacity 300ms;
}
滚动行为控制可以在布局组件的componentDidUpdate生命周期中实现：
// src/layouts/index.js
import { Component } from 'react';
import withRouter from 'umi/withRouter';
class Layout extends Component {
componentDidUpdate(prevProps) {
// 当路由变化时滚动到顶部
if (this.props.location.pathname !== prevProps.location.pathname) {
window.scrollTo(0, 0);
}
}
render() {
return this.props.children;
}
}
export default withRouter(Layout);
实战技巧与最佳实践
路由组织方式选择
在实际项目中，如何选择约定式路由还是配置式路由？以下是一些参考建议：
- 小型项目：优先使用约定式路由，开发速度快，代码结构清晰。
- 中型项目：可以混合使用，主体使用约定式路由，特殊页面使用配置式路由覆盖。
- 大型项目：建议使用配置式路由，便于统一管理和维护，尤其是多人协作时。
umi支持在配置式路由中通过extendsRoutes配置扩展约定式路由，实现两种方式的结合：
// .umirc.js
export default {
routes: [
// 配置式路由
{ path: '/login', component: './pages/login.js' },
],
// 扩展约定式路由
extendsRoutes: (routes) => {
return [
...routes, // 原有约定式路由
{ path: '/admin', component: './pages/admin.js' }, // 新增路由
];
},
};
路由模块化
对于大型项目，将所有路由配置放在一个文件中会导致文件臃肿难以维护。我们可以将路由配置拆分成多个模块，然后在主配置文件中合并：
// config/routes/user.js
export default [
{ path: '/users', component: './pages/users/index.js' },
{ path: '/users/:id', component: './pages/users/$id.js' },
];
// config/routes/product.js
export default [
{ path: '/products', component: './pages/products/index.js' },
{ path: '/products/:id', component: './pages/products/$id.js' },
];
// .umirc.js
import userRoutes from './config/routes/user';
import productRoutes from './config/routes/product';
export default {
routes: [
{ path: '/', component: './pages/index.js' },
...userRoutes,
...productRoutes,
],
};
路由守卫与错误处理
在实际应用中，我们经常需要在路由切换前进行一些检查，如登录状态验证、权限检查等。这可以通过"路由守卫"来实现。在umi中，可以通过高阶组件包装路由组件来实现：
// src/utils/withAuth.js
import { useEffect } from 'react';
import router from 'umi/router';
export default function withAuth(Component) {
return (props) => {
useEffect(() => {
const token = localStorage.getItem('token');
if (!token) {
// 未登录，重定向到登录页
router.push('/login?redirect=' + props.location.pathname);
}
}, []);
return <Component {...props} />;
};
}
然后在路由配置中使用：
// pages/dashboard.js
import withAuth from '../utils/withAuth';
function Dashboard() {
return <div>需要登录才能访问的页面</div>;
}
export default withAuth(Dashboard);
对于404页面，umi提供了简单的约定：pages/404.js文件会被自动识别为404页面。你可以自定义这个页面的内容：
// pages/404.js
export default () => {
return (
<div style={{ textAlign: 'center', padding: '50px' }}>
<h1>404 - 页面未找到</h1>
<p>您访问的页面不存在或已被删除</p>
</div>
);
};
详细配置可参考docs/guide/add-404-page.md。
总结与展望
umi的路由系统为React应用开发提供了极大的便利，无论是简单的约定式路由还是灵活的配置式路由，都能满足不同场景的需求。通过本文的介绍，你应该已经掌握了umi路由的核心概念和使用方法，包括：
- 约定式路由的基本约定和高级用法（动态路由、嵌套路由等）
- 配置式路由的基础配置和高级特性（路由优先级、自定义路由组件等）
- 路由跳转的两种方式（声明式和命令式）
- 路由动效、滚动行为等用户体验优化技巧
- 路由模块化、权限控制等最佳实践
路由系统作为前端框架的核心组成部分，其设计直接影响开发效率和用户体验。umi的路由方案在简洁性和灵活性之间取得了很好的平衡，让开发者能够专注于业务逻辑而非路由配置。
随着前端技术的发展，我们可以期待umi路由系统在未来提供更多创新特性，如基于文件系统的路由中间件、更智能的路由代码分割策略等。现在，是时候将这些知识应用到你的项目中，体验umi路由带来的开发乐趣了！
如果你在使用过程中遇到问题，可以查阅官方路由文档或常见问题解答获取帮助。也欢迎在评论区分享你的使用经验和心得！
【免费下载链接】umi A framework in react community ✨ 项目地址: https://gitcode.com/gh_mirrors/umi8/umi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
