[!info] related notes

• 所属 MOC: Vue MOC
• 上位主题: vue3
• 前置概念: 路由
• 相关实践: vue-router-module-design, vue-router-guards-and-permission-control, pinia, vue3-performance-optimization, 页面浏览埋点

Vue Router

Vue Router 是 Vue 的官方客户端路由库。它负责监听 URL 变化、匹配路由规则、执行导航控制，并把对应组件渲染到 <router-view> 中。

一句话定义

Vue Router = Vue 应用里的页面组织系统，用 URL 表达页面状态，用路由表把 URL 映射到组件。

先抓住它解决的问题

• 让不同 URL 显示不同页面组件
• 让页面状态可分享、可刷新恢复、可前进后退
• 让布局嵌套、权限控制、懒加载、页面缓存有统一骨架

浏览器原理和它的关系

Vue Router 不是凭空工作的，它建立在浏览器路由机制之上。

• hash 模式基于 location.hash 和 hashchange
• history 模式基于 pushState、replaceState 和 popstate

如果只想理解浏览器层原理，先看 路由；Vue Router 是在这个基础上再做组件映射与工程封装。

核心概念

router

路由器实例，负责执行导航行为和注册守卫。

常见能力：

• router.push()
• router.replace()
• router.back()
• router.forward()

route

当前路由信息对象，表示当前页面状态。

常见字段：

• path
• params
• query
• name
• meta
• matched
• hash

最短记忆：

• router 用来跳
• route 用来看

routes

路由表，用来定义“什么 URL 对应什么组件”。

<router-view>

路由出口，匹配到的组件最终渲染在这里。

<router-link>

声明式导航组件，适合在模板中写页面跳转。

一个最小示例

// router/index.js
import { createRouter, createWebHistory } from 'vue-router'

const Home = () => import('../views/Home.vue')
const About = () => import('../views/About.vue')

const routes = [
  {
    path: '/',
    name: 'home',
    component: Home
  },
  {
    path: '/about',
    name: 'about',
    component: About
  }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router

<!-- App.vue -->
<template>
  <router-link to="/">首页</router-link>
  <router-link to="/about">关于</router-link>

  <router-view />
</template>

三种 history 模式

createWebHistory()

标准 History 路由，URL 更自然，例如 /about。

优点是 URL 干净；代价是部署时需要服务端把前端路由回退到 index.html。

createWebHashHistory()

Hash 路由，URL 形如 /#/about。

优点是部署简单，不依赖服务端路由回退；代价是 URL 不够自然。

createMemoryHistory()

内存路由，不直接依赖浏览器地址栏，常见于 SSR 或测试环境。

日常最常用的能力

声明式导航

<router-link to="/about">关于</router-link>

适合普通链接跳转。

编程式导航

router.push('/about')
router.replace('/login')
router.go(-1)

适合登录成功跳转、提交成功跳转、守卫里重定向等场景。

动态路由

{
  path: '/article/:id',
  name: 'article',
  component: ArticleDetail
}

const route = useRoute()
console.log(route.params.id)

query

router.push({
  path: '/search',
  query: { keyword: 'vue', page: 2 }
})

适合搜索、筛选、分页等附加状态。

嵌套路由

适合后台布局页、用户中心、设置页这类“父页面包子页面”的结构。

父组件必须提供 <router-view> 给子路由渲染。

404 路由

{
  path: '/:pathMatch(.*)*',
  name: 'not-found',
  component: NotFound
}

通常放在路由表最后。

params 和 query 的区别

• params 是路径结构的一部分，更像“资源是谁”，例如 /user/:id
• query 是附加条件，更像“你想怎么查”，例如 /search?keyword=vue&page=2

推荐：

router.push({
  name: 'user',
  params: { id: 1 }
})

不推荐把 path 写死后再混用 params，因为这时参数常会被忽略。

导航守卫、meta 与工程协作

Vue Router 本身不只负责页面切换，还常作为工程骨架的一部分。

导航守卫

常见用法：

• 登录校验
• 权限校验
• 页面离开确认
• 统计与埋点

meta

适合放：

• title
• requiresAuth
• role
• keepAlive

模块化路由

中大型项目通常会：

• 用布局路由承载页面骨架
• 按业务模块拆分路由文件
• 让菜单、权限和路由结构共用一套骨架

延伸看：

• vue-router-guards-and-permission-control
• vue-router-module-design

常见问题

history 模式刷新 404

原因不是 Vue Router 本身，而是服务器直接去请求 /about 这类路径，如果没有回退到 index.html 就会 404。

同一路由参数变化但组件不刷新

例如从 /article/1 到 /article/2 仍然是同一个组件，组件可能被复用。

常见处理方式：

• watch(() => route.params.id, ...)
• onBeforeRouteUpdate(...)

嵌套路由不显示

通常是父组件漏写了 <router-view />。

用普通 <a> 导致整页刷新

在 SPA 内部导航里应优先使用 <router-link>。

404 路由放太前面

兜底路由写太前会把后面的正常路由直接吃掉。

一条完整主线

用户点击链接或代码调用 router.push() 后：

1. URL 发生变化
2. Vue Router 根据 routes 做匹配
3. 提取 params、query、hash 和 meta
4. 执行导航守卫
5. 确认导航
6. 把匹配组件渲染到 <router-view>

这就是 SPA 中“不整页刷新但页面切换正常发生”的核心链路。

面试或复习时的最短表达

Vue Router 是 Vue 官方客户端路由方案。它基于浏览器的 hash 或 history 机制监听 URL 变化，再根据路由表把路径映射到组件，并结合守卫、meta、嵌套路由和懒加载组织中大型应用的页面系统。

Related notes

• Vue MOC