路由基础

┌────────────────────────────────────────────────────────────────┐
│                      Vue Router 架构                            │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │
│  │   URL 变化   │───>│  Router     │───>│  Component  │        │
│  │  (浏览器)    │    │  匹配路由    │    │  渲染组件    │        │
│  └─────────────┘    └─────────────┘    └─────────────┘        │
│                            │                                   │
│                            ▼                                   │
│                    ┌─────────────┐                            │
│                    │ router-view │                            │
│                    │  渲染出口    │                            │
│                    └─────────────┘                            │
│                                                                │
│  核心组件:                                                      │
│  ┌─────────────────┐    ┌─────────────────┐                   │
│  │  router-link    │    │  router-view    │                   │
│  │  导航链接组件    │    │  路由出口组件    │                   │
│  └─────────────────┘    └─────────────────┘                   │
│                                                                │
└────────────────────────────────────────────────────────────────┘

# 使用 Vue CLI 创建项目时选择 Router
npm create vue@latest

# 或手动安装
npm install vue-router@4

src/
├── router/
│   └── index.js        # 路由配置文件
├── views/              # 页面组件
│   ├── Home.vue
│   └── About.vue
├── App.vue             # 根组件
└── main.js             # 入口文件

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

// 路由配置数组
const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home,
    meta: { title: '首页' }
  },
  {
    path: '/about',
    name: 'About',
    // 懒加载：按需导入
    component: () => import('../views/About.vue'),
    meta: { title: '关于我们' }
  }
]

