vue-router-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vuejs/router

vue-router

vuejs/router

vue-router

Version: 5.0.2 (Feb 2026) Deps: @babel/generator@^7.28.6, @vue-macros/common@^3.1.1, @vue/devtools-api@^8.0.0, ast-walker-scope@^0.8.3, chokidar@^5.0.0, json5@^2.2.3, local-pkg@^1.1.2, magic-string@^0.30.21, mlly@^1.8.0, muggle-string@^0.4.1, pathe@^2.0.3, picomatch@^4.0.3, scule@^1.3.0, tinyglobby@^0.2.15, unplugin@^3.0.0, unplugin-utils@^0.3.1, yaml@^2.8.2 Tags: next: 4.0.13 (Feb 2022), legacy: 3.6.5 (Sep 2022), edge: 4.4.0-alpha.3 (Jun 2024), beta: 5.0.0-beta.2 (Jan 2026), latest: 5.0.2 (Feb 2026)

References: Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs

版本： 5.0.2（2026年2月） 依赖： @babel/generator@^7.28.6, @vue-macros/common@^3.1.1, @vue/devtools-api@^8.0.0, ast-walker-scope@^0.8.3, chokidar@^5.0.0, json5@^2.2.3, local-pkg@^1.1.2, magic-string@^0.30.21, mlly@^1.8.0, muggle-string@^0.4.1, pathe@^2.0.3, picomatch@^4.0.3, scule@^1.3.0, tinyglobby@^0.2.15, unplugin@^3.0.0, unplugin-utils@^0.3.1, yaml@^2.8.2 标签： next: 4.0.13（2022年2月）, legacy: 3.6.5（2022年9月）, edge: 4.4.0-alpha.3（2024年6月）, beta: 5.0.0-beta.2（2026年1月）, latest: 5.0.2（2026年2月）

参考文档： 官方文档 — API参考、使用指南 • GitHub Issues — 问题反馈、解决方案、边界情况 • GitHub Discussions — 问答、模式、实践方案 • 版本发布记录 — 更新日志、破坏性变更、新API

API Changes

API变更

This section documents version-specific API changes — prioritize recent major/minor releases.

NEW:
```
vue-router/vite
```
— v5 ships the Vite plugin (formerly
```
unplugin-vue-router/vite
```
) directly in the core package; import from
```
vue-router/vite
```
instead source
NEW:
```
vue-router/auto-routes
```
— v5 export that provides the auto-generated file-based route list; previously required
```
unplugin-vue-router
```
as a separate package source
NEW:
```
vue-router/unplugin
```
— v5 export for Webpack/Rollup/esbuild plugins and utilities (
```
VueRouterAutoImports
```
,
```
EditableTreeNode
```
,
```
createRoutesContext
```
, etc.); previously imported from
```
unplugin-vue-router
```
source

NEW:

DataLoaderPlugin

defineBasicLoader

(experimental) — v5 adds data loaders directly to

vue-router/experimental

; previously in

unplugin-vue-router/data-loaders

. Install

DataLoaderPlugin

before the router with

app.use(DataLoaderPlugin, { router })

source

NEW:

defineColadaLoader

(experimental) — Pinia Colada-backed loader available at

vue-router/experimental/pinia-colada

; previously

unplugin-vue-router/data-loaders/pinia-colada

source

NEW:
```
NavigationResult
```
(experimental) — class from
```
vue-router/experimental
```
returned inside a loader to redirect during navigation (e.g.
```
return new NavigationResult('/login')
```
); previously did not exist in vue-router source

NEW: Volar plugins moved to

vue-router/volar/sfc-typed-router

and

vue-router/volar/sfc-route-blocks

— previously

unplugin-vue-router/volar/sfc-typed-router

and

unplugin-vue-router/volar/sfc-route-blocks

source

NEW:

TypesConfig

module augmentation — v4.4+ interface used to register

RouteNamedMap

for typed routes; augment with

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

source

BREAKING: IIFE build no longer bundles
```
@vue/devtools-api
```
— v5 upgraded devtools-api to v8 which has no IIFE build; affects CDN/script-tag setups that relied on the bundled devtools source
NEW: Query params optional by default (experimental) — v5 file-based routing makes query params optional in typed routes by default source

Also changed:

