unplugin-vue-router 路由扩展指南

unplugin-vue-router 路由扩展指南

前言

在现代 Vue 项目中，路由管理是一个核心功能。unplugin-vue-router 作为一款创新的路由解决方案，提供了多种灵活的方式来扩展和定制路由配置。本文将深入探讨如何在构建时和运行时扩展路由，以及如何在组件内部定义路由元信息。

构建时路由扩展

使用 extendRoute 和 beforeWriteFiles

在构建阶段，我们可以通过配置选项来修改和扩展路由：

import VueRouter from 'unplugin-vue-router/vite'

VueRouter({
  extendRoute(route) {
    // 为特定路由添加别名
    if (route.name === '/[name]') {
      route.addAlias('/hello-vite-:name')
    }
  },

  beforeWriteFiles(root) {
    // 在根路由下插入新路由
    root.insert('/from-root', './src/pages/index.vue')
  },
})

这两种方法都支持异步操作（可以返回 Promise），修改后的路由会反映在生成的类型定义文件中。

组件内路由定义

definePage 宏

definePage 是一个全局可用的宏（无需导入），允许我们在组件内部定义路由元信息：

<script setup>
definePage({
  alias: ['/n/:name'],  // 路由别名
  meta: {
    requiresAuth: true, // 自定义元信息
  },
})
</script>

重要限制：

• 参数必须是静态的，不能使用变量
• 类似于 Nuxt 的 definePageMeta，参数会在构建时被提取并移除

SFC 自定义路由块

Vue 单文件组件支持 <route> 自定义块来覆盖路由配置：

<route lang="yaml">
name: name-override
meta:
  requiresAuth: false
</route>

支持的语言格式：

• JSON5（默认，更宽松的 JSON）
• JSON
• YAML

运行时路由扩展

虽然不推荐，但在某些特殊场景下，我们可以在运行时修改路由：

import { routes } from 'vue-router/auto-routes'

// 修改现有路由
routes.forEach(route => {
  if (route.name === '/admin') {
    route.meta = { ...route.meta, requiresAuth: true }
  }
})

// 添加新路由（如重定向）
routes.push({
  path: '/old-path',
  redirect: '/new-path'
})

注意事项：

1. 运行时修改不会反映在类型定义中
2. 需要特殊处理热模块替换（HMR）
3. 适用于集成某些特定插件（如布局系统）

最佳实践建议

1. 优先使用构建时扩展：能获得更好的类型支持和开发体验
2. 合理使用组件内定义：适合定义与组件紧密相关的元信息
3. 谨慎使用运行时扩展：仅在必要场景下使用，并注意类型安全
4. 保持一致性：团队应约定统一的扩展方式，避免混用造成混乱

通过合理运用这些扩展机制，开发者可以构建出既灵活又类型安全的路由系统，满足各种复杂应用场景的需求。