更新记录

1.0.0（2026-06-07） 下载此版本

新增

• 路由器核心 - createRouter() 创建路由器实例，支持 routes、strict、interceptUniApi 配置项
• 路由导航 - router.push() 导航到新页面，router.replace() 替换当前页面，router.back() 返回上一页
• 命名路由 - 通过 name 字段进行导航，无需硬编码路径字符串
• 路由元信息 - meta 字段支持 title、isTab、requireAuth 及自定义扩展字段
• 全局前置守卫 - router.beforeEach() 在每次导航前执行，支持中止、放行和重定向
• 全局解析守卫 - router.beforeResolve() 在所有前置守卫和路由独享守卫完成后执行
• 全局后置钩子 - router.afterEach() 在导航完成后执行
• 路由独享守卫 - beforeEnter 配置项，进入特定路由时触发
• 守卫重定向 - 守卫中调用 next(location) 可重定向到其他路由，支持多级重定向（最大深度 10）
• 组合式 API - useRouter() 获取路由器实例，useRoute() 获取当前路由位置
• 错误处理 - RouterError 路由错误类，NavigationFailure 导航失败类（包含 to、from、cause 信息）
• 全局错误捕获 - router.onError() 注册错误处理回调
• 路由查询 - router.resolve() 解析路由位置（不执行导航），router.getRoutes() 获取所有路由配置，router.hasRoute() 检查路由是否存在
• TypeScript 类型提示 - RouteNameMap 接口支持模块增强，为路由名称和路径提供自动补全和类型检查
• uni API 拦截 - interceptUniApi 选项可拦截 uni.navigateTo / uni.redirectTo / uni.switchTab / uni.navigateBack，统一走路由守卫流程
• 重复导航检测 - push 到当前页面时自动拒绝并抛出 NAVIGATION_DUPLICATED 错误
• 并发导航排队 - 多次并发导航自动排队，前一次完成后再执行下一次
• 路径自动规范化 - 路径自动补全前导 /，查询字符串自动解析为 query 对象

错误码

平台兼容性

uni-app(3.7.9)

uni-app x(3.7.9)

其他

@meng-xi/uni-router

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

特性

• vue-router 风格 API - 熟悉的 push / replace / back 导航方式，零学习成本
• 路由守卫 - 全局前置守卫 beforeEach、解析守卫 beforeResolve、后置钩子 afterEach、路由独享守卫 beforeEnter
• 命名路由 - 通过 name 进行导航，无需硬编码路径字符串
• 路由元信息 - meta 字段支持页面标题、权限标记、TabBar 标识等自定义数据
• 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 实例方法

错误码

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