vue-router-skilld

vuejs/router [email protected]

准备的源代码：[email protected]，ESM 包（"type": "module"，package.json:2,20）。 Peer 依赖：vue ^3.5.34 || ^4.0.0；可选依赖：vite ^7.3.0 || ^8.0.0、pinia ^3.0.4 || ^4.0.2、@pinia/colada >=0.21.2（package.json:173-193）。 文档：https://router.vuejs.org

导入映射

导入	用途
vue-router	createRouter、createWebHistory、createWebHashHistory、createMemoryHistory、RouterLink、RouterView、useRouter、useRoute、useLink、onBeforeRouteLeave、onBeforeRouteUpdate、isNavigationFailure、NavigationFailureType、START_LOCATION、parseQuery、stringifyQuery（dist/vue-router.d.ts:6）
vue-router/vite	Vite 插件、基于文件的路由（package.json:104）
vue-router/unplugin/{vite,webpack,rollup,esbuild,rolldown}	适用于其他打包工具的同一插件（dist/unplugin/）
vue-router/unplugin	VueRouterAutoImports、createRoutesContext、EditableTreeNode、插件 Options（dist/unplugin/index.d.mts:62）
vue-router/auto-routes	生成的 routes 数组 + handleHotUpdate(router)（vue-router-auto-routes.d.mts:6,28）
vue-router/auto-resolver	为 experimental_createRouter 生成的 resolver + handleHotUpdate（vue-router-auto-resolver.d.mts:15,21）
vue-router/experimental	数据加载器、reroute、miss、definePage、defineParamParser、PARAM_PARSER_INT/PARAM_PARSER_BOOL、experimental_createRouter、useIsDataLoading（dist/experimental/index.d.ts:7）
vue-router/experimental/pinia-colada	defineColadaLoader（package.json:77）
vue-router/volar/sfc-route-blocks、vue-router/volar/sfc-typed-router	Volar 插件：<route> 块、按文件提供类型的 useRoute()（package.json:115-121）

请避免：

• vue-router/auto——已弃用，即将移除（vue-router-auto.d.ts:1）。
• 在 CJS 构建中使用 vue-router/experimental——自 v5.1.0 起仅支持 ESM（https://github.com/vuejs/router/releases/tag/v5.1.0）。

快速入门（经典路由）

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

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: () => import('./pages/Home.vue') },
    { path: '/users/:id', component: () => import('./pages/User.vue'), props: true },
  ],
})
app.use(router)

在组件中：从 vue-router 导入 useRoute() / useRouter()；通过 app.use(router) 全局注册 <RouterLink to="..."> 和 <RouterView>。

快速入门（基于文件的路由）

// vite.config.ts
import VueRouter from 'vue-router/vite'
import Vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [VueRouter(), Vue()], // Vue plugin MUST come after VueRouter
})

import { createRouter, createWebHistory } from 'vue-router'
import { routes, handleHotUpdate } from 'vue-router/auto-routes'

const router = createRouter({ history: createWebHistory(), routes })
if (import.meta.hot) handleHotUpdate(router)

默认情况下，页面位于 src/pages。启动一次开发服务器以生成 typed-router.d.ts，然后将其添加到 tsconfig.json 的 include 中，并设置 "moduleResolution": "Bundler"。详情、命名约定和插件选项见：references/file-based-routing.md。

核心规则

• 从导航守卫中返回值，切勿调用 next()。next 已弃用（自 v5.0.3 起会发出运行时警告），并将被移除（dist/index-D7ja2BKs.d.ts:362-393, https://github.com/vuejs/router/releases/tag/v5.0.3）。

  router.beforeEach(to => {
    if (to.meta.requiresAuth && !isAuthenticated) return { name: 'login' }
    // return nothing, true, false, or a route location
  })
  

