更新记录

2.5.0（2026-08-23） 下载此版本

新增

• RouterLink H5 端渲染为原生 <a> 标签 - 恢复浏览器链接的原生能力（语义化、右键新标签页、地址识别、无障碍、href 原生行为）
  • H5 端通过 #ifdef H5 条件编译渲染为 <a :href>，href 由 useLink 响应式提供；普通左键 preventDefault 后交由路由器导航，守卫链照常生效
  • 修饰键（Ctrl/Cmd/Shift/Alt）或中键点击保留浏览器原生行为（如新标签页打开）
  • href 自动适配 hash 路由（# 前缀），确保右键"在新标签页打开"能正确路由
  • 其他平台（App/小程序）渲染为 <navigator>（uni-app 原生导航组件），行为不变
  • 脚本中修饰键判断与 hash 前缀逻辑使用 #ifdef H5 条件编译，非 H5 平台编译期剔除，避免非 H5 事件对象无 button 属性导致导航被误拦截

2.4.0（2026-08-21） 下载此版本

新增

• 可控重定向（Controllable Redirect） - 守卫返回值模式补全重定向方式控制能力，通过返回 { location, mode } 对象可显式指定重定向使用的导航方式
  • 新增 NavigationRedirect 接口，扩展 NavigationGuardReturn 类型（增加 | NavigationRedirect 分支）
  • mode 支持 'push'（uni.navigateTo）/ 'replace'（uni.redirectTo）/ 'relaunch'（uni.reLaunch）
  • 重定向方式优先级：显式 mode > 原始导航方式 > back 回退 relaunch
  • mode 缺省时行为不变（沿用原始导航方式），完全向后兼容
  • guardRoute() 冷启动场景同步支持可控重定向
  • 示例：

    router.beforeEach((to, from) => {
    if (to.meta.requireAuth && !isLoggedIn()) {
        // 用 replace 跳转登录页，避免登录页残留在页面栈中
        return { location: { name: 'login', query: { redirect: to.fullPath } }, mode: 'replace' }
    }
    })

修复

• 字符串路径含 query 时注入内部 key 产生双 ? - injectQueryKey 对已含 query 的字符串路径（如 '/detail?id=1'）注入 __nav_id / __params_key 时未拆分已有 query，导致拼接出 ?id=1?__nav_id=... 的畸形 URL
  • 修复：字符串路径先按 ? 拆分为 path + 已有 query，再合并注入，最终为 ?id=1&__nav_id=...
  • 同时惠及 ChannelPlugin（__nav_id）与 ParamsPlugin（__params_key）

2.3.1（2026-08-20） 下载此版本

修复

• RouterLink 组件 H5 端控制台错误 - 将根元素从 <navigator> 替换为 <view>，解决 H5 端每次点击时 uni-h5 输出 [ERROR] <navigator/> should have url attribute 控制台错误的问题
  • <view> 同样支持 hover-class / hover-stop-propagation / hover-start-time / hover-stay-time 等点击态属性
  • 实际导航完全由 @click.stop="handleClick" 调用路由器 API 完成，不影响导航功能

优化

• 组件 emits 类型重构 - 将 RouterLinkEmits、TabBarEmits 从 interface 改为 type 别名，与其他类型定义风格保持一致

平台兼容性

uni-app(3.8.2)

uni-app x(3.8.2)

其他

@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，RouterErrorCode 错误码，isNavigationFailure() 精准判断
• 组合式 API - useRouter() / useRoute() / usePageChannel() / onBeforeRouteLeave() / useLink()

安装

将 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) => {
    if (to.meta.requireAuth && !isLoggedIn()) {
        return { name: 'login' } // 重定向到登录页
    }
    // 不返回值（或 return true）表示放行
})

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/

License

MIT