1. 从一个真实的路由拦截需求说起
前端项目做到一定规模，路由管理就不再是简单的路径映射了。我接手过一个后台管理系统，里面有几十个页面，不同角色的用户登录后能看到的菜单和能进入的页面完全不同。最开始的做法很粗暴——在每个页面的组件初始化钩子里判断权限，没权限就弹个提示然后手动跳走。这种写法在页面少的时候还能忍，一旦页面数量上去，维护成本直接爆炸：改一个权限规则，得翻遍所有组件；漏掉一个页面，用户就能通过手动输入地址栏的方式溜进去。
后来我把这套逻辑全部收敛到路由层面，用 Angular 的CanActivate守卫统一处理。效果立竿见影：权限判断只写一次，所有需要保护的路由挂上守卫就行，组件里再也不用关心"我该不该被显示"这种问题。这就是路由守卫存在的意义——把访问控制从业务组件里抽离出来，放到路由配置这一层统一管理。
CanActivate是 Angular 路由守卫体系里最常用的一个接口，它的职责非常明确：在路由激活之前做一次判断，返回true就放行，返回false就拦截。听起来简单，但实际用起来有不少细节值得聊——同步返回和异步返回有什么区别、怎么把用户重定向到登录页、多个守卫的执行顺序是怎样的、依赖注入在守卫里怎么用、为什么有时候守卫返回了false页面却还是跳转了。这些问题我在项目里几乎全踩过一遍。
这篇文章适合已经用过 Angular 路由、但对守卫机制还停留在"照着文档抄一遍"阶段的开发者。我会从实际场景出发，把CanActivate的工作机制、写法、常见坑和进阶用法讲透，让你不只是会写，而是真正理解它为什么这么设计。
2. CanActivate 到底在路由生命周期的哪个环节介入
2.1 路由导航的完整流程拆解
要理解CanActivate，得先搞清楚一次路由跳转到底经历了什么。当用户在地址栏输入 URL，或者点击了一个routerLink，Angular 的路由器并不是直接就把新组件渲染出来的，中间有一整套流程：
- URL 解析：路由器把目标 URL 解析成 URL 树，匹配到对应的路由配置。
- 重定向检查：如果匹配到的路由配置里有
redirectTo，先处理重定向。 - 守卫检查阶段：依次执行
CanDeactivate（离开当前路由）、CanActivateChild（子路由激活）、CanActivate（激活目标路由）、CanLoad（模块加载）等守卫。 - 解析数据：执行路由的
resolve守卫，预加载数据。 - 激活路由：实例化组件，渲染视图。
CanActivate处在第 3 步，也就是组件还没被创建之前。这一点非常关键——它意味着守卫里拿不到目标组件的实例，你只能基于路由参数、全局状态（比如用户服务）来做判断。很多人一开始会想在守卫里访问组件的属性，这是行不通的，因为组件压根还没出生。
提示：正因为
CanActivate在组件创建前执行，所以它非常适合做"这个用户有没有资格进入这个页面"的判断，而不适合做"这个页面的数据准备好了没有"的判断——后者应该交给Resolve守卫。
2.2 返回值的三态：true、false 和 UrlTree
CanActivate的接口签名允许返回三种东西，理解这三态是掌握它的核心：
| 返回值类型 | 行为 | 典型场景 |
|---|---|---|
true | 放行，继续导航 | 用户已登录，允许进入 |
false | 拦截，导航被取消，停留在当前页 | 用户未登录，但不希望跳转 |
UrlTree | 拦截当前导航，并重定向到 UrlTree 指定的地址 | 未登录，跳转到登录页 |
早期 Angular 版本里，如果想在拦截后跳转到登录页，得在守卫里手动调用router.navigate()然后返回false。这种做法有个隐患：手动导航和返回false之间存在竞态，有时候会出现导航被取消、页面卡住的情况。从 Angular 7.1 开始，守卫可以直接返回一个UrlTree，路由器会接管重定向，行为更可预测。现在写守卫，重定向场景一律优先用UrlTree，不要再用router.navigate加false的老写法。
import { Injectable } from '@angular/core'; import { CanActivate, Router, UrlTree } from '@angular/router'; import { AuthService } from './auth.service'; @Injectable({ providedIn: 'root' }) export class AuthGuard implements CanActivate { constructor(private auth: AuthService, private router: Router) {} canActivate(): boolean | UrlTree { if (this.auth.isLoggedIn()) { return true; } // 返回 UrlTree，路由器自动重定向 return this.router.createUrlTree(['/login']); } }2.3 同步与异步：Observable 和 Promise 的处理
真实项目里，登录状态往往不是本地一个布尔值就能确定的。比如 token 存在 localStorage 里，但需要向后端验证是否过期；或者用户权限列表需要异步拉取。这时候canActivate可以返回Observable<boolean | UrlTree>或Promise<boolean | UrlTree>。
canActivate(): Observable<boolean | UrlTree> { return this.auth.checkPermissionAsync().pipe( map(hasPermission => hasPermission ? true : this.router.createUrlTree(['/no-access'])), catchError(() => of(this.router.createUrlTree(['/login']))) ); }这里有个容易忽略的点：如果返回的 Observable 一直不发出值（既不 complete 也不 emit），路由导航会一直挂起，页面看起来像卡死了。我遇到过因为 HTTP 请求没有设置超时，后端又恰好挂了，导致用户点击菜单后整个界面无响应的情况。所以异步守卫里一定要给数据源加上超时或者兜底逻辑。
canActivate(): Observable<boolean | UrlTree> { return this.auth.checkPermissionAsync().pipe( timeout(5000), map(hasPermission => hasPermission ? true : this.router.createUrlTree(['/no-access'])), catchError(() => of(this.router.createUrlTree(['/login']))) ); }3. 把守卫挂到路由上：配置方式与执行顺序
3.1 三种注册方式的选择
CanActivate守卫写好后，需要挂到路由配置上。Angular 提供了几种注册方式，各有适用场景：
方式一：类守卫（class guard），最传统也最常用。守卫是一个实现了CanActivate接口的类，通过@Injectable注册，然后在路由配置里引用。
const routes: Routes = [ { path: 'dashboard', component: DashboardComponent, canActivate: [AuthGuard] } ];方式二：函数式守卫（functional guard），Angular 14 之后引入的新写法。守卫就是一个普通函数，用inject()获取依赖，不需要写类。
export const authGuard: CanActivateFn = (route, state) => { const auth = inject(AuthService); const router = inject(Router); return auth.isLoggedIn() ? true : router.createUrlTree(['/login']); }; const routes: Routes = [ { path: 'dashboard', component: DashboardComponent, canActivate: [authGuard] } ];函数式守卫的好处是代码更简洁，不需要@Injectable装饰器，也更容易做组合和复用。新项目我基本都用函数式写法，老项目如果已经有一堆类守卫，也没必要强行迁移，两者可以共存。
方式三：canActivateChild，作用于子路由。当父路由有一堆子路由，且它们需要相同的守卫逻辑时，挂在父路由的canActivateChild上比在每个子路由上重复写canActivate要干净得多。
const routes: Routes = [ { path: 'admin', component: AdminLayoutComponent, canActivateChild: [AdminGuard], children: [ { path: 'users', component: UserListComponent }, { path: 'settings', component: SettingsComponent } ] } ];3.2 多个守卫的执行顺序与短路机制
一个路由可以挂多个守卫，canActivate: [GuardA, GuardB, GuardC]。它们的执行顺序是从左到右，而且是串行的——GuardA返回true之后才会执行GuardB。
这里有个非常重要的短路机制：只要有一个守卫返回false或UrlTree，后面的守卫就不会再执行了。这个特性可以用来做性能优化：把最便宜、最容易失败的检查放在前面。比如先检查本地有没有 token（同步、零成本），通过了再去异步请求后端验证权限（有网络开销）。
const routes: Routes = [ { path: 'reports', component: ReportsComponent, canActivate: [TokenExistsGuard, PermissionGuard] // 先查本地，再查后端 } ];我见过有同事把顺序写反了，每次进页面都先发一个权限请求，明明本地 token 都没有，白白浪费一次网络往返。顺序这件事，想清楚了能省不少事。
3.3 依赖注入在守卫里的正确姿势
类守卫通过构造函数注入依赖，这是 Angular 的标准做法。但要注意，守卫如果注册在懒加载模块里，它的注入器作用域是模块级的；如果注册在根级（providedIn: 'root'），则是应用级的。这个区别在守卫依赖某个模块级服务时会出问题——比如守卫在根级，但它依赖的服务只在懒加载模块里提供，就会报NullInjectorError。
函数式守卫用inject()就没这个烦恼，因为inject()会在调用时从当前注入器上下文解析，行为更符合直觉。这也是我推荐新项目用函数式守卫的原因之一。
注意：守卫里不要注入那些会触发大量副作用的服务。守卫的执行时机很早，如果注入的服务在构造函数里就发起了 HTTP 请求或者订阅了全局事件，可能会造成意料之外的行为。
4. 那些年我在守卫上踩过的坑
4.1 返回 false 之后页面为什么还是跳转了
这是新手最容易困惑的问题。现象是：守卫明明返回了false，但页面还是跳到了目标路由。排查下来通常有两个原因。
原因一：守卫根本没被执行。路由配置里canActivate写错了位置，比如写在了children数组的某个子路由上，但实际访问的是父路由。或者路由匹配顺序有问题，前面的通配路由**把请求截胡了。Angular 的路由匹配是"先匹配先赢"，如果**路由排在前面，后面的守卫路由永远匹配不到。
原因二：在守卫里手动调用了router.navigate又返回了false。这种写法在某些 Angular 版本里会导致导航状态混乱。正确做法是返回UrlTree，让路由器统一处理。
// 错误写法：手动导航 + 返回 false canActivate(): boolean { if (!this.auth.isLoggedIn()) { this.router.navigate(['/login']); // 手动跳转 return false; // 又返回 false } return true; } // 正确写法：返回 UrlTree canActivate(): boolean | UrlTree { return this.auth.isLoggedIn() ? true : this.router.createUrlTree(['/login']); }4.2 异步守卫导致的"页面卡死"
前面提过，异步守卫如果 Observable 不发出值，导航会一直挂起。除了加timeout，还有一个隐蔽的场景：在守卫里订阅了一个BehaviorSubject，但这个 Subject 的初始值判断逻辑有问题，导致它永远不 emit 新值。
我遇到过一次，权限服务用一个BehaviorSubject<boolean>存登录状态，初始值是false。守卫里this.auth.status$.pipe(filter(v => v === true))这样写，如果用户本来就是登录状态，Subject 的值已经是true了，filter会通过；但如果用户刚刷新页面，状态还没从 localStorage 恢复，Subject 是false，filter就把值过滤掉了，守卫永远等不到true，页面就卡住了。
解决办法是守卫里不要做这种"等待某个值变成 true"的过滤，而是直接取当前快照判断，或者用take(1)明确只取一次。
canActivate(): Observable<boolean | UrlTree> { return this.auth.status$.pipe( take(1), // 明确只取当前值，不等待后续变化 map(isLoggedIn => isLoggedIn ? true : this.router.createUrlTree(['/login'])) ); }4.3 守卫里的重定向死循环
如果登录页本身也挂了AuthGuard，而未登录时守卫又重定向到登录页，就会形成死循环：访问登录页 → 守卫判断未登录 → 重定向到登录页 → 守卫判断未登录 → ……浏览器会报"重定向次数过多"。
解决办法很简单：登录页、注册页、错误页这些公共页面不要挂AuthGuard。如果确实需要守卫，守卫里要排除这些路径。
canActivate(route: ActivatedRouteSnapshot): boolean | UrlTree { const publicPaths = ['/login', '/register', '/404']; if (publicPaths.includes(route.routeConfig?.path ?? '')) { return true; } return this.auth.isLoggedIn() ? true : this.router.createUrlTree(['/login']); }4.4 守卫与路由参数的配合
守卫可以拿到ActivatedRouteSnapshot和RouterStateSnapshot，这意味着你可以基于路由参数做权限判断。比如/project/:id这样的路由，守卫里可以读取id，然后判断当前用户是不是这个项目的成员。
canActivate(route: ActivatedRouteSnapshot): Observable<boolean | UrlTree> { const projectId = route.paramMap.get('id'); if (!projectId) { return of(this.router.createUrlTree(['/404'])); } return this.projectService.isMember(projectId).pipe( map(isMember => isMember ? true : this.router.createUrlTree(['/no-access'])) ); }这里有个细节：route.paramMap在守卫执行时已经解析好了，可以直接用。但route.data（路由配置里的静态数据）也是可用的，可以用来传递一些配置信息，比如data: { roles: ['admin'] }，守卫里读取route.data['roles']做角色判断。
5. 从单守卫到守卫体系：进阶组合与最佳实践
5.1 用工厂函数生成参数化守卫
实际项目里，权限判断往往需要参数。比如"需要 admin 角色"和"需要 editor 角色"是两个不同的判断，但逻辑结构一样。这时候可以用工厂函数生成守卫，避免写一堆重复的类。
export function roleGuard(allowedRoles: string[]): CanActivateFn { return (route, state) => { const auth = inject(AuthService); const router = inject(Router); const userRole = auth.getCurrentRole(); return allowedRoles.includes(userRole) ? true : router.createUrlTree(['/no-access']); }; } const routes: Routes = [ { path: 'admin', component: AdminComponent, canActivate: [roleGuard(['admin'])] }, { path: 'editor', component: EditorComponent, canActivate: [roleGuard(['admin', 'editor'])] } ];这种写法把守卫逻辑参数化，复用性极高。我在一个项目里用这种方式管理了十几种角色权限，路由配置读起来非常清晰。
5.2 守卫与拦截器的分工
很多人会把权限判断和 HTTP 请求拦截混在一起。我的经验是：CanActivate管"能不能进这个页面"，HTTP 拦截器管"这个请求带不带 token、401 了怎么办"。两者职责不同，不要互相替代。
守卫负责页面级的访问控制，拦截器负责请求级的认证信息注入和错误处理。如果只做拦截器不做守卫，用户还是能进入页面，只是页面里的数据请求会失败，体验很差；如果只做守卫不做拦截器，页面能进但数据拿不到，同样不行。两者配合才是完整的方案。
5.3 测试守卫：不要只测 happy path
守卫的单元测试很容易写成"登录了就返回 true"这种 happy path。但守卫的价值恰恰在于异常路径。我通常会覆盖这几种情况：
| 测试场景 | 预期结果 |
|---|---|
| 已登录用户访问受保护路由 | 返回true |
| 未登录用户访问受保护路由 | 返回UrlTree，指向登录页 |
| 异步权限检查超时 | 返回UrlTree，指向登录页或错误页 |
| 权限不足的用户访问 | 返回UrlTree，指向无权限页 |
| 公共路径访问 | 直接返回true，不触发权限检查 |
测试异步守卫时，用fakeAsync和tick控制时间，或者用jasmine-marbles这类工具模拟 Observable 流。关键是确保守卫在异常情况下不会挂起，而是有明确的返回值。
5.4 性能考量：守卫里别做重活
守卫在每次导航时都会执行，如果里面做了耗时的同步操作（比如遍历一个几千条数据的数组做权限匹配），会明显拖慢页面切换。我的做法是：权限数据在应用启动时预加载并缓存，守卫里只做 O(1) 的查表判断。如果权限数据需要异步获取，也尽量在守卫外提前加载好，守卫里只读缓存。
另外，canActivate和canActivateChild不要重复挂相同的守卫。如果父路由已经用canActivateChild保护了所有子路由，子路由上就不用再挂canActivate了，否则同一个判断会执行两次。
6. 一个完整的权限守卫落地案例
假设我们要做一个内容管理后台，需求是这样的：未登录用户访问任何管理页面都跳转到登录页；已登录但角色不是admin的用户访问用户管理页面时跳转到无权限页；登录页和 404 页不需要守卫。
先定义认证服务：
@Injectable({ providedIn: 'root' }) export class AuthService { private currentUser: { role: string } | null = null; constructor() { const stored = localStorage.getItem('user'); if (stored) { this.currentUser = JSON.parse(stored); } } isLoggedIn(): boolean { return this.currentUser !== null; } getRole(): string { return this.currentUser?.role ?? 'guest'; } }然后写两个函数式守卫：
export const authGuard: CanActivateFn = () => { const auth = inject(AuthService); const router = inject(Router); return auth.isLoggedIn() ? true : router.createUrlTree(['/login']); }; export function roleGuard(roles: string[]): CanActivateFn { return () => { const auth = inject(AuthService); const router = inject(Router); return roles.includes(auth.getRole()) ? true : router.createUrlTree(['/no-access']); }; }路由配置：
const routes: Routes = [ { path: 'login', component: LoginComponent }, { path: 'no-access', component: NoAccessComponent }, { path: '404', component: NotFoundComponent }, { path: 'admin', component: AdminLayoutComponent, canActivate: [authGuard], canActivateChild: [authGuard], children: [ { path: 'dashboard', component: DashboardComponent }, { path: 'users', component: UserListComponent, canActivate: [roleGuard(['admin'])] }, { path: 'content', component: ContentListComponent, canActivate: [roleGuard(['admin', 'editor'])] } ] }, { path: '', redirectTo: '/admin/dashboard', pathMatch: 'full' }, { path: '**', redirectTo: '/404' } ];这套配置下来，未登录用户访问/admin/users会被authGuard拦截跳到登录页；登录了但角色是editor的用户访问/admin/users，authGuard放行，但roleGuard(['admin'])会拦截并跳到无权限页；访问/admin/content则两个角色都能进。逻辑清晰，维护起来也方便——加新页面只需要在路由配置里挂上对应的守卫就行。
我在实际项目里还加了一层：把用户的权限列表也缓存到AuthService里，roleGuard改成检查权限列表而不是单一角色。这样权限粒度可以做到按钮级别，路由守卫和组件内的权限指令共用同一份数据源，不会出现两处判断不一致的情况。
最后分享一个排查守卫问题的小技巧：在守卫里加一行console.log打印当前路由和判断结果，然后打开浏览器的路由日志（Angular 提供了enableTracing选项），能清楚看到每次导航经过了哪些守卫、返回了什么值。这个手段帮我定位过好几次"守卫没生效"的问题，比盲猜快得多。