• 在数据加载器中，使用 reroute(to) 重定向；new NavigationResult(to) 已弃用，并会记录警告（dist/experimental/index.js:1106-1111）。
• router.currentRoute 是 ShallowRef<RouteLocationNormalizedLoaded>——读取时使用 router.currentRoute.value（dist/index-D7ja2BKs.d.ts:1433）。
• router.onReady() 不存在（已在 v4 中移除）；请使用 await router.isReady()。
• scrollBehavior 返回 { top, left }（v4 将 x/y 重命名为 left/top）。
• 检测导航失败：const failure = await router.push(...)；使用 isNavigationFailure(failure, NavigationFailureType.aborted) 进行检查。
• route.meta 会以非递归方式合并所有匹配记录中的内容；直接读取 to.meta.requiresAuth，不要遍历 to.matched。通过 RouteMeta 模块扩展为 meta 添加类型。
• 对于需要异步组件解析完成后再执行的操作，请使用 router.beforeResolve（而非 beforeEach）。
• 在守卫中使用 inject() 访问 Pinia 存储（Vue 3.3 起支持）。
• 使用路由 props: true 或 props: route => ({ ... }) 解耦组件与路由；以此方式传递查询值，让组件便于测试。
• 监听范围较窄的数据源（() => route.params.id），不要监听整个 route 对象。

完整的核心 API 说明：references/core-api.md。

类型化路由

使用基于文件的路由插件即可启用（类型会自动生成），也可以手动扩展：

declare module 'vue-router' {
  interface TypesConfig {
    RouteNamedMap: RouteNamedMap
  }
}

支持类型化的 push('/users/:id', { params: { id: 42 } })、类型化的 useRoute()，并可通过 Volar 插件 vue-router/volar/sfc-typed-router 为每个文件单独添加类型。参数解析器（int、bool，以及 src/params/ 中的自定义解析器）可提供带类型且经过验证的参数；definePage({ params: { query: { page: { parser: 'int', default: 1 } } }) 用于声明查询参数。详情请参阅：references/typed-routes.md。

数据加载器（实验性）

// src/pages/users/[id].vue
import { defineBasicLoader } from 'vue-router/experimental'
import { reroute } from 'vue-router/experimental'

export const useUserData = defineBasicLoader(async (to) => {
  if (!to.params.id) reroute('/') // reroute throws: stops the loader immediately
  return fetchUser(to.params.id)
})

请在路由器之前安装 DataLoaderPlugin：app.use(DataLoaderPlugin, { router })。非阻塞加载器：defineBasicLoader(loader, { lazy: true })；此时错误会进入 error，而非 router.onError。详情请参阅：references/data-loaders.md。

版本说明（5.0.x → 5.3.1）

• v5.0.7：RouteNamedMap 通过生成的 typed-router.d.ts 接入（https://github.com/vuejs/router/releases/tag/v5.0.7）；参数解析器文件夹新增了 include/exclude。
• v5.1.0：新增类型化的 definePage params.path、defineParamParserRaw、严格默认类型，以及 TypesConfig 全局 Router 覆盖；实验性导出仅支持 ESM（https://github.com/vuejs/router/releases/tag/v5.1.0）。
• v5.2.0：新增常见错误的诊断；支持 pinia 4（https://github.com/vuejs/router/releases/tag/v5.2.0）。
• v5.3.0：当 history.scrollRestoration 指示跳过时，不执行滚动；重复的 definePage() 会报告错误而非导致崩溃；EditableTreeNode.name 接受 false 以取消设置（https://github.com/vuejs/router/releases/tag/v5.3.0）。
• v5.3.1：修复了参数为非字符串时的 isActive（https://github.com/vuejs/router/releases/tag/v5.3.1）。

从 v3/v4 或 unplugin-vue-router 迁移：references/migration.md。

参考资料

• core-api.md — 路由器创建、历史记录、守卫、失败、滚动、RouterLink/RouterView。
• file-based-routing.md — 插件设置、文件命名、definePage、<route> 块、extendRoute、选项。
• typed-routes.md — TypesConfig、生成的类型、参数解析器、experimental_createRouter。
• data-loaders.md — defineBasicLoader、defineColadaLoader、reroute、惰性加载器、SSR 说明。
• migration.md — v3→v4 和 v4→v5 的变更、v5 系列中的弃用项。