Vue Router 完全指南：v4 路由模式、导航守卫、动态路由、懒加载与生产实践

// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'Home',
      component: Home,
    },
    {
      path: '/about',
      name: 'About',
      component: () => import('../views/About.vue'),  // 懒加载
    },
    {
      path: '/users/:id',
      name: 'UserProfile',
      component: () => import('../views/UserProfile.vue'),
      props: true,  // 将路由参数作为 props 传递
    },
  ],
})

export default router

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

createApp(App).use(router).mount('#app')

<!-- App.vue -->
<template>
  <nav>
    <RouterLink to="/">Home</RouterLink>
    <RouterLink to="/about">About</RouterLink>
  </nav>
  <main>
    <RouterView />  <!-- 路由组件渲染位置 -->
  </main>
</template>

const routes = [
  {
    path: '/dashboard',
    component: DashboardLayout,
    children: [
      { path: '', name: 'DashboardHome', component: DashboardHome },           // /dashboard
      { path: 'analytics', name: 'Analytics', component: Analytics },          // /dashboard/analytics
      { path: 'settings', name: 'Settings', component: Settings },             // /dashboard/settings
    ],
  },
]

<!-- DashboardLayout.vue -->
<template>
  <div class="dashboard">
    <Sidebar />
    <div class="content">
      <RouterView />  <!-- 渲染子路由组件 -->
    </div>
  </div>
</template>

const routes = [
  {
    path: '/',
    components: {
      default: Home,
      sidebar: Sidebar,     // <RouterView name="sidebar" />
      footer: Footer,       // <RouterView name="footer" />
    },
  },
]

const routes = [
  // /users/123 → { id: '123' }
  { path: '/users/:id', component: UserProfile, props: true },

  // /posts/2024/08/article-slug → { year: '2024', month: '08', slug: 'article-slug' }
  { path: '/posts/:year/:month/:slug', component: PostDetail },

  // 可选参数（?）
  { path: '/users/:id?', component: UserProfile },  // /users 和 /users/123 都匹配

  // 正则限制
  { path: '/users/:id(\\d+)', component: UserById },  // 只允许数字
]

<script setup>
import { useRoute } from 'vue-router'
import { watch } from 'vue'

const route = useRoute()

// 读取参数
console.log(route.params.id)

// 读取查询参数 /search?q=vue → { q: 'vue' }
console.log(route.query.q)

// 读取 hash
console.log(route.hash)

// 监听参数变化（组件复用时不会重新挂载）
watch(() => route.params.id, (newId) => {
  fetchUser(newId)
})
</script>

import { useRouter } from 'vue-router'

const router = useRouter()

// 字符串路径
router.push('/users/123')

// 带查询参数
router.push({ path: '/search', query: { q: 'vue' } })

// 命名路由 + 参数
router.push({ name: 'UserProfile', params: { id: '123' } })

// 替换当前历史（不增加记录）
router.replace('/home')

// 后退
router.back()
router.go(-1)

// router/index.ts
router.beforeEach(async (to, from) => {
  const authStore = useAuthStore()

  // 需要登录但未登录 → 跳转登录
  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
    return { name: 'Login', query: { redirect: to.fullPath } }
  }

  // 需要管理员权限
  if (to.meta.requiresAdmin && authStore.user?.role !== 'admin') {
    return { name: 'Unauthorized' }
  }

  // 已登录访问登录页 → 跳转首页
  if (to.name === 'Login' && authStore.isLoggedIn) {
    return { name: 'Home' }
  }
})

const routes = [
  {
    path: '/admin',
    component: AdminPanel,
    beforeEnter: (to, from) => {
      const auth = useAuthStore()
      if (!auth.isAdmin) return { name: 'Unauthorized' }
    },
  },
]

<script setup>
import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router'

// 离开守卫（如未保存表单时确认）
onBeforeRouteLeave((to, from) => {
  const answer = window.confirm('You have unsaved changes. Leave?')
  if (!answer) return false  // 阻止导航
})

// 组件复用时更新（如 /users/1 → /users/2）
onBeforeRouteUpdate((to, from) => {
  // 复用组件，只需更新数据
  userId.value = to.params.id
  fetchUserData(to.params.id)
})
</script>

const router = createRouter({
  history: createWebHistory(),
  routes,
  scrollBehavior(to, from, savedPosition) {
    // 返回历史位置（浏览器前进/后退）
    if (savedPosition) {
      return savedPosition
    }

    // hash 锚点跳转
    if (to.hash) {
      return { el: to.hash, behavior: 'smooth' }
    }

    // 默认滚动到顶部
    return { top: 0, left: 0 }
  },
})

<template>
  <RouterView v-slot="{ Component }">
    <Transition name="fade" mode="out-in">
      <component :is="Component" />
    </Transition>
  </RouterView>
</template>

<style>
.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.3s ease;
}
.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}
</style>

const routes = [
  {
    path: '/dashboard',
    component: () => import('../views/Dashboard.vue'),
    // Webpack chunk name（Vite 需配置）
    // component: () => import(/* webpackChunkName: "dashboard" */ '../views/Dashboard.vue'),
  },
]

<script setup>
// 鼠标悬停时预加载
const prefetchDashboard = () => {
  import('../views/Dashboard.vue')
}
</script>

<template>
  <RouterLink to="/dashboard" @mouseenter="prefetchDashboard">
    Dashboard
  </RouterLink>
</template>

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

const routes = [
  {
    path: '/admin',
    component: AdminLayout,
    meta: {
      requiresAuth: true,
      requiresAdmin: true,
      title: '管理后台',
      breadcrumb: [
        { label: '首页', path: '/' },
        { label: '管理后台', path: '/admin' }
      ]
    },
    children: [
      {
        path: 'users',
        component: UserManagement,
        meta: {
          title: '用户管理',
          breadcrumb: [
            { label: '首页', path: '/' },
            { label: '管理后台', path: '/admin' },
            { label: '用户管理', path: '/admin/users' }
          ]
        }
      }
    ]
  }
]

// 全局后置守卫：设置页面标题
router.afterEach((to) => {
  const title = to.meta.title as string
  if (title) {
    document.title = `${title} | My App`
  }
})

// 面包屑组件
<script setup>
import { useRoute, useRouter } from 'vue-router'
const route = useRoute()
const router = useRouter()

const breadcrumbs = computed(() => {
  const matched = route.matched.filter(r => r.meta?.breadcrumb)
  return matched.flatMap(r => r.meta.breadcrumb as BreadcrumbItem[])
})
</script>

// 定义路由名称枚举
export enum RouteNames {
  Home = 'Home',
  UserProfile = 'UserProfile',
  Dashboard = 'Dashboard',
  NotFound = 'NotFound'
}

// 定义路由参数类型
export interface RouteParams {
  [RouteNames.UserProfile]: { id: string }
  [RouteNames.Dashboard]: { tab?: string }
}

// 类型安全的 router.push
export function push<K extends keyof RouteParams>(
  name: K,
  params: RouteParams[K]
) {
  return router.push({ name, params })
}

// 使用
push(RouteNames.UserProfile, { id: '123' })  // ✅ 类型安全
push(RouteNames.UserProfile, { id: 123 })    // ❌ 类型错误

<script setup>
// 页面级守卫
definePageMeta({
  middleware: 'auth',  // 使用中间件
  requiresAuth: true
})

// useRoute / useRouter 与 Vue Router 一致
const route = useRoute()
const router = useRouter()
</script>