unplugin-vue-router

types/utilities moved to

vue-router/unplugin

(renamed) ·

route-map.d.ts

replaces

typed-router.d.ts

(renamed) ·

meta.loaders

array on route records for manually connecting data loaders (NEW, experimental) ·

router.currentRoute

Ref<RouteLocationNormalizedLoaded>

— access via

.value

(v4 BREAKING) ·

router.onReady()

removed — use

router.isReady()

returning a Promise (v4 BREAKING) ·

scrollBehavior

renamed to

left

top

(v4 BREAKING)

本节记录各版本的API变更信息 — 优先关注近期的大版本/小版本更新。

新增：
```
vue-router/vite
```
— v5版本将Vite插件（原
```
unplugin-vue-router/vite
```
）直接集成到核心包中；请改为从
```
vue-router/vite
```
导入来源
新增：
```
vue-router/auto-routes
```
— v5新增的导出项，提供基于文件自动生成的路由列表；此前需要单独安装
```
unplugin-vue-router
```
包来源
新增：
```
vue-router/unplugin
```
— v5为Webpack/Rollup/esbuild提供的插件及工具函数导出项（包含
```
VueRouterAutoImports
```
、
```
EditableTreeNode
```
、
```
createRoutesContext
```
等）；此前需从
```
unplugin-vue-router
```
导入来源

新增：

DataLoaderPlugin

defineBasicLoader

（实验性） — v5在

vue-router/experimental

中直接添加了数据加载器；此前该功能位于

unplugin-vue-router/data-loaders

。请在注册路由前使用

app.use(DataLoaderPlugin, { router })

安装

DataLoaderPlugin

来源

新增：

defineColadaLoader

（实验性） — 基于Pinia Colada的加载器，可从

vue-router/experimental/pinia-colada

获取；此前位于

unplugin-vue-router/data-loaders/pinia-colada

来源

新增：
```
NavigationResult
```
（实验性） — 从
```
vue-router/experimental
```
导出的类，可在加载器中返回以在导航过程中实现重定向（例如
```
return new NavigationResult('/login')
```
）；此前vue-router中无此功能来源

新增：Volar插件迁移至

vue-router/volar/sfc-typed-router

和

vue-router/volar/sfc-route-blocks

— 此前位于

unplugin-vue-router/volar/sfc-typed-router

和

unplugin-vue-router/volar/sfc-route-blocks

来源

新增：
```
TypesConfig
```
模块扩展 — v4.4+版本新增的接口，用于注册
```
RouteNamedMap
```
以实现类型化路由；可通过
```
declare module 'vue-router' { interface TypesConfig { RouteNamedMap: RouteNamedMap } }
```
进行扩展来源
破坏性变更：IIFE构建版本不再捆绑
```
@vue/devtools-api
```
— v5版本将devtools-api升级至v8，该版本无IIFE构建；这会影响依赖捆绑版devtools的CDN/script标签引入方式来源
新增：查询参数默认可选（实验性） — v5版本的基于文件路由功能默认将类型化路由中的查询参数设为可选来源

其他变更：

unplugin-vue-router

的类型定义/工具函数迁移至

vue-router/unplugin

（已重命名） ·

route-map.d.ts

替代

typed-router.d.ts

（已重命名） · 路由记录新增

meta.loaders

数组，用于手动关联数据加载器（新增，实验性） ·

router.currentRoute

类型为

Ref<RouteLocationNormalizedLoaded>

— 需通过

.value

访问（v4版本破坏性变更） ·

router.onReady()

已移除 — 请使用返回Promise的

router.isReady()

（v4版本破坏性变更） ·

scrollBehavior

中的

参数重命名为

left

top

（v4版本破坏性变更）

Best Practices

最佳实践