// 创建路由实例
const router = createRouter({
  // 路由模式
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

export default router

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

const app = createApp(App)

// 注册路由插件
app.use(router)

app.mount('#app')

<!-- App.vue -->
<template>
  <div id="app">
    <!-- 导航链接 -->
    <nav>
      <router-link to="/">首页</router-link>
      <router-link to="/about">关于</router-link>
    </nav>
    
    <!-- 路由出口：匹配的组件将渲染在这里 -->
    <router-view />
  </div>
</template>

<template>
  <!-- 1. 字符串路径 -->
  <router-link to="/home">首页</router-link>
  
  <!-- 2. 对象形式：命名路由 -->
  <router-link :to="{ name: 'Home' }">首页</router-link>
  
  <!-- 3. 对象形式：路径 -->
  <router-link :to="{ path: '/home' }">首页</router-link>
  
  <!-- 4. 带路径参数 -->
  <router-link :to="{ name: 'User', params: { id: 1 } }">
    用户详情
  </router-link>
  
  <!-- 5. 带查询参数 -->
  <router-link :to="{ path: '/search', query: { q: 'vue', page: 1 } }">
    搜索结果
  </router-link>
  
  <!-- 6. 带 hash -->
  <router-link :to="{ path: '/about', hash: '#team' }">
    关于我们（团队介绍）
  </router-link>
  
  <!-- 7. 替换历史记录 -->
  <router-link to="/home" replace>首页（不留历史记录）</router-link>
  
  <!-- 8. 自定义激活样式 -->
  <router-link to="/home" active-class="active" exact-active-class="exact-active">
    首页
  </router-link>
</template>

<template>
  <router-link
    to="/home"
    custom
    v-slot="{ isActive, isExactActive, href, navigate, route }"
  >
    <li :class="{ active: isActive, exact: isExactActive }">
      <a :href="href" @click="navigate">
        {{ isActive ? '✓ ' : '' }}首页
      </a>
    </li>
  </router-link>
</template>

<script setup>
// v-slot 提供的属性：
// - isActive: 是否处于激活状态（包含子路由）
// - isExactActive: 是否精确匹配激活
// - href: 解析后的 URL
// - navigate: 导航函数
// - route: 解析后的路由对象
</script>

<template>
  <router-link to="/home" custom v-slot="{ navigate, isActive }">
    <button 
      @click="navigate" 
      :class="{ active: isActive }"
      role="link"
    >
      前往首页
    </button>
  </router-link>
</template>

<template>
  <!-- 基本用法 -->
  <router-view />
  
  <!-- 命名视图 -->
  <router-view name="sidebar" />
  <router-view name="main" />
  
  <!-- 默认视图 + 命名视图 -->
  <router-view />
  <router-view name="footer" />
</template>

<template>
  <!-- 方式1：简单过渡 -->
  <router-view v-slot="{ Component }">
    <transition name="fade" mode="out-in">
      <component :is="Component" />
    </transition>
  </router-view>
  
  <!-- 方式2：基于路由的过渡 -->
  <router-view v-slot="{ Component, route }">
    <transition :name="route.meta.transition || 'fade'" mode="out-in">
      <component :is="Component" :key="route.path" />
    </transition>
  </router-view>
</template>

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

.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}

.slide-enter-active,
.slide-leave-active {
  transition: transform 0.3s ease;
}

.slide-enter-from {
  transform: translateX(100%);
}

.slide-leave-to {
  transform: translateX(-100%);
}
</style>

<template>
  <router-view v-slot="{ Component }">
    <Suspense>
      <component :is="Component" />
      
      <template #fallback>
        <div class="loading">加载中...</div>
      </template>
    </Suspense>
  </router-view>
</template>

<template>
  <!-- 向路由组件传递 props -->
  <router-view :user="currentUser" />
</template>

<script setup>
import { ref } from 'vue'

const currentUser = ref({ id: 1, name: '张三' })
</script>

import { 
  createRouter, 
  createWebHistory,
  createWebHashHistory,
  createMemoryHistory 
} from 'vue-router'

// HTML5 History 模式（推荐）
const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

// Hash 模式
const router = createRouter({
  history: createWebHashHistory(),
  routes
})

// Memory 模式（用于 SSR 或测试）
const router = createRouter({
  history: createMemoryHistory(),
  routes
})

# Nginx 配置
location / {
  try_files $uri $uri/ /index.html;
}

# Apache 配置
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

// Vite 开发服务器配置
export default {
  server: {
    historyApiFallback: true
  }
}

interface RouteRecord {
  path: string                    // 路由路径
  name?: string | symbol          // 路由名称（唯一标识）
  component?: Component           // 路由组件
  components?: Record<string, Component>  // 命名视图组件
  redirect?: string | Location | Function // 重定向
  alias?: string | string[]       // 别名
  children?: RouteRecord[]        // 嵌套子路由
  meta?: Record<string, any>      // 路由元信息
  beforeEnter?: NavigationGuard | NavigationGuard[]  // 路由守卫
  props?: boolean | Object | Function  // 传递 props
  caseSensitive?: boolean         // 是否区分大小写
  pathToRegexpOptions?: Object    // 正则配置
}

const routes = [
  // 基本路由
  {
    path: '/',
    name: 'Home',
    component: () => import('@/views/Home.vue'),
    meta: { title: '首页', requiresAuth: false }
  },
  
  // 动态路由
  {
    path: '/user/:id',
    name: 'User',
    component: () => import('@/views/User.vue'),
    props: true,  // 将 params 作为 props 传入
    meta: { requiresAuth: true },
    beforeEnter: (to, from) => {
      // 路由独享守卫
      if (!isValidUserId(to.params.id)) {
        return { name: 'NotFound' }
      }
    }
  },
  
  // 嵌套路由
  {
    path: '/settings',
    component: () => import('@/views/Settings.vue'),
    children: [
      {
        path: '',           // 默认子路由
        name: 'SettingsProfile',
        component: () => import('@/views/SettingsProfile.vue')
      },
      {
        path: 'account',
        name: 'SettingsAccount',
        component: () => import('@/views/SettingsAccount.vue')
      }
    ]
  },
  
  // 命名视图
  {
    path: '/dashboard',
    components: {
      default: () => import('@/views/Dashboard.vue'),
      sidebar: () => import('@/views/Sidebar.vue'),
      header: () => import('@/views/Header.vue')
    }
  },
  
  // 重定向
  {
    path: '/home',
    redirect: '/'
  },
  
  // 别名
  {
    path: '/users/:id',
    component: () => import('@/views/User.vue'),
    alias: ['/u/:id', '/user/:id']
  },
  
  // 404 捕获
  {
    path: '/:pathMatch(.*)*',
    name: 'NotFound',
    component: () => import('@/views/NotFound.vue')
  }
]

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

// router：路由实例，用于导航等方法
const router = useRouter()

// route：当前路由对象（响应式，只读）
const route = useRoute()

// 导航方法
function goHome() {
  router.push('/')
}

function goBack() {
  router.back()
}

// 访问当前路由信息
console.log(route.path)      // 当前路径
console.log(route.params)    // 路径参数
console.log(route.query)     // 查询参数
console.log(route.meta)      // 元信息
console.log(route.name)      // 路由名称
</script>

<script setup>
import { ref, watch, computed } from 'vue'
import { useRoute, useRouter } from 'vue-router'

const route = useRoute()
const router = useRouter()

// 响应式获取路由参数
const userId = computed(() => route.params.id)

// 监听路由变化
watch(
  () => route.params.id,
  async (newId) => {
    if (newId) {
      await fetchUserData(newId)
    }
  },
  { immediate: true }
)

// 编程式导航
function navigateToUser(id) {
  router.push({ name: 'User', params: { id } })
}

// 带回调的导航
async function navigateWithCallback() {
  try {
    await router.push('/protected')
    console.log('导航成功')
  } catch (error) {
    console.log('导航失败:', error)
  }
}
</script>

# Nginx
location / {
  try_files $uri $uri/ /index.html;
}

<template>
  <!-- 使用默认类名 -->
  <router-link to="/home">首页</router-link>
</template>

<style>
/* 默认激活类名 */
.router-link-active {
  color: #42b983;
}

/* 精确匹配激活 */
.router-link-exact-active {
  color: #42b983;
  font-weight: bold;
}

/* 或自定义类名 */
<router-link to="/home" active-class="my-active">
  首页
</router-link>
</style>

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

const route = useRoute()

// 方式1：监听路由变化
watch(() => route.params.id, (newId) => {
  fetchData(newId)
})
</script>

<!-- 方式2：使用 key 强制重新渲染 -->
<template>
  <router-view :key="$route.fullPath" />
</template>

// vite.config.js
export default {
  base: '/my-app/'  // 子目录部署
}

// router/index.js
const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

// 使用有意义的命名，便于维护
const routes = [
  { path: '/user/:id', name: 'UserDetail', component: UserDetail },
  { path: '/user/:id/edit', name: 'UserEdit', component: UserEdit },
  
  // 嵌套路由命名约定
  { 
    path: '/settings', 
    name: 'Settings',
    component: Settings,
    children: [
      { path: 'profile', name: 'SettingsProfile', component: Profile },
      { path: 'account', name: 'SettingsAccount', component: Account }
    ]
  }
]

// router/modules/user.js
export default [
  {
    path: '/user',
    component: () => import('@/layouts/UserLayout.vue'),
    children: [
      {
        path: '',
        name: 'UserList',
        component: () => import('@/views/user/List.vue')
      },
      {
        path: ':id',
        name: 'UserDetail',
        component: () => import('@/views/user/Detail.vue')
      }
    ]
  }
]

// router/index.js
import userRoutes from './modules/user'
import productRoutes from './modules/product'

const routes = [
  ...userRoutes,
  ...productRoutes,
  { path: '/:pathMatch(.*)*', component: NotFound }
]

// types/router.d.ts
import 'vue-router'

declare module 'vue-router' {
  interface RouteMeta {
    title?: string
    requiresAuth?: boolean
    roles?: string[]
    breadcrumb?: { title: string; path?: string }[]
  }
}

// 使用时自动提示
const routes = [
  {
    path: '/admin',
    meta: {
      title: '管理后台',      // ✓ 类型提示
      requiresAuth: true,    // ✓ 类型提示
      roles: ['admin']       // ✓ 类型提示
    }
  }
]

┌─────────────────────────────────────────────────────────────┐
│                    动态路由匹配示意                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  URL 请求: /users/123                                       │
│           ──────── ───                                      │
│             路径    参数                                     │
│                     │                                       │
│                     ▼                                       │
│  路由配置: /users/:id                                       │
│                    ───                                      │
│                   动态字段                                   │
│                                                             │
│  匹配结果:                                                  │
│  route.params = { id: '123' }                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

const routes = [
  // 单个参数
  { path: '/users/:id', component: User },
  
  // 多个参数
  { path: '/users/:userId/posts/:postId', component: UserPost },
  
  // 匹配示例：
  // /users/123              → params: { id: '123' }
  // /users/abc/posts/456    → params: { userId: 'abc', postId: '456' }
]

<template>
  <div>
    <h2>用户详情</h2>
    <p>用户 ID: {{ $route.params.id }}</p>
  </div>
</template>

<script>
export default {
  created() {
    console.log(this.$route.params.id)
  }
}
</script>

<template>
  <div>
    <h2>用户详情</h2>
    <p>用户 ID: {{ userId }}</p>
  </div>
</template>

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

const route = useRoute()

// 响应式获取参数
const userId = computed(() => route.params.id)

// 直接访问（非响应式）
console.log(route.params.id)
</script>

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

const route = useRoute()
const user = ref(null)

// 方式1：watch 监听（推荐）
watch(
  () => route.params.id,
  async (newId) => {
    if (newId) {
      user.value = await fetchUser(newId)
    }
  },
  { immediate: true }  // 立即执行一次
)

// 方式2：使用路由守卫
import { onBeforeRouteUpdate } from 'vue-router'

onBeforeRouteUpdate(async (to) => {
  if (to.params.id !== route.params.id) {
    user.value = await fetchUser(to.params.id)
  }
  return true
})
</script>

const routes = [
  // ? 表示参数可选
  { path: '/users/:id?', component: User },
  
  // 匹配:
  // /users      → params: {} 或 { id: undefined }
  // /users/123  → params: { id: '123' }
]

const routes = [
  // + 表示一个或多个
  { path: '/:chapters+', component: Chapters },
  // 匹配: /one, /one/two, /one/two/three
  // params: { chapters: ['one', 'two', 'three'] }
  
  // * 表示零个或多个
  { path: '/:chapters*', component: Chapters },
  // 匹配: /, /one, /one/two
  // params: { chapters: ['one', 'two'] } 或 []
]

<template>
  <div>
    <h2>文档浏览</h2>
    <p>路径: {{ chapters.join(' / ') }}</p>
  </div>
</template>

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

const route = useRoute()

// 路由: /docs/:pathMatch+*
// URL: /docs/guide/getting-started
const chapters = computed(() => {
  const path = route.params.pathMatch
  return Array.isArray(path) ? path : [path]
})
</script>

const routes = [
  // 只匹配数字
  { path: '/users/:id(\\d+)', component: User },
  // /users/123  ✓ 匹配
  // /users/abc  ✗ 不匹配
  
  // 只匹配字母
  { path: '/products/:name([a-z]+)', component: Product },
  // /products/phone  ✓ 匹配
  // /products/Phone  ✗ 不匹配（区分大小写）
  
  // 自定义正则
  { path: '/orders/:orderId(ORD-\\d{6})', component: Order },
  // /orders/ORD-123456  ✓ 匹配
  // /orders/123456      ✗ 不匹配
]

const routes = [
  // 匹配邮箱格式的用户名
  { 
    path: '/profile/:email([\\w.-]+@[\\w.-]+\\.\\w+)', 
    component: Profile 
  },
  // /profile/user@example.com  ✓ 匹配
  
  // 匹配日期格式
  { 
    path: '/archive/:date(\\d{4}-\\d{2}-\\d{2})', 
    component: Archive 
  },
  // /archive/2024-01-15  ✓ 匹配
  
  // 匹配 UUID
  { 
    path: '/items/:uuid([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})',
    component: Item 
  },
  // /items/550e8400-e29b-41d4-a716-446655440000  ✓ 匹配
]

const routes = [
  // Vue Router 4 推荐写法
  { 
    path: '/:pathMatch(.*)*', 
    name: 'NotFound',
    component: () => import('@/views/NotFound.vue')
  },
  // * 表示可以匹配多个路径段
  // 匹配: /anything, /nested/path, /deep/nested/path
  
  // 单段匹配
  { 
    path: '/:pathMatch(.*)', 
    component: NotFound 
  },
  // 只匹配单段，如 /404，不匹配 /a/b
]

const routes = [
  // 匹配特定前缀后的所有路径
  { 
    path: '/docs/:pathMatch(.*)*', 
    component: DocsViewer 
  },
  // /docs/guide/intro
  // /docs/api/components/button
  
  // 捕获并获取完整路径
  { 
    path: '/legacy/:pathMatch(.*)',
    redirect: to => {
      const path = to.params.pathMatch
      return `/new-path/${path}`
    }
  }
]

// 路由配置
const routes = [
  // 布尔模式：将 params 作为 props
  { 
    path: '/user/:id', 
    component: User,
    props: true 
  },
  
  // 对象模式：静态 props
  { 
    path: '/search', 
    component: Search,
    props: { showFilter: true } 
  },
  
  // 函数模式：动态 props
  { 
    path: '/user/:id',
    component: User,
    props: route => ({
      id: parseInt(route.params.id),
      query: route.query
    })
  }
]

<script setup>
// 接收 props
const props = defineProps({
  id: {
    type: [String, Number],
    required: true
  },
  query: {
    type: Object,
    default: () => ({})
  }
})

// props.id 就是路由参数
console.log(props.id)
</script>

const routes = [
  {
    path: '/user/:id',
    components: {
      default: User,
      sidebar: Sidebar
    },
    props: {
      default: true,           // User 组件接收 params
      sidebar: { showMenu: true }  // Sidebar 接收静态 props
    }
  }
]

// types/router.d.ts
import 'vue-router'

declare module 'vue-router' {
  interface RouteParams {
    id?: string
    userId?: string
    postId?: string
  }
  
  interface RouteMeta {
    title?: string
  }
}

// composables/useTypedRoute.ts
import { useRoute } from 'vue-router'
import { computed } from 'vue'

export function useTypedRoute<T extends Record<string, string>>() {
  const route = useRoute()
  
  return {
    params: computed(() => route.params as T),
    query: computed(() => route.query as Record<string, string | undefined>),
    // ...其他属性
  }
}

// 使用
const { params } = useTypedRoute<{ id: string; postId: string }>()
console.log(params.value.id)  // 类型安全

<script setup lang="ts">
import { useRoute } from 'vue-router'

interface UserParams {
  id: string
}

const route = useRoute()

// 类型断言
const id = route.params.id as string

// 或使用泛型函数
function getParam<K extends keyof UserParams>(key: K): UserParams[K] {
  return route.params[key] as UserParams[K]
}
</script>

const routes = [
  // 具体路径优先
  { path: '/users/create', component: UserCreate },
  { path: '/users/:id', component: UserDetail },
  
  // 带正则的优先
  { path: '/users/:id(\\d+)', component: UserById },
  { path: '/users/:name([a-z]+)', component: UserByName },
  { path: '/users/:slug', component: UserBySlug },
  
  // 通配符放最后
  { path: '/:pathMatch(.*)*', component: NotFound }
]

const routes = [
  // 数字 ID
  { 
    path: '/orders/:id(\\d+)', 
    component: OrderById,
    meta: { type: 'byId' }
  },
  
  // 订单编号
  { 
    path: '/orders/:orderNo(ORD-\\w+)', 
    component: OrderByNo,
    meta: { type: 'byOrderNo' }
  },
  
  // 通用 slug
  { 
    path: '/orders/:slug', 
    component: OrderBySlug,
    meta: { type: 'bySlug' }
  }
]

// URL: /users/123
const route = useRoute()
console.log(typeof route.params.id)  // 'string'

// 需要手动转换
const id = Number(route.params.id)

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

const route = useRoute()

// 计算属性转换类型
const userId = computed(() => Number(route.params.id))
const page = computed(() => Number(route.query.page) || 1)
</script>

// 检查路由是否匹配
router.beforeEach((to) => {
  if (to.matched.length === 0) {
    return '/404'  // 无匹配路由
  }
})

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

const route = useRoute()

// 处理可选参数
const category = computed(() => route.params.category || 'all')
const page = computed(() => Number(route.query.page) || 1)
</script>

// URL 编码自动处理
router.push({ 
  path: '/search', 
  query: { q: 'hello world' } 
})
// 实际 URL: /search?q=hello%20world

// 获取时自动解码
console.log(route.query.q)  // 'hello world'

// utils/routeValidators.js
export function validateUserId(id) {
  return /^\d+$/.test(id)
}

export function validateUUID(uuid) {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(uuid)
}

// 路由守卫中使用
router.beforeEach((to) => {
  if (to.name === 'UserDetail') {
    if (!validateUserId(to.params.id)) {
      return { name: 'NotFound' }
    }
  }
})

// composables/useRouteParams.js
import { computed } from 'vue'
import { useRoute } from 'vue-router'

export function useRouteParams() {
  const route = useRoute()
  
  const numericId = computed(() => {
    const id = route.params.id
    return id ? Number(id) : null
  })
  
  const pageQuery = computed(() => {
    return Number(route.query.page) || 1
  })
  
  return {
    numericId,
    pageQuery
  }
}

// router/params.js
export const USER_ID_PATTERN = '(\\d+)'
export const UUID_PATTERN = '([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'

// router/index.js
import { USER_ID_PATTERN, UUID_PATTERN } from './params'

const routes = [
  { path: `/user/:id${USER_ID_PATTERN}`, component: User },
  { path: `/item/:uuid${UUID_PATTERN}`, component: Item }
]

// 简化版 createRouter 源码
import { ref, shallowRef, computed, markRaw } from 'vue'
import { createRouterMatcher } from './matcher'
import { RouterLink } from './RouterLink'
import { RouterView } from './RouterView'

interface RouterOptions {
  history: RouterHistory
  routes: RouteRecordRaw[]
  sensitive?: boolean
  strict?: boolean
}

export function createRouter(options: RouterOptions): Router {
  const { history, routes } = options

  // 1. 创建路由匹配器（核心：路径 → 路由记录的映射）
  const matcher = createRouterMatcher(routes, options)

  // 2. 创建响应式的当前路由状态
  const currentRoute = shallowRef<RouteLocationNormalized>(
    START_LOCATION_NORMALIZED
  )

  // 3. 路由实例
  const router: Router = markRaw({
    // 公开的当前路由（只读）
    currentRoute: computed(() => currentRoute.value),

    // 路由匹配方法
    resolve: (to: RouteLocationRaw, currentLocation?: RouteLocationNormalized) =>
      matcher.resolve(to, currentLocation ?? currentRoute.value),

    // 添加路由
    addRoute: (parentNameOrRecord, record?) => {
      matcher.addRoute(parentNameOrRecord, record)
    },

    // 移除路由
    removeRoute: (name) => {
      matcher.removeRoute(name)
    },

    // 获取所有路由
    getRoutes: () => matcher.getRoutes(),

    // 编程式导航
    push: (to) => pushWithRedirect(to),
    replace: (to) => pushWithRedirect(to, true),

    // 历史记录导航
    go: (delta) => history.go(delta),
    back: () => history.go(-1),
    forward: () => history.go(1),

    // 安装插件
    install(app: App) {
      const router = this

      // 注册全局组件
      app.component('RouterLink', RouterLink)
      app.component('RouterView', RouterView)

      // 注入全局属性
      app.config.globalProperties.$router = router
      app.config.globalProperties.$route = currentRoute

      // 使用 provide/inject 注入（组合式 API 使用）
      app.provide(routerKey, router)
      app.provide(routeLocationKey, computed(() => currentRoute.value))

      // 初始化导航
      const startupLocation = history.location
      pushWithRedirect(startupLocation)
    }
  })

  return router
}

// ─── createWebHistory ─────────────────────────────────────
// 基于 HTML5 History API (pushState / replaceState / popstate)
export function createWebHistory(base?: string): RouterHistory {
  base = normalizeBase(base)

  const historyNavigation = useHistoryStateNavigation(base)
  const historyListeners = useHistoryListeners(
    base,
    historyNavigation.state,
    historyNavigation.location
  )

  function go(delta: number, triggerListeners = true) {
    if (!triggerListeners) historyListeners.pauseListeners()
    history.go(delta)
  }

  const routerHistory: RouterHistory = {
    location: '',
    base,
    go,
    // pushState 实现
    push(to, data) {
      const currentState = historyNavigation.state.value
      historyNavigation.pushState(data, '', to.fullPath)
      // 更新内部状态
    },
    // replaceState 实现
    replace(to, data) {
      historyNavigation.replaceState(data, '', to.fullPath)
    },
    // 监听 popstate 事件
    listen(cb) {
      return historyListeners.listen(cb)
    },
    destroy() {
      historyListeners.destroy()
    }
  }

  return routerHistory
}

// ─── createWebHashHistory ──────────────────────────────────
// 基于 hashchange 事件，兼容性更好
export function createWebHashHistory(base?: string): RouterHistory {
  base = location.host ? base || location.pathname + location.search : ''

  // 确保 hash 以 / 开头
  if (!base.includes('#')) base += '#'

  function getHash(): string {
    let href = window.location.href
    const index = href.indexOf('#')
    if (index < 0) return ''
    href = href.slice(index + 1)
    const searchIndex = href.indexOf('?')
    if (searchIndex < 0) return href
    return href.slice(0, searchIndex)
  }

  function push(to, data) {
    window.location.hash = to.fullPath
  }

  function replace(to, data) {
    const href = window.location.href
    const hashIndex = href.indexOf('#')
    window.location.replace(
      href.slice(0, hashIndex >= 0 ? hashIndex : 0) + '#' + to.fullPath
    )
  }

  // 监听 hashchange 而非 popstate
  function listen(cb) {
    window.addEventListener('hashchange', cb)
    return () => window.removeEventListener('hashchange', cb)
  }

  return { location: getHash(), base, push, replace, listen }
}

// Router 的 install 方法 —— Vue 插件系统的核心
// app.use(router) 时调用

const routerKey = Symbol('router')
const routeLocationKey = Symbol('route location')
const routerViewLocationKey = Symbol('router view location')

install(app: App) {
  const router = this

  // 1. 注册全局组件
  // RouterLink —— 渲染为 <a> 标签，处理导航点击
  app.component('RouterLink', RouterLink)

  // RouterView —— 根据当前路由渲染匹配的组件
  app.component('RouterView', RouterView)

  // 2. 注入全局属性（选项式 API 中通过 this.$router / this.$route 访问）
  app.config.globalProperties.$router = router
  app.config.globalProperties.$route = reactive(currentRoute)

  // 3. provide/inject 注入（组合式 API 中通过 useRouter / useRoute 访问）
  app.provide(routerKey, router)
  app.provide(routeLocationKey, shallowRef(currentRoute))
  app.provide(routerViewLocationKey, shallowRef(currentRoute))

  // 4. 首次导航：解析当前 URL，触发初始路由匹配
  if (currentRoute === START_LOCATION_NORMALIZED) {
    push(history.location).catch(err => {
      warn('Unexpected error when starting the router:', err)
    })
  }
}

// useRouter 和 useRoute 的实现
// 通过 inject 从 Vue 的依赖注入系统中获取

export function useRouter(): Router {
  const router = inject(routerKey)
  if (!router) {
    throw new Error(
      'useRouter() 只能在 setup() 内部或 <script setup> 中使用'
    )
  }
  return router
}

export function useRoute(): RouteLocationNormalized {
  const route = inject(routeLocationKey)
  if (!route) {
    throw new Error(
      'useRoute() 只能在 setup() 内部或 <script setup> 中使用'
    )
  }
  return route
}

// 为什么使用 Symbol 作为 key？
// 1. 避免命名冲突 —— 用户无法通过字符串注入覆盖
// 2. 类型安全 —— TypeScript 可以精确推断类型
// 3. 封装性 —— 外部模块无法轻易获取到注入的实例

// 单例模式保证
// 多次调用 app.use(router) 不会重复注册
// Vue 的插件系统会检查重复安装并发出警告

// 简化版 resolve 实现
export function resolve(
  to: RouteLocationRaw,
  currentLocation?: RouteLocationNormalized
): RouteLocation & { href: string } {

  // 1. 标准化目标位置
  const targetLocation: RouteLocationRaw = typeof to === 'string'
    ? parseURL(to)
    : to

  // 2. 处理命名路由
  let matchedRoute: RouteRecordNormalized | undefined
  if (targetLocation.name) {
    // 按 name 查找路由记录
    matchedRoute = matcher.getRecordMatcher(targetLocation.name)
  }

  // 3. 处理路径路由
  if (targetLocation.path != null) {
    // 相对路径解析
    const resolvedPath = currentLocation
      ? resolveRelativePath(currentLocation.path, targetLocation.path)
      : targetLocation.path

    // 使用 path-to-regexp 匹配
    matchedRoute = matcher.resolveByPath(resolvedPath)
  }

  // 4. 构建完整的 RouteLocation
  const matched = matchedRoute
    ? matchedRoute.matched
    : []

  const fullPath = stringifyURL(
    matchedRoute?.path ?? targetLocation.path ?? '/',
    targetLocation.query ?? {},
    targetLocation.hash ?? ''
  )

  return {
    fullPath,
    path: matchedRoute?.path ?? '/',
    query: targetLocation.query ?? {},
    hash: targetLocation.hash ?? '',
    params: matchedRoute?.params ?? {},
    matched,
    meta: matched[matched.length - 1]?.meta ?? {},
    name: matchedRoute?.name,
    redirectedFrom: undefined,
    href: routerHistory.base + fullPath
  }
}

// path-to-regexp 编译示例
// 输入路径字符串 → 输出正则表达式 + 参数键数组

import { pathToRegexp, compile } from 'path-to-regexp'

// 示例 1：基本动态路由
const keys1: Key[] = []
const regex1 = pathToRegexp('/users/:id', keys1)
// regex1: /^\/users\/((?:[^\/]+?))(?:\/)?$/i
// keys1:  [{ name: 'id', modifier: '' }]

// 示例 2：带正则的动态路由
const keys2: Key[] = []
const regex2 = pathToRegexp('/users/:id(\\d+)', keys2)
// regex2: /^\/users\/((\d+))(?:\/)?$/i
// keys2:  [{ name: 'id', modifier: '' }]

// 示例 3：可选参数
const keys3: Key[] = []
const regex3 = pathToRegexp('/users/:id?', keys3)
// regex3: /^\/users(?:\/((?:[^\/]+?)))?(?:\/)?$/i
// keys3:  [{ name: 'id', modifier: '?' }]

// 示例 4：重复参数
const keys4: Key[] = []
const regex4 = pathToRegexp('/files/:path+', keys4)
// regex4: /^\/files\/((?:[^\/]+?)(?:\/(?:[^\/]+?))*)(?:\/)?$/i
// keys4:  [{ name: 'path', modifier: '+' }]

// 示例 5：通配符
const keys5: Key[] = []
const regex5 = pathToRegexp('/:pathMatch(.*)*', keys5)
// regex5: /^\/((.*))$/i
// keys5:  [{ name: 'pathMatch', modifier: '*' }]

┌─────────────────────────────────────────────────────────────────┐
│                    路由匹配完整流程                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  输入: URL "/users/42/posts/hello-world"                        │
│                                                                 │
│  Step 1: URL 解析                                               │
│  ┌──────────────────────────────────────┐                       │
│  │ path:  /users/42/posts/hello-world   │                       │
│  │ query: {}                            │                       │
│  │ hash:  ""                            │                       │
│  └──────────────────────────────────────┘                       │
│           │                                                      │
│           ▼                                                      │
│  Step 2: 路径分段                                                │
│  ┌──────────────────────────────────────┐                       │
│  │ segments: ['users', '42', 'posts',   │                       │
│  │            'hello-world']            │                       │
│  └──────────────────────────────────────┘                       │
│           │                                                      │
│           ▼                                                      │
│  Step 3: 遍历路由表，正则匹配                                     │
│  ┌──────────────────────────────────────┐                       │
│  │ /users/:id/posts/:slug               │  ← 匹配！              │
│  │ regex: /^\/users\/([^/]+)\/posts\/   │                       │
│  │         ([^/]+)$/                    │                       │
│  └──────────────────────────────────────┘                       │
│           │                                                      │
│           ▼                                                      │
│  Step 4: 提取参数                                                │
│  ┌──────────────────────────────────────┐                       │
│  │ params: {                            │                       │
│  │   id: '42',                          │                       │
│  │   slug: 'hello-world'                │                       │
│  │ }                                    │                       │
│  └──────────────────────────────────────┘                       │
│           │                                                      │
│           ▼                                                      │
│  Step 5: 构建 RouteLocation                                      │
│  ┌──────────────────────────────────────┐                       │
│  │ matched: [UserLayout, UserPost]      │                       │
│  │ meta: merged from all matched        │                       │
│  └──────────────────────────────────────┘                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

// Vue Router 的路由评分机制
// router.getRoutes() 返回的顺序就是匹配优先级

function computeScore(
  pattern: string,
  prefix: string = ''
): number[][] {
  // 评分是一个二维数组，用于比较路由优先级
  // 规则：
  // 1. 静态段 > 动态段 > 通配段
  // 2. 段数越多，优先级越高
  // 3. 同级比较：先定义的优先

  const segments = pattern.split('/').filter(Boolean)
  const scores: number[][] = []

  for (const segment of segments) {
    if (segment === '*') {
      scores.push([3])        // 通配符：最低优先级
    } else if (segment.startsWith(':')) {
      scores.push([2])        // 动态参数：中等优先级
    } else {
      scores.push([1])        // 静态段：最高优先级
    }
  }

  return scores
}

// 评分比较示例
// /users/create       → [[1], [1]]          优先级最高
// /users/:id          → [[1], [2]]          次之
// /users/:id(\\d+)    → [[1], [2]]          与上同级，按定义顺序
// /:pathMatch(.*)*    → [[3]]              优先级最低

// Vue Router 默认的 parseQuery 实现（简化版）
export function parseQuery(search: string): LocationQuery {
  const query: LocationQuery = {}

  if (search === '' || search === '?') return query

  const searchStr = search.startsWith('?') ? search.slice(1) : search

  for (const part of searchStr.split('&')) {
    if (part === '') continue

    const eqIndex = part.indexOf('=')
    let key: string
    let value: string

    if (eqIndex < 0) {
      key = decodeQueryValue(part)
      value = ''
    } else {
      key = decodeQueryValue(part.slice(0, eqIndex))
      value = decodeQueryValue(part.slice(eqIndex + 1))
    }

    // 处理数组参数：key[]=a&key[]=b → { key: ['a', 'b'] }
    if (key.endsWith('[]')) {
      const realKey = key.slice(0, -2)
      const existing = query[realKey]
      if (Array.isArray(existing)) {
        existing.push(value)
      } else if (existing != null) {
        query[realKey] = [existing as string, value]
      } else {
        query[realKey] = [value]
      }
    } else {
      // 重复 key 覆盖
      query[key] = value
    }
  }

  return query
}

// 自定义 stringifyQuery
export function stringifyQuery(query: LocationQueryRaw): string {
  const parts: string[] = []

  for (const key in query) {
    const value = query[key]
    if (value == null) continue

    if (Array.isArray(value)) {
      for (const item of value) {
        parts.push(
          encodeQueryValue(key) + '=' + encodeQueryValue(String(item))
        )
      }
    } else {
      parts.push(
        encodeQueryValue(key) + '=' + encodeQueryValue(String(value))
      )
    }
  }

  return parts.length > 0 ? '?' + parts.join('&') : ''
}

// ─── 策略 1：Vue Router 默认（类似 qs 简化版）───────────────
// 优点：支持数组（key[]=a&key[]=b）、null 值过滤
// 缺点：不支持嵌套对象

// ─── 策略 2：URLSearchParams（浏览器原生）───────────────────
const params = new URLSearchParams({ q: 'vue', page: '1' })
params.toString()  // 'q=vue&page=1'
// 优点：零依赖、浏览器原生
// 缺点：不支持数组、不支持 null 过滤

// ─── 策略 3：qs 库（功能最全）───────────────────────────────
import qs from 'qs'

// 序列化
qs.stringify({ filter: { status: 'active', type: 'admin' } })
// 'filter%5Bstatus%5D=active&filter%5Btype%5D=admin'

// 解析
qs.parse('filter[status]=active&filter[type]=admin')
// { filter: { status: 'active', type: 'admin' } }

// ─── 自定义 parseQuery 替换默认实现 ─────────────────────────
const router = createRouter({
  history: createWebHistory(),
  routes,
  parseQuery: (search: string) => {
    // 使用 qs 替换默认解析
    return qs.parse(search, { ignoreQueryPrefix: true })
  },
  stringifyQuery: (query: Record<string, any>) => {
    // 使用 qs 替换默认序列化
    return '?' + qs.stringify(query, { addQueryPrefix: false })
  }
})

// 路由参数中的特殊字符处理
// Vue Router 内部使用 encodeURIComponent / decodeURIComponent

// 编码规则
function encodeParam(value: string): string {
  return encodeURIComponent(value)
}

function decodeParam(value: string): string {
  return decodeURIComponent(value)
}

// 特殊字符测试
const testCases = [
  { input: 'hello world',   encoded: 'hello%20world' },
  { input: 'a+b',           encoded: 'a%2Bb' },        // + 需要编码
  { input: 'user@email',    encoded: 'user%40email' },  // @ 需要编码
  { input: 'path/to/file',  encoded: 'path%2Fto%2Ffile' }, // / 在参数中编码
  { input: '你好',          encoded: '%E4%BD%A0%E5%A5%BD' },
  { input: '🚀',            encoded: '%F0%9F%9A%80' },
]

// 生产级安全处理
function safeDecodeParam(value: string): string {
  try {
    return decodeURIComponent(value)
  } catch (e) {
    // 处理非法编码序列
    console.warn('Failed to decode param:', value, e)
    return value
  }
}

// 路径中包含特殊字符的路由参数
// /search/:query 中 query 可能包含 / ? # 等字符
// 解决方案：使用 query 参数而非 path 参数
router.push({
  name: 'Search',
  query: { q: 'vue/react/angular' }  // ✓ 安全
})
// 而非
router.push({
  name: 'Search',
  params: { query: 'vue/react/angular' }  // ✗ 会被解析为多段路径
})

// Unicode 字符在路由中的处理

// 1. 路径中的 Unicode（需要浏览器和服务器支持）
const routes = [
  // 中文路径
  { path: '/产品/:id', component: Product },
  // 实际 URL: /%E4%BA%A7%E5%93%81/123
  // 浏览器地址栏显示: /产品/123

  // Emoji 路径（不推荐，但技术上可行）
  { path: '/favorites/⭐', component: Favorites },
]

// 2. 参数中的 Unicode
// URL: /search?q=北京
// 自动编码为: /search?q=%E5%8C%97%E4%BA%AC
// route.query.q → '北京'（自动解码）

// 3. 兼容性检查
function isUnicodeRouteSafe(path: string): boolean {
  // 检查路径是否可以被正确编码
  try {
    const encoded = encodeURIComponent(path)
    const decoded = decodeURIComponent(encoded)
    return decoded === path
  } catch {
    return false
  }
}

// 4. 生产建议：路由路径使用 ASCII，参数支持 Unicode
// ✓ 推荐
{ path: '/products/:id', component: Product }
// 参数 id 可以是任意 Unicode 字符串

// ✗ 不推荐（兼容性问题）
{ path: '/产品/:id', component: Product }

# ─── Nginx 完整配置 ───────────────────────────────────────
server {
    listen 80;
    server_name example.com;
    root /var/www/dist;

    # SPA 回退配置
    location / {
        try_files $uri $uri/ /index.html;

        # 安全头
        add_header X-Frame-Options "SAMEORIGIN";
        add_header X-Content-Type-Options "nosniff";
    }

    # 静态资源缓存（带 hash 的文件长期缓存）
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # API 代理
    location /api/ {
        proxy_pass http://backend:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# ─── Apache (.htaccess) ────────────────────────────────────
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /

    # 如果请求的不是真实文件或目录
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d

    # 回退到 index.html
    RewriteRule ^ index.html [L]
</IfModule>

# 静态资源缓存
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 1 year"
    ExpiresByType application/javascript "access plus 1 year"
</IfModule>

// ─── Vercel (vercel.json) ─────────────────────────────────
{
  "rewrites": [
    {
      "source": "/((?!api/).*)",
      "destination": "/index.html"
    }
  ]
}

# ─── Netlify (netlify.toml) ────────────────────────────────
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

// Hash 模式的 SEO 问题及 workaround

// 问题：搜索引擎通常忽略 # 后面的内容
// URL: https://example.com/#/products/123
// 爬虫实际抓取: https://example.com/ （只看到首页）

// Workaround 1：使用 sitemap.xml 提供可抓取的 URL
// sitemap.xml
// <?xml version="1.0" encoding="UTF-8"?>
// <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
//   <url><loc>https://example.com/#/products/123</loc></url>
//   <url><loc>https://example.com/#/about</loc></url>
// </urlset>

// Workaround 2：服务端渲染（SSR）+ History 模式
// 使用 Nuxt.js / Vite SSR 在服务端生成完整 HTML

// Workaround 3：预渲染关键页面
// 使用 prerender-spa-plugin 生成静态 HTML

// Workaround 4：使用 _escaped_fragment_ 协议（已废弃）
// Google 曾支持，但已于 2015 年弃用

// 结论：生产环境强烈建议使用 History 模式

// ─── 场景 1：单元测试 ─────────────────────────────────────
import { createRouter, createMemoryHistory } from 'vue-router'
import { mount } from '@vue/test-utils'

describe('UserView', () => {
  it('renders user details from route params', async () => {
    const router = createRouter({
      history: createMemoryHistory('/users/42'),
      routes: [
        { path: '/users/:id', name: 'User', component: UserView }
      ]
    })

    // 初始导航
    await router.push('/users/42')

    const wrapper = mount(UserView, {
      global: { plugins: [router] }
    })

    expect(wrapper.text()).toContain('User 42')
  })
})

// ─── 场景 2：SSR ──────────────────────────────────────────
// server.js
import { createSSRApp } from 'vue'
import { createRouter, createMemoryHistory } from 'vue-router'
import { renderToString } from 'vue/server-renderer'

export async function render(url: string) {
  const app = createSSRApp(App)

  const router = createRouter({
    history: createMemoryHistory(url),  // 不依赖浏览器 API
    routes
  })

  app.use(router)

  // 导航到请求的 URL
  await router.push(url)
  await router.isReady()

  const html = await renderToString(app)
  return { html }
}

// ─── 场景 3：Electron ─────────────────────────────────────
// Electron 中 file:// 协议下 History 模式不可用
// Memory 模式是最佳选择
const router = createRouter({
  history: createMemoryHistory(),
  routes
})

// 手动同步 Electron 的导航
ipcRenderer.on('navigate', (_, path) => {
  router.push(path)
})

// ─── 策略 1：软 404（返回 200 + 404 页面内容）─────────────
// 适用：纯前端 SPA，无法控制服务端
const routes = [
  // ... 其他路由
  {
    path: '/:pathMatch(.*)*',
    name: 'NotFound',
    component: () => import('@/views/NotFound.vue'),
    meta: { title: '页面未找到' }
  }
]

// ─── 策略 2：硬 404（服务端返回 404 状态码）─────────────────
// 适用：SSR / Nuxt，可以控制服务端响应
// Nuxt 示例
export default defineNuxtRouteMiddleware((to) => {
  const validRoutes = ['/', '/about', '/products']
  if (!validRoutes.includes(to.path)) {
    throw createError({
      statusCode: 404,
      statusMessage: 'Page Not Found',
      fatal: true
    })
  }
})

// ─── 策略 3：分层 404（按模块返回不同 404 页面）─────────────
const routes = [
  {
    path: '/products',
    component: ProductLayout,
    children: [
      { path: ':id', component: ProductDetail },
      {
        path: ':pathMatch(.*)*',
        component: ProductNotFound  // 产品模块专用 404
      }
    ]
  },
  {
    path: '/:pathMatch(.*)*',
    component: GlobalNotFound  // 全局 404
  }
]

// ─── 策略 4：智能重定向（记录来源并建议正确路径）────────────
router.beforeEach((to, from) => {
  if (to.matched.length === 0) {
    // 尝试模糊匹配
    const suggestion = findClosestRoute(to.path, router.getRoutes())
    if (suggestion) {
      return {
        path: '/404',
        query: {
          from: to.fullPath,
          suggestion: suggestion.path
        }
      }
    }
  }
})

// ─── 完整子路径部署方案 ───────────────────────────────────

// 1. Vite 配置
// vite.config.ts
export default defineConfig(({ mode }) => ({
  base: mode === 'production' ? '/my-app/' : '/',
}))

// 2. Router 配置
// router/index.ts
const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
  // 重要：敏感度和严格模式配置
  sensitive: false,  // /Users 和 /users 视为相同
  strict: false,     // /users 和 /users/ 视为相同
})

// 3. 静态资源引用
// 使用 import.meta.env.BASE_URL 而非硬编码路径
const logoUrl = `${import.meta.env.BASE_URL}images/logo.png`

// 4. Nginx 子路径部署
// location /my-app/ {
//     alias /var/www/my-app/dist/;
//     try_files $uri $uri/ /my-app/index.html;
// }

// 5. 环境变量方案（支持多环境部署）
// .env.production
// VITE_BASE_URL=/my-app/

// .env.staging
// VITE_BASE_URL=/my-app-staging/

// 6. 动态 BASE_URL（运行时注入）
// public/config.js
// window.__APP_CONFIG__ = { BASE_URL: '/my-app/' }

// main.ts
const baseUrl = window.__APP_CONFIG__?.BASE_URL || '/'
const router = createRouter({
  history: createWebHistory(baseUrl),
  routes
})

// ─── 微前端路由隔离方案 ───────────────────────────────────

// 方案 1：qiankun / single-spa 风格 —— 每个子应用独立路由
// 主应用
const mainRouter = createRouter({
  history: createWebHistory(),
  routes: [
    {
      path: '/app1/:pathMatch(.*)*',
      name: 'App1',
      // 不渲染组件，由 qiankun 接管
    },
    {
      path: '/app2/:pathMatch(.*)*',
      name: 'App2',
    }
  ]
})

// 子应用 router
const subAppRouter = createRouter({
  history: createWebHistory(
    window.__POWERED_BY_QIANKUN__ ? '/app1/' : '/'
  ),
  routes: [
    { path: '/', component: Home },
    { path: '/users', component: Users },
  ]
})

// 方案 2：Module Federation —— 共享路由注册
// 主应用暴露路由注册接口
interface MicroAppRoute {
  prefix: string
  routes: RouteRecordRaw[]
}

const microApps = new Map<string, MicroAppRoute>()

export function registerMicroApp(name: string, config: MicroAppRoute) {
  microApps.set(name, config)

  // 动态添加路由
  for (const route of config.routes) {
    router.addRoute({
      ...route,
      path: config.prefix + route.path
    })
  }
}

export function unregisterMicroApp(name: string) {
  const config = microApps.get(name)
  if (config) {
    // 移除路由
    for (const route of config.routes) {
      router.removeRoute(route.name as string)
    }
    microApps.delete(name)
  }
}

// 方案 3：iframe 隔离（最彻底的隔离）
// 主应用通过 postMessage 通信
const iframeRouter = {
  navigate(path: string) {
    const iframe = document.getElementById('micro-app') as HTMLIFrameElement
    iframe?.contentWindow?.postMessage(
      { type: 'NAVIGATE', path },
      '*'
    )
  }
}

// 子应用监听
window.addEventListener('message', (event) => {
  if (event.data.type === 'NAVIGATE') {
    router.push(event.data.path)
  }
})

// ─── 微前端路由冲突避免策略 ───────────────────────────────
// 1. 命名空间前缀：所有路由 name 加应用前缀
const APP_PREFIX = 'app1'
const routes = [
  { path: '/users', name: `${APP_PREFIX}-Users`, component: Users }
]

// 2. 路由白名单：主应用维护所有子应用路由前缀
const MICRO_APP_PREFIXES = ['/app1', '/app2', '/app3']

// 3. 导航守卫：防止子应用导航到其他子应用的路由
router.beforeEach((to) => {
  const currentAppPrefix = getCurrentAppPrefix()
  if (to.path.startsWith('/') && !to.path.startsWith(currentAppPrefix)) {
    // 跨应用导航，需要通知主应用
    window.dispatchEvent(new CustomEvent('cross-app-navigate', {
      detail: { path: to.path }
    }))
    return false
  }
})