从零设计一个 uni-app 路由框架：架构设计与实现细节

深入剖析 @meng-xi/uni-router 的内部架构，探讨在 uni-app 静态页面模型下实现 vue-router 风格路由管理的设计决策与工程实践

为什么需要又一个路由库？

uni-app 的路由本质上是静态页面模型——所有页面在 pages.json中声明，运行时通过 uni.navigateTo/ uni.redirectTo/ uni.navigateBack三个命令式 API 进行页面切换。这个模型简单直接，但随着业务复杂度增长，几个核心问题反复出现：

没有拦截点。登录校验、权限检查、页面标题设置……这些横切关注点不得不散落在每个页面的 onShow或 onLoad中。十个需要登录的页面，就写十遍相同的判断逻辑。

没有路由抽象。路径字符串硬编码在各处，页面路径变更时需要全局搜索替换。没有命名路由，没有元信息，没有路由解析。

没有错误体系。uni.navigateTo的 fail回调只告诉你"失败了"，但无法区分是页面不存在、栈溢出还是其他原因。更无法在全局统一处理导航错误。

@meng-xi/uni-router的设计目标不是替代 pages.json，而是在其之上构建一层可控的导航管理层，提供守卫链、路由解析、状态同步和错误处理能力。

架构总览

整个框架由六个核心模块组成，各司其职：

┌─────────────────────────────────────────────┐ │ UniRouter │ │ (门面 / 编排层) │ │ push / replace / back / install / syncRoute │ ├──────────┬──────────┬──────────┬─────────────┤ │ Matcher │ Guard │ State │ Interceptor │ │ 路由匹配 │ 守卫管理 │ 状态管理 │ API 拦截 │ ├──────────┴──────────┴──────────┴─────────────┤ │ Navigation │ │ uni API 适配层 │ ├──────────────────────────────────────────────┤ │ Errors │ │ 错误体系 (RouterError / │ │ NavigationFailure) │ └──────────────────────────────────────────────┘

UniRouter是门面类，对外暴露 push/ replace/ back等方法，对内编排 Matcher、Guard、State、Navigation 四个模块的协作流程。

Matcher负责路由解析——将 string、{ path, query }、{ name, query }三种形式的路由位置统一解析为 RouteLocation对象。

Guard负责守卫链的注册与执行——管理 beforeEach、beforeResolve、afterEach三类全局守卫和 beforeEnter路由独享守卫。

State负责路由状态管理——维护 currentRoute，处理就绪状态和路由变化监听。

Interceptor负责拦截 uni 原生导航 API——将外部直接调用重定向到路由器，确保守卫始终生效。

Navigation是 uni API 适配层——封装 uni.navigateTo等为 Promise，处理 TabBar 页面自动切换。

Errors定义了完整的错误体系——RouterError基类和 NavigationFailure子类，携带错误码、来源/目标路由和原始错误。

导航流程：一次 push 的完整旅程

当调用 router.push({ name: 'about', query: { id: '1' } })时，框架内部经历了以下步骤：

1. 并发导航排队

private async performNavigation(location: RouteLocationRaw, mode: 'push' | 'replace') { // 等待前一次导航完成 if (this.pendingNavigation) { await this.pendingNavigation.catch(() =＞ {}) } // ... const navigationPromise = this.executeNavigation(to, from, mode, 0) this.pendingNavigation = navigationPromise // ... }

uni-app 的页面导航是异步的，如果两次 push同时执行，可能导致页面栈混乱。框架通过 pendingNavigation实现导航排队——新的导航必须等待前一次完成后再开始。catch(() =＞ {})确保即使前一次导航失败，也不会阻塞后续导航。

2. 重复导航检测

if (mode === 'push' ＆＆ this.isSameRouteLocation(to, from)) { const failure = new NavigationFailure(to, from, RouterErrorCode.NAVIGATION_DUPLICATED, ...) return Promise.reject(failure) }

push到当前已处于的页面是无意义的操作（replace允许，因为可能只是查询参数不同）。路径和查询参数完全一致时，直接 reject 并携带 NAVIGATION_DUPLICATED错误码。

3. 守卫链执行

这是导航流程中最复杂的部分，涉及四层守卫的顺序执行和重定向处理：

beforeEach → beforeEnter → beforeResolve → uni API → afterEach

每一层守卫都可能产生三种结果：

守卫的核心难点在于回调风格到 Promise 风格的转换。vue-router 的守卫使用 next()回调，但内部流程是异步的。框架通过 runGuard函数将回调风格统一转换为 Promise＜GuardResult＞：

function runGuard(guard, to, from): Promise＜GuardResult＞ { return new Promise(resolve =＞ { let resolved = false const next = (location?) =＞ { if (resolved) return // 防止多次调用 next resolved = true if (location === false) resolve({ type: 'abort', ... }) else if (location) resolve({ type: 'next', redirect: location }) else resolve({ type: 'next' }) } // 守卫抛异常视为中止 try { const result = guard(to, from, next) // 支持异步守卫 if (result?.catch) result.catch(() =＞ { ... }) } catch { if (!resolved) resolve({ type: 'abort', ... }) } }) }

resolved标志位防止 next()被多次调用。守卫既可以是同步的，也可以返回 Promise（异步守卫），两种情况都被正确处理。

4. 重定向与深度限制

守卫重定向本质上是递归执行导航流程：

private handleGuardResult(result, to, from, mode, redirectDepth) { if (result.redirect) { const redirectTarget = this.matcher.resolve(result.redirect) return this.executeNavigation(redirectTarget, from, mode, redirectDepth + 1) } // ... }

但递归有风险——如果守卫 A 重定向到 B，B 的守卫又重定向到 A，就会无限循环。框架通过 MAX_REDIRECT_DEPTH = 10限制重定向深度，超过后抛出 NAVIGATION_CANCELLED错误。

5. uni API 调用

守卫全部通过后，进入实际的页面跳转：

const navOptions = { path: to.path, meta: to.meta, query: to.query } if (mode === 'push') await navigateTo(navOptions) else await replaceTo(navOptions)

navigateTo和 replaceTo内部根据 meta.isTab自动选择 uni.navigateTo/ uni.switchTab或 uni.redirectTo/ uni.switchTab：

export function navigateTo(options: UniNavigationOptions): Promise＜void＞ { const { path, meta, query } = options if (meta.isTab) { // switchTab 不支持查询参数，给出警告 if (hasQueryParams(query)) warn('uni.switchTab does not support query parameters.') return uniSwitchTab(path) } return uniNavigateTo(path, query) }

所有 uni API 调用都被 promisify 化，统一返回 Promise。失败时封装为 UniApiError，携带 API 名称和原始错误。

6. 状态更新与后置钩子

导航 API 调用成功后：

this.routeState.setCurrentRoute(to) this.guardManager.runAfterGuards(to, from)

setCurrentRoute会对路由对象进行深度冻结（Object.freeze），确保路由状态不可变——任何组件拿到的 currentRoute都不会被意外修改。

路由匹配器：三种定位方式的统一解析

Matcher 维护两个索引：pathMap（路径 → 配置）和 nameMap（名称 → 配置），支持三种路由位置输入：

// 1. 字符串路径（可含查询参数） router.push('/pages/about/index?id=1') // 2. 路径对象 router.push({ path: '/pages/about/index', query: { id: '1' } }) // 3. 命名路由 router.push({ name: 'about', query: { id: '1' } })

三种输入最终都被解析为统一的 RouteLocation：

interface RouteLocation { path: string // 标准化后的路径，如 /pages/about/index name?: string // 路由名称 meta: RouteMeta // 路由元信息 query: Record＜string, string＞ // 查询参数 fullPath: string // 完整路径，如 /pages/about/index?id=1 }

路径标准化（normalizePath）确保 /pages/about/index、pages/about/index、/pages/about/index/都指向同一路由。

严格模式（strict: true）下，命名路由找不到时抛出 ROUTE_NOT_FOUND；非严格模式下仅输出警告并降级为路径导航。

状态同步：uni-app 页面栈与路由器的博弈

这是 uni-app 路由管理中最棘手的问题。uni-app 的页面栈由运行时管理，路由器的 currentRoute是应用层状态——两者可能不同步。

不同步的场景

1.浏览器后退（H5 平台）：用户点击浏览器后退按钮，页面实际回退了，但路由器不知道

2.物理返回键（App 平台）：Android 返回键触发 navigateBack，路由器未感知

3.第三方代码直接调用 uni.navigateTo：绕过路由器，守卫未执行

syncRoute 的设计

syncRoute(): void { const from = this.routeState.getCurrentRoute() const currentPath = getCurrentPagePath() // 从 uni 页面栈读取 if (currentPath === from.path) return // 已同步，无需操作 this.syncCurrentRoute(from) // 读取实际页面信息并更新 }

getCurrentPagePath()通过 getCurrentPages()获取 uni-app 实际页面栈的栈顶页面路径。如果与路由器状态不一致，就从页面栈中读取路径、元信息和查询参数，更新 currentRoute并触发 afterEach后置钩子。

建议在每个页面的 onShow中调用 syncRoute()，因为 onShow在页面从后台回到前台时也会触发，覆盖了浏览器后退和物理返回键的场景。

API 拦截：让 uni.navigateTo 也走路由守卫

interceptUniApi: true选项启用后，直接调用 uni.navigateTo等原生 API 也会经过路由守卫。实现原理是 uni.addInterceptor：

uni.addInterceptor('navigateTo', { invoke(args) { if (_isRouterCall) { _isRouterCall = false // 路由器内部调用，放行 return args } // 外部调用，转由路由器处理 handleInterceptedNavigation('navigateTo', args) return false // 阻止原始调用 } })

关键设计是内部标记_isRouterCall。路由器自身调用 uni.navigateTo时，先通过 markRouterCall()设置标记，拦截器检测到标记后放行，避免守卫链被重复执行。

错误体系：可编程的导航失败处理

框架定义了两层错误类：

RouterError (基类) ├── code: RouterErrorCode // 错误码 └── message: string // 错误信息（自动添加 [uni-router] 前缀） NavigationFailure (子类) ├── to: RouteLocation // 目标路由 ├── from: RouteLocation // 来源路由 └── cause?: unknown // 原始错误（仅 API 调用失败时）

错误码枚举：

双重错误处理机制：

// 1. 全局错误处理器——适合统一上报、日志 router.onError((error, to, from) =＞ { analytics.track('navigation_error', { code: error.code, from: from.path, to: to.path }) }) // 2. 局部 try/catch——适合 UI 反馈 try { await router.push({ name: 'protected' }) } catch (e) { if (e.code === 'NAVIGATION_ABORTED') { showToast('您没有访问权限') } }

Vue 插件集成：与 uni-app H5 的 vue-router 共存

H5 平台上，uni-app 内部使用了 vue-router，会在全局属性上注册 $router和 $route。直接覆盖会导致 uni-app 路由功能异常。框架的 install方法采用了防御性设计：

install(app): void { // 通过 provide/inject 提供路由器（useRouter / useRoute 使用） vueApp.provide(ROUTER_SYMBOL, this) // 仅在 $router 未被定义时设置全局属性 if (!('$router' in vueApp.config.globalProperties)) { vueApp.config.globalProperties.$router = this } if (!('$route' in vueApp.config.globalProperties)) { Object.defineProperty(vueApp.config.globalProperties, '$route', { get: () =＞ this.currentRoute }) } }

优先使用 provide/inject机制（useRouter()/ useRoute()），全局属性作为降级方案。$route使用 getter 定义，确保每次访问都返回最新的路由状态。

设计取舍

在实现过程中，有几个关键的设计取舍值得讨论：

为什么不实现动态路由？

vue-router 支持运行时 router.addRoute()/ router.removeRoute()，但 uni-app 的页面注册是静态的——pages.json在编译期确定，运行时无法添加新页面。动态路由在 uni-app 中没有意义，因此未实现。

为什么守卫使用回调风格而非纯 Promise？

兼容 vue-router 的 API 习惯。vue-router 的守卫使用 next()回调，大量教程和代码示例基于此风格。框架内部将回调转换为 Promise，但对外保持回调接口。

为什么 syncRoute 需要手动调用？

自动监听页面变化需要轮询 getCurrentPages()，性能开销不可接受。onShow是 uni-app 提供的页面可见性回调，在合适的时机调用 syncRoute()是成本最低的方案。

为什么拦截器使用标记而非调用栈分析？

uni-app 的 addInterceptor是全局的，无法区分调用来源。调用栈分析（new Error().stack）性能差且不可靠。简单的布尔标记是最轻量的解决方案。

写在最后

@meng-xi/uni-router的核心设计哲学是在 uni-app 的约束下，提供最大程度的路由管理能力。不替代 pages.json，不破坏原生页面模型，而是在其之上构建守卫链、路由解析和错误处理层。每一个设计决策都围绕"与 uni-app 共存"这个前提展开。

如果你对实现细节感兴趣，源码位于 GitHub，欢迎阅读和贡献。