`wevu/router`

wevu/router 是 Wevu 提供的独立路由子入口，目标是尽量对齐 Vue Router 的导航心智，同时保持对小程序路由能力边界的明确约束。

如果你只需要拿到原生页面路由对象，请继续使用 wevu 主入口里的 useNativeRouter() / useNativePageRouter()；如果你需要守卫、失败分类、resolve() 与更统一的导航封装，请使用 wevu/router。

创建与获取

createRouter()：负责创建并注册默认 router 实例
useRouter()：负责获取当前已创建的 router 实例

推荐在应用入口或上层 setup() 中先调用一次 createRouter()，后续业务代码里再通过 useRouter() 读取。

安装方式

wevu 请安装到 devDependencies：

pnpm add -D wevu

不要把它放到 dependencies。

什么时候使用

想把页面跳转从“零散 wx.navigateTo 调用”升级到统一导航入口
想把跳转前判断收敛到 beforeEach / beforeResolve / beforeEnter
想获得更接近 Vue Router 的 resolve()、currentRoute 与失败分类能力

最小示例

import { createRouter, useRouter } from 'wevu/router'

// 在应用入口或上层 setup 中先创建一次
createRouter()

// 业务代码里只负责获取实例
const router = useRouter()

await router.push('/pages/home/index')
await router.replace('/pages/profile/index?tab=security')
await router.back(1)

在 App 中注册

推荐在应用入口或 App 级 setup() 中创建一次 router：

import { createApp } from 'wevu'
import { createRouter } from 'wevu/router'

const router = createRouter()

createApp({
  setup() {
    // 这里通常不需要额外返回 router
  },
}).use(router)

如果你只是想让后续页面/组件里的 useRouter() 能拿到默认实例，最关键的是这句：

const router = createRouter()

createRouter() 创建时就会注册当前默认 router；createApp(...).use(router) 则会把它同步挂到 app.config.globalProperties.$router。

`app.vue` + `<script setup>` 写法

如果你使用的是 Weapp-vite + Vue SFC，通常可以直接在 app.vue 顶层创建：

vue

<script setup lang="ts">
import { createRouter } from 'wevu/router'

createRouter()
</script>

关键点：

必须是顶层语句
不要放进 onLaunch()、onShow() 或其他 hook 里
这样后续页面/组件里的 useRouter() 才能直接拿到默认实例

核心能力

useRouter()：获取当前已创建的路由实例
createRouter()：创建带守卫、失败分类的高阶路由器
useRoute()：读取当前路由快照
resolveRouteLocation()：预解析目标位置
parseQuery() / stringifyQuery()：query 处理工具
createNavigationFailure() / isNavigationFailure()：失败对象与判定
NavigationFailureType：失败类别枚举

常见心智

路径优先

await router.push('/pages/post/1/index?preview=0')

在小程序里，页面物理路径本身就是分包、注册和跳转语义的一部分，所以文档更推荐你直接使用真实页面路径。

守卫用于统一前置判断

import { createRouter } from 'wevu/router'

// 常见做法是在应用入口统一创建 router
const router = createRouter({
  beforeEach(to) {
    if (to.path.startsWith('/pages/private/') && !isLoggedIn()) {
      return '/pages/login/index'
    }
  },
})

这样比把跳转限制散落在各个页面里更容易维护。

小程序不支持真正 forward 栈

const result = await router.forward()

这在小程序里通常会返回 NavigationFailureType.aborted，属于预期行为，不是 bug。

调试与迁移建议

用 resolve() 提前检查 href / matched / redirectedFrom
把业务里的零散跳转判断迁移到守卫，而不是继续散落在页面逻辑里
优先保留小程序真实路径，不要过早抽象成重度命名路由体系

wevu/router ​

什么时候使用 ​

最小示例 ​

在 App 中注册 ​

app.vue + <script setup> 写法 ​

核心能力 ​

常见心智 ​

路径优先 ​

守卫用于统一前置判断 ​

小程序不支持真正 forward 栈 ​

调试与迁移建议 ​

相关页面 ​