routerKey - 路由实例注入键

routerKey 是一个Symbol类型的常量，用于在 Vue 的依赖注入系统中唯一标识路由实例。它是 Vue Router 内部实现依赖注入机制的关键组成部分。🔑

📋 变量定义

const routerKey: InjectionKey<Router> = Symbol()

🎯 功能说明

这个常量就像是路由系统的"身份证"，负责：

1. 唯一标识 - 在依赖注入系统中唯一标识路由实例
2. 类型安全 - 提供 TypeScript 类型安全的依赖注入
3. 内部使用 - 主要供 Vue Router 内部和高级定制场景使用

🔧 技术细节

注入键的作用

// InjectionKey 的定义
interface InjectionKey<T> extends Symbol {}

// routerKey 的实际类型
const routerKey: InjectionKey<Router> = Symbol('router')

在 Vue 依赖注入中的使用

// 提供路由实例
provide(routerKey, router)

// 获取路由实例
const router = inject(routerKey)

💡 实际应用示例

标准用法（通常不需要直接使用）

<script setup>
import { inject } from 'vue'
import { routerKey } from 'vue-router'

// 获取路由实例（标准方式）
const router = inject(routerKey)

// 等同于使用 useRouter()
// const router = useRouter()
</script>

自定义路由提供（高级场景）

<script setup>
import { provide } from 'vue'
import { routerKey, createRouter } from 'vue-router'

// 创建自定义路由实例
const customRouter = createRouter({
  history: createWebHistory(),
  routes: [...]
})

// 提供自定义路由实例
provide(routerKey, customRouter)
</script>

测试环境中的使用

// 在单元测试中模拟路由
import { routerKey } from 'vue-router'

describe('组件测试', () => {
  it('应该能访问路由', () => {
    const mockRouter = {
      push: vi.fn(),
      currentRoute: { value: { path: '/test' } }
    }
    
    const wrapper = mount(MyComponent, {
      global: {
        provide: {
          [routerKey]: mockRouter
        }
      }
    })
    
    expect(wrapper.vm.$router).toBe(mockRouter)
  })
})

🎯 使用场景

库开发者的高级定制

// 创建具有特殊行为的路由包装器
function createEnhancedRouter(options) {
  const baseRouter = createRouter(options)
  
  // 添加额外功能
  const enhancedRouter = {
    ...baseRouter,
    smartPush(to) {
      // 自定义导航逻辑
      return baseRouter.push(to)
    }
  }
  
  return enhancedRouter
}

// 在应用中使用增强版路由
const router = createEnhancedRouter({...})
app.provide(routerKey, router)

多路由实例场景（罕见）

// 在同一个应用中管理多个独立的路由系统
const mainRouterKey: InjectionKey<Router> = Symbol('mainRouter')
const adminRouterKey: InjectionKey<Router> = Symbol('adminRouter')

// 提供不同的路由实例
provide(mainRouterKey, mainRouter)
provide(adminRouterKey, adminRouter)

// 在不同区域使用不同的路由
const mainRouter = inject(mainRouterKey)
const adminRouter = inject(adminRouterKey)

🔧 内部实现原理

Vue Router 的依赖注入机制

// 在路由插件安装时提供路由实例
export function install(app: App, router: Router) {
  app.provide(routerKey, router)
  
  // 其他安装逻辑...
}

// 在 useRouter 中获取路由实例
export function useRouter(): Router {
  return inject(routerKey)!
}

类型安全的保证

// 通过 InjectionKey 确保类型安全
const router = inject(routerKey) // 类型为 Router | undefined

// 使用非空断言（因为 Vue Router 保证路由存在）
const router = inject(routerKey)!

🚨 注意事项

通常不需要直接使用

// ❌ 不推荐（过于底层）
import { routerKey } from 'vue-router'
const router = inject(routerKey)

// ✅ 推荐（更简洁明了）
import { useRouter } from 'vue-router'
const router = useRouter()

错误的使用方式

// ❌ 错误：尝试修改 routerKey
routerKey = Symbol('newKey') // 编译错误

// ❌ 错误：错误类型的注入
provide(routerKey, 'not-a-router') // 类型错误

🔗 相关变量

• routeLocationKey - 路由位置注入键
• routerViewLocationKey - 路由视图位置键

💡 专业建议：对于绝大多数应用场景，直接使用 useRouter() 和 useRoute() 即可，无需关心底层的依赖注入机制。routerKey 主要供库开发者和需要深度定制的场景使用。