@meng-xi/uni-router

为 uni-app 提供类似 vue-router 风格的路由管理系统（uni_modules 版本）。

特性

• vue-router 风格 API - 熟悉的 push / replace / back 导航方式，零学习成本
• 路由守卫 - 全局前置守卫 beforeEach、解析守卫 beforeResolve、后置钩子 afterEach、路由独享守卫 beforeEnter
• 守卫超时保护 - 守卫未调用 next() 时自动中止导航，超时时间可配置（guardTimeout）
• 命名路由 - 通过 name 进行导航，无需硬编码路径字符串
• 路由元信息 - meta 字段支持页面标题、权限标记、TabBar 标识等自定义数据
• uni API 拦截 - 拦截 uni.navigateTo 等原生导航 API，确保守卫始终生效（interceptUniApi）
• 路由状态同步 - syncRoute() 将路由状态与实际页面栈同步，处理物理返回键等非路由器导航
• 路由变化监听 - onRouteChange() 订阅路由状态变化，包括导航完成和状态同步
• RouterLink 组件 - 声明式导航组件，支持 push / replace 模式和 @error 事件
• TypeScript 类型提示 - 通过模块增强为路由名称和路径提供自动补全和类型检查
• 错误处理 - 完整的 RouterError / NavigationFailure 体系，支持 onError 全局捕获
• 组合式 API - useRouter() / useRoute() 在组件中便捷访问路由器
• uni_modules 集成 - 通过 uni_modules 方式安装，无需 npm，开箱即用

📖 完整文档：https://mengxi-studio.github.io/uni-router/

安装

uni_modules（推荐）

将 mxuni-router 目录复制到项目的 uni_modules 目录下：

src/  
  └── uni_modules/  
        └── mxuni-router/  
              ├── js_sdk/  
              │     ├── index.js  
              │     ├── index.cjs  
              │     ├── index.d.ts  
              │     └── index.d.cts  
              ├── components/  
              │     └── mxuni-router/  
              │           └── mxuni-router.vue  
              ├── package.json  
              └── readme.md

npm

pnpm add @meng-xi/uni-router

npm 方式需将导入路径改为 @meng-xi/uni-router。

快速开始

1. 创建路由器

// main.ts  
import { createSSRApp } from 'vue'  
import { createRouter } from './uni_modules/mxuni-router/js_sdk/index.js'  
import App from './App.vue'  

const router = createRouter({  
    routes: [  
        { path: 'pages/index/index', name: 'home', meta: { title: '首页' } },  
        { path: 'pages/about/about', name: 'about', meta: { title: '关于', requireAuth: true } },  
        { path: 'pages/user/user', name: 'user', meta: { title: '我的', isTab: true } }  
    ],  
    strict: true  
})  

export function createApp() {  
    const app = createSSRApp(App)  
    app.use(router)  
    return { app }  
}

2. 路由导航

import { useRouter, useRoute } from './uni_modules/mxuni-router/js_sdk/index.js'  

// 在组件 setup 中使用  
const router = useRouter()  
const route = useRoute()  

// 路径导航  
await router.push('/pages/about/about')  
await router.push({ path: '/pages/about/about', query: { id: '1' } })  

// 命名导航  
await router.push({ name: 'about' })  

// 返回  
await router.back()  
await router.back(2) // 返回两级

3. 路由守卫

// 全局前置守卫 - 登录验证  
router.beforeEach((to, from, next) => {  
    if (to.meta.requireAuth && !isLoggedIn()) {  
        next({ name: 'login', query: { redirect: to.fullPath } })  
    } else {  
        next()  
    }  
})  

// 全局后置钩子  
router.afterEach((to, from) => {  
    console.log(`导航完成: ${from.path} → ${to.path}`)  
})

4. 自动生成路由配置（推荐）

配合 @meng-xi/vite-plugin 的 generateRouter 插件，可从 pages.json 自动生成路由配置和类型声明：

pnpm add @meng-xi/vite-plugin -D

// vite.config.ts  
import { defineConfig } from 'vite'  
import uni from '@dcloudio/vite-plugin-uni'  
import { generateRouter } from '@meng-xi/vite-plugin'  

export default defineConfig({  
    plugins: [  
        uni(),  
        generateRouter({  
            pagesJsonPath: 'src/pages.json',  
            outputPath: 'src/router.config.ts',  
            dts: true,  
            metaMapping: {  
                navigationBarTitleText: 'title',  
                requireAuth: 'requireAuth'  
            }  
        })  
    ]  
})

然后在 main.ts 中导入生成的路由配置：

import { createRouter } from './uni_modules/mxuni-router/js_sdk/index.js'  
import routes from './router.config'  

const router = createRouter({ routes })

API 概览

核心

Router 实例方法

错误码

RouterOptions 配置项

RouterLink 组件

声明式导航组件，对应 uni-app 的 <navigator>，自动通过路由器执行导航。

<!-- 路径导航 -->  
<mxuni-router to="/pages/about/about">  
    <view>跳转到关于页</view>  
</mxuni-router>  

<!-- replace 模式 -->  
<mxuni-router to="/pages/about/about" replace>  
    <view>替换当前页</view>  
</mxuni-router>  

<!-- 捕获导航失败 -->  
<mxuni-router to="/pages/about/about" @error="onNavError">  
    <view>跳转</view>  
</mxuni-router>

TypeScript 类型提示

启用 dts: true 后，generateRouter 插件自动生成类型声明文件，为路由导航提供类型安全：

// 路由名称自动补全  
router.push({ name: 'pagesIndexIndex' }) // ✅ 自动补全  
router.push({ name: 'invalidName' }) // ❌ 类型错误  

// 路径自动补全  
router.push({ path: '/pages/index/index' }) // ✅ 自动补全  
router.push({ path: '/invalid/path' }) // ❌ 类型错误

与 pages.json 的关系

Uni Router 不替代 pages.json，而是与之配合使用：

License

MIT