发布日期：2026-09-05

unix-router 首个可运行版本正式发布！这是一个为 uni-app x 提供的、API 对标 vue-router 4 的路由管理库，以 UTS 源码（.uts）随 uni_modules 分发，无需预编译，由 uni-app x 编译链按平台现场编译——Web / 小程序 → JS，Android → Kotlin，iOS → Swift。

为什么需要它

uni-app x 原生提供 uni.navigateTo / redirectTo / reLaunch / navigateBack / switchTab，但当页面增多后，「无路由表、无守卫、无统一路由状态、参数传递繁琐」成为痛点。unix-router 用一套与 vue-router 一致的 API 抹平这些差异，并提供登录鉴权、导航控制、参数传递等能力。

核心特性

• vue-router 风格 API：createRouter、push / replace / relaunch / back，自动根据 meta.isTab 切换 switchTab
• 路由匹配：path / name 双索引，字符串 / 对象 / 命名三种解析，strict 严格模式
• 路由守卫：beforeEach / beforeResolve / afterEach / beforeEnter / 组件内守卫（onBeforeRouteLeave / onBeforeRouteUpdate / onBeforeRouteEnter），支持重定向与守卫超时
• 组合式 API：useRouter() / useRoute() / useLink()，响应式 currentRoute
• 参数传递：params（Map<string,string>）经查询编码（__unixr_p_ 保留前缀）跨页传递，不暴露明文键名；query 以字符串经 URL 传递
• 导航控制：重复导航自动拒绝（DUPLICATED）、并发导航自动排队
• 错误体系：RouterError / NavigationFailure / RouterErrorCode，isNavigationFailure() 精准判断，onError 全局捕获
• 状态同步：页面 onShow 自动 syncRoute()，基于 getCurrentPages() 对齐物理返回 / TabBar 切换等非路由器导航

快速开始

// 定义路由配置（path 与 pages.json 一致）
export const routes: RouteConfig[] = [
	{ path: 'pages/index/index', name: 'home', meta: { title: '首页', isTab: true } },
	{ path: 'pages/about/about', name: 'about', meta: { title: '关于', requireAuth: true } }
]

// 创建并安装路由器
export const router = createRouter({ routes, strict: true })
app.use(router) // 注入全局 mixin，onShow 自动 syncRoute()

// 页面内导航
const router = useRouter()
await router.push({ name: 'about', query: new Map([['id', '1']]) })

安装方式

• uni-app 插件市场：直接在 插件市场 中点击“使用 HBuilderX 导入”即可，项目内路径为 @/uni_modules/ux-router/utssdk/index.uts

文档

从入门到精通的完整文档（🟢 入门 → 🟡 进阶 → 🔴 精通）位于 packages/docs，覆盖快速开始、路由配置、导航、守卫与完整实战示例。

平台兼容性

• Web / H5、微信小程序 → 编译为 JS
• App-Android → 编译为 Kotlin / JS
• iOS（VDOM）→ 编译为 Swift
• 底层仅依赖 uni.* 原生导航 API，双模式兼容 uni-app x

后续规划

• 更丰富的守卫能力与冷启动守卫 guardRoute()
• 面向实战的完整演示与性能优化

欢迎使用与反馈：uni-app 插件市场