Use
```
route.meta
```
directly in guards instead of iterating
```
to.matched
```
— Vue Router merges all ancestor
```
meta
```
fields non-recursively, so
```
to.meta.requiresAuth
```
already reflects inherited values from parent routes source
Extend the
```
RouteMeta
```
interface via module augmentation to type all
```
meta
```
fields — this enforces that every route declares required fields at compile time rather than relying on runtime checks source
Use
```
router.beforeResolve
```
(not
```
beforeEach
```
) for operations that must run after async components are resolved — it fires after all in-component guards and async route components are ready, making it the correct place for camera permission checks or final data validation source
Use
```
inject()
```
inside navigation guards (global or per-route) to access Pinia stores and provided values — this is supported since Vue 3.3 and avoids importing stores outside of
```
setup
```
context source
Avoid the
```
next
```
callback in guards — return values (
```
false
```
, a route location, or nothing) instead;
```
next
```
is error-prone because it must be called exactly once per code path and is considered a legacy API source
```
await router.push()
```
and check the resolved value to detect navigation failures — the promise resolves to a
```
NavigationFailure
```
when blocked, or
```
undefined
```
on success; use
```
isNavigationFailure(result, NavigationFailureType.aborted)
```
to distinguish the specific failure type source
Set
```
props: true
```
(or a function) on route records to decouple components from
```
useRoute()
```
— components receiving params as props are reusable and testable without a router instance; use the function form (
```
props: route => ({ query: route.query.q })
```
) to map query params or cast types source
Watch specific
```
route
```
properties rather than the whole
```
route
```
object —
```
useRoute()
```
returns a reactive object, but watching it entirely triggers on any change (hash, query, params); narrow the watcher to
```
() => route.params.id
```
to avoid unnecessary fetches source
(experimental) Use
```
defineBasicLoader
```
/
```
defineColadaLoader
```
exported from page components for navigation-aware data fetching — loaders exported from lazy-loaded route components are automatically connected to the navigation lifecycle, block the transition until resolved, and expose
```
isLoading
```
/
```
error
```
reactively; set
```
lazy: true
```
for non-critical data that should not block navigation source

在导航守卫中直接使用
```
route.meta
```
，而非遍历
```
to.matched
```
— Vue Router会以非递归方式合并所有父路由的
```
meta
```
字段，因此
```
to.meta.requiresAuth
```
已包含从父路由继承的值来源
通过模块扩展
```
RouteMeta
```
接口，为所有
```
meta
```
字段添加类型定义 — 这能确保在编译阶段强制每个路由声明必填字段，而非依赖运行时检查来源
使用
```
router.beforeResolve
```
（而非
```
beforeEach
```
）执行需在异步组件解析后运行的操作 — 该钩子会在所有组件内守卫和异步路由组件准备完成后触发，是进行相机权限检查或最终数据验证的合适时机来源
在导航守卫（全局或路由级）中使用
```
inject()
```
访问Pinia状态管理仓库和注入的值 — Vue 3.3及以上版本支持该方式，可避免在
```
setup
```
上下文之外导入仓库来源
避免在守卫中使用
```
next
```
回调函数 — 改用返回值（
```
false
```
、路由地址或无返回值）；
```
next
```
容易出错，因为它在每个代码路径中必须被调用恰好一次，且属于遗留API 来源
使用
```
await router.push()
```
并检查解析结果以检测导航失败 — 当导航被阻止时，Promise会解析为
```
NavigationFailure
```
对象，成功时则返回
```
undefined
```
；可使用
```
isNavigationFailure(result, NavigationFailureType.aborted)
```
区分具体的失败类型来源
在路由记录中设置
```
props: true
```
（或函数形式），使组件与
```
useRoute()
```
解耦 — 通过props接收参数的组件无需路由实例即可复用和测试；使用函数形式（
```
props: route => ({ query: route.query.q })
```
）可映射查询参数或进行类型转换来源
监听
```
route
```
对象的特定属性，而非整个
```
route
```
对象 —
```
useRoute()
```
返回一个响应式对象，但监听整个对象会在任何变化（哈希、查询参数、路径参数）时触发回调；将监听器限定为
```
() => route.params.id
```
可避免不必要的数据请求来源
（实验性）在页面组件中导出
```
defineBasicLoader
```
/
```
defineColadaLoader
```
，实现导航感知的数据获取 — 从懒加载路由组件导出的加载器会自动关联导航生命周期，在解析完成前阻止页面过渡，并以响应式方式暴露
```
isLoading
```
/
```
error
```
状态；对于非关键数据，可设置
```
lazy: true
```
使其不阻塞导航来源

vue-router-skilld

Original

Translation

vuejs/router
`vue-router`

vuejs/router
`vue-router`

API Changes

API变更

Best Practices

最佳实践