更新记录

2.0.0（2026-07-13） 下载此版本

新增

• 插件架构 - 核心功能拆分为按需注册的插件，未注册的插件不增加包体积和运行时开销
  • RouterPlugin 接口 - Swiper.js 风格的插件系统，通过 install(context, options) 注册 hook
  • PluginContext 接口 - 路由器暴露给插件的 hook 注册 API，支持 7 种生命周期 hook
  • RouterOptions.plugins - 插件注册配置项，传入插件数组即可启用对应功能
  • PLUGIN_REQUIRED 错误码 - 使用未注册插件的功能时抛出，帮助快速定位问题
• ParamsPlugin - 页面参数传递插件（从核心拆分）
  • push / replace / relaunch 支持 params 参数传递复杂数据，不暴露在 URL 中
  • 参数持久化存储 persistent，H5 刷新后仍可读取
  • RouterOptions.paramsPersistent 全局默认值
• ChannelPlugin - 页面间通信插件（从核心拆分并增强）
  • useUniEventChannel 选项 - 启用后所有导航方式（push/replace/relaunch）均支持 eventChannel
  • UniEventChannel 类 - 基于 uni.$emit/$on/$off/$once 全局事件总线实现，替代仅 push 可用的原生 EventChannel
  • Sticky 事件缓存机制 - emit() 始终缓存事件参数，on() / once() 注册时异步触发已缓存事件，解决时序竞态
  • usePageChannel() 组合式 API - 目标页面获取通信通道的便捷方法
  • noopChannel 导出 - 空操作通道，无 __navId 时返回，避免空指针
• InterceptorPlugin - uni API 拦截插件（从核心拆分）
  • RouterOptions.interceptUniApi 选项需要此插件才能生效
  • 拦截 navigateTo / redirectTo / switchTab / reLaunch / navigateBack，统一守卫流程
• AnimationPlugin - 导航动画插件（从核心拆分）
  • push / replace / back 支持动画参数，仅 App 端生效
  • 路由级 meta.animation 默认动画配置
• applySyncHooks 导航预处理 - 在 setCurrentRoute 前执行 routeSyncHooks，将 __nav_id 等内部 key 从 query 提取到 params，确保目标页 onLoad / <script setup> 时 usePageChannel() 能正确获取通道

优化

• syncRoute 去重优化 - 比较前先执行 runSyncHooks 移除 URL query 中的内部 key（如 __nav_id、__params_key），避免因内部 key 差异导致 onShow 每次触发多余的 onRouteChange 事件
• 路由位置解析逻辑集中 - router/index.ts 中的 resolveLocation / extractParamsKey 等逻辑提取到 utils/route.ts，消除与 router/location.ts 的重复
• 插件间数据共享 - pluginData: Record<string, any> 在导航流程各阶段间传递，插件通过约定 key 存取数据，避免直接耦合

破坏性变更

• createRouter 必须显式注册插件 - params / events / animation / interceptUniApi 功能不再默认可用，需在 plugins 数组中注册对应插件

  // 1.x - 功能默认可用
  const router = createRouter({ routes, interceptUniApi: true })
  
  // 2.0 - 需要显式注册插件
  const router = createRouter({
  routes,
  plugins: [ParamsPlugin, ChannelPlugin, InterceptorPlugin, AnimationPlugin],
  interceptUniApi: true
  })

• @meng-xi/uni-router/plugins 子路径导出 - 插件从主入口 @meng-xi/uni-router 和子路径 @meng-xi/uni-router/plugins 均可导入
• 未注册插件功能抛出 PLUGIN_REQUIRED - 使用 params 但未注册 ParamsPlugin、使用 events 但未注册 ChannelPlugin、使用 animation 但未注册 AnimationPlugin、设置 interceptUniApi: true 但未注册 InterceptorPlugin 时，均抛出 PLUGIN_REQUIRED 错误

迁移指南

