前言

在 uni-app 开发中，路由管理一直是一个痛点。原生 API虽然能满足基本导航需求，但缺少路由守卫、命名路由、元信息等 vue‑router 开发者习以为常的能力。每次需要登录拦截、页面标题设置、权限控制时都不得不在各个页面中重复编写逻辑。

@meng-xi/uni-router 的目标很简单：

• 让 uni‑app 也能拥有 vue‑router 级别的路由管理体验；其实，
• 不破坏 uni‑app 原有的页面模型。

使用者痛点与方法

• 缺乏全局导航守卫：无法统一处理登录拦截、权限校验。
• 方法硬编码：直接使用字符串方法，维护困难。
• 元信息不足：无法在路由配置中携带标题或权限等数据。
• Navigations 失败时没有统一捕获机制。
• No type checking for route names or paths.

主要特性

vue-router 风格 API

If you’ve used vue‑router,learning curve is zero:

const router = useRouter
// 方法导航
await router.push
// 带查询参数
await router.push
// 命名路由导航
await router.push
// 替换当前页面
await router.replace
// 返回上一页
await router.back
// 返回两级
await router.back

路由守卫

The most powerful feature of uni‑router is its guard system:

// 全局前置守卫 - 登录拦截
router.beforeEach => {
if ) {
next
} else {
next
}
})
// 全局解析守卫 - 所有前置守卫通过后执行
router.beforeResolve => { next })
// 全局后置钩子 - 导航完成后执行。无法改变导航结果
router.afterEach => {
console.log
})
// 路由独享守卫 - 在路由配置中定义
const routes =

The execution order is:


#beforeEach → #beforeEnter → #beforeResolve → Navigation API → #afterEach 

#next / #next / #next

Guard actions:


#next – allow navigation;

#next – redirect;

#next – abort.




命名路由

No more hard‑coded paths;navigate by name instead:
// 路由配置
const routes =
// 使用名称导航
await router.push
await router.push

The 

路由元信息

Add custom data in 'meta',n read it in guards for permissions or title setting:

const routes =
// Guard reading meta:
router.beforeEach=>{
if ){
next
}else{
if{
uni.setNavigationBarTitle
}
next
}

TypeScript 类型提示 & 自动补全 

If you enable dts:true 。route names and paths receive auto‑completion and type checking:

// Route name auto-complete:
router.push // ✅
// Invalid route:
router.push // ❌
/* Path auto-complete */
router.push // ✅
// Invalid path:
router.push // ❌

错误处理程序 

A comprehensive error handling scheme allows global catching and local try/catch:

// Global error handler:
router.onError=>{
switch{
case 'NIGATION_DUPLICATED':
console.warn;break，case 'NIGATION_ABORTED':
console.warn;break，case 'NIGATION_API_ERROR':
console.error;break，}
})
// Local error handling:
try{
await router.push
}catch{
if{
// Guard blocked navigation...
}
}


Error Code |说明 |示例场景


NIGATION_ABORTED | Guard 中止导航 | 未授权访问受限页面

NIGATION_CANCELLED | 重定向超限导致取消 |

NIGATION_DUPLICATED | 重复导航到同一方法 |

NIGATION_API_ERROR | Uni 导航 API 调用失败 |

NIGATION_NOT_FOUND | 未找到匹配的路由 |

NIGATION_API_ERROR |

**Note**：Table rendered for illustration only.
**More Error Codes**:


`SETUP_ERROR` – Router 初始化或使用方式错误。

`NIGATION_ABORTED` – 守卫中止了导航。

`NIGATION_CANCELLED` – 重定向循环导致取消。


组合式 API 接口 

Simplify access within Vue setup functions: