深入剖析 @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

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

next() 调用	GuardResult	后续行为
next()	{ type: 'next' }	继续执行下一层守卫
next(false)	{ type: 'abort', code: NAVIGATION_ABORTED }	中止导航，reject
next({ path: '/login' })	{ type: 'next', redirect: { path: '/login' } }	递归执行重定向导航

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

function runGuard(guard: NavigationGuard, to: RouteLocation, from: RouteLocation): Promise<GuardResult> {
    return new Promise(resolve => {
        let resolved = false
        const next: NavigationGuardNext = (location?) => {
            if (resolved) return  // 防止多次调用 next
            resolved = true
            if (location === false) resolve({ type: 'abort', code: NAVIGATION_ABORTED })
            else if (location) resolve({ type: 'next', redirect: location })
            else resolve({ type: 'next' })
        }
        // 守卫抛异常视为中止
        try {
            const result = guard(to, from, next)
            // 支持异步守卫
            if (result?.catch) result.catch(() => { if (!resolved) resolve({ type: 'abort', ... }) })
        } 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 调用失败时）

错误码枚举：

错误码	触发场景
NAVIGATION_ABORTED	守卫调用 next(false)
NAVIGATION_CANCELLED	重定向深度超限
NAVIGATION_DUPLICATED	push 到当前页面
ROUTE_NOT_FOUND	严格模式下命名路由不存在
NAVIGATION_API_ERROR	uni API 调用失败
SETUP_ERROR	useRouter() 在 setup 外调用

双重错误处理机制：

// 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，欢迎阅读和贡献。