1. 在 createRouter 中添加 plugins 数组，按需注册功能插件
2. 从 @meng-xi/uni-router 导入插件：import { ParamsPlugin, ChannelPlugin, InterceptorPlugin, AnimationPlugin } from '@meng-xi/uni-router'
3. usePageChannel() 从 @meng-xi/uni-router 主入口导入
4. uni_modules 版本从 ./uni_modules/mxuni-router-v2/js_sdk/index.js 导入

平台兼容性

uni-app(3.7.11)

uni-app x(3.7.11)

其他

@meng-xi/uni-router

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

仅支持 Vue 3 — 基于 Vue 3 Composition API，不支持 Vue 2 项目。

特性

• vue-router 风格 API - push / replace / relaunch / back
• 路由守卫 - beforeEach / beforeResolve / afterEach / beforeEnter，guardRoute 冷启动补执行
• 命名路由 & 路由元信息 - 通过 name 导航，meta 携带自定义数据
• TypeScript 类型提示 - 路由名称和路径自动补全与类型检查
• 插件架构 - ParamsPlugin / ChannelPlugin / InterceptorPlugin / AnimationPlugin 按需注册
• 页面间通信 - useUniEventChannel 内置通信管理器，所有导航方式支持 eventChannel
• 声明式组件 - RouterLink / TabBar / TabBarItem，easycom 自动注册
• 页面参数传递 - params 传递复杂数据不暴露 URL，back() 后自动保留
• 查询参数增强 - queryInt() / queryNumber() / queryBool()
• 导航动画 - push / replace / back 支持动画参数，仅 App 端
• 路由状态自动同步 - 全局 Mixin 自动 syncRoute()，无需手动同步
• 错误处理 - RouterError / NavigationFailure / UniApiError，支持 instanceof 精准判断
• 组合式 API - useRouter() / useRoute() / usePageChannel()

安装

将 mxuni-router-v2 目录复制到项目的 uni_modules 目录下即可，无需 npm 安装。

快速开始

1. 创建路由器

// main.ts
import { createSSRApp } from 'vue'
import { createRouter, ParamsPlugin, ChannelPlugin, InterceptorPlugin, AnimationPlugin } from './uni_modules/mxuni-router-v2/js_sdk/index.js'
import App from './App.vue'

const router = createRouter({
    routes: [
        { path: 'pages/index/index', name: 'home', meta: { title: '首页', isTab: true } },
        { path: 'pages/about/about', name: 'about', meta: { requireAuth: true } }
    ],
    plugins: [ParamsPlugin, ChannelPlugin, InterceptorPlugin, AnimationPlugin],
    interceptUniApi: true // 需要 InterceptorPlugin
})

export function createApp() {
    const app = createSSRApp(App)
    app.use(router) // 自动注册全局 mixin，onShow 时同步 currentRoute
    return { app }
}

2. 路由导航

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

const router = useRouter()
const route = useRoute()

await router.push({ path: '/pages/about/about', query: { id: '1' } })
await router.push({ name: 'about' })
await router.push({ path: '/pages/detail/detail', params: { info: { name: 'Tom' } } })
await router.back()

3. 路由守卫

router.beforeEach((to, from, next) => {
    if (to.meta.requireAuth && !isLoggedIn()) {
        next({ name: 'login' }, { mode: 'replace' })
    } else {
        next()
    }
})

4. 组件

组件通过 easycom 自动注册，直接在模板中使用即可：

<!-- RouterLink：声明式导航 -->
<RouterLink :to="{ name: 'about' }">关于</RouterLink>

<!-- TabBar / TabBarItem：自定义底部导航 -->
<TabBar selected-color="#007aff">
    <TabBarItem to="/pages/index/index" icon-path="/static/home.png" text="首页" />
    <TabBarItem to="/pages/about/about" icon-path="/static/user.png" text="我的" dot />
</TabBar>

文档

📖 https://mengxi-studio.github.io/uni-router/v1/

License

MIT