0.8.0重磅发布：路由自动生成功能上线

v0.8.0 为 非破坏性 版本（0.7.0 → 0.8.0），两条主线：① 新增 基于文件的路由生成 插件——页面就近声明，构建期自动产出 pages.json 与路由表，消除双份手工维护；② 集中修复跨端问题——Android 云打包 UTS 强类型编译错误、H5 端 router.push 崩溃与 uni.* 编译警告，并补全 App 端导航动画透传。升级无需改动代码。

一、新特性：基于文件的路由生成

为什么需要

uni-app x 项目里，一个页面的元信息要在两处重复维护：

// router/routes.ts —— 手写路由表
{ path: 'pages/index/index', name: 'home', meta: { title: '首页', isTab: true } }

// pages.json —— 手写页面条目（title 与上面 meta.title 重复维护）
{ "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } }

页面一多，path / title / tabBar / isTab 极易两处不同步。v0.8.0 引入构建期 dev 工具（随路由库同包分发，运行时零额外依赖）：在页面旁就近声明，构建期自动生成 pages.json（含 tabBar / subPackages）与路由表 routes.gen.uts。

快速上手

从新增的子路径导出 @meng-xi/unix-router/vite-plugin 引入 vite 插件（unplugin 打包内置，vite / webpack 通用）：

// vite.config.ts（CLI 项目）
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { routeGen } from '@meng-xi/unix-router/vite-plugin'

export default defineConfig({
	plugins: [
		uni(),
		routeGen({
			pages: {
				pagesDir: 'pages',
				subPackages: [{ root: 'pages-sub', dir: 'pages-sub' }],
				entryPage: 'pages/index/index',
				tabBar: { color: '#7A7E83', selectedColor: '#007AFF', backgroundColor: '#FFFFFF' }
			},
			router: { dts: true }
		})
	]
})

页面就近声明 defineUniPage 宏：

<!-- pages/index/index.uvue -->
<script setup lang="uts">
	defineUniPage({ title: '首页', name: 'home', isTab: true })
</script>

路由表直接使用生成产物：

// router/index.ts
import { createRouter } from '@meng-xi/unix-router'
import { routes } from './routes.gen.uts' // 构建期自动生成

export const router = createRouter({ routes })

::: warning HBuilderX 项目注意
HBuilderX 下项目根存在 vite.config.ts 时会整体替换内置配置（内置的 uni() 不再生效），必须自行从 HBuilderX 内置目录引入 @dcloudio/vite-plugin-uni；否则 dev server 启动后页面空白 / /main 404。详见文档基于文件的路由生成。
:::

三个独立插件，按需选型

插件拆分为三个独立实现（node/ 目录重组为 route-gen / pages-gen / routes-gen + shared），可独立或组合注册、互不影响：

插件 职责 适用场景
routeGen 页面文件 → pages.json + 路由表 默认推荐，全链路自动同步
pagesGen 页面文件 → 仅 pages.json（含宏 dts） 页面注册自动化，路由表自己手写
routesGen pages.json → 仅路由表 pages.json 手写或由其他工具维护；name / meta / beforeEnter 经扩展声明文件注入
  • pagesGen + routesGen 组合可替代 routeGen，两阶段解耦，支持从「手写 pages.json」渐进迁移到「全自动」
  • 选项随插件拆分：公共选项（pagesJsonPath / watch / verbose / errorStrategy）+ pages 段 / router 段

二、文件路由的关键设计

  • 优先级链：宏 > <route-config> 自定义块 > 插件推导（titleFallback / tabBar 配置兜底），字段级合并
  • name 自动规范化：末段 camelCase → 冲突回退全路径 camelCase → 终极冲突按 errorStrategy（strict 抛错 / warn 告警跳过）
  • 保留你的修改：preserveRouteChanges（默认开启）在重生成时保留对路由文件的既有修改与自定义路由；pages.json 手写的非页面字段（globalStyle、uniIdRouter 等）合并保留
  • 扩展路由：routesGen 模式经 routes.ext.uts 声明文件注入显式 name / meta 扩展 / beforeEnter（函数原文注入生成文件，须自包含；router.extensions 可改路径或 false 关闭）
  • watch：页面新增 / 删除 / 修改，200ms 去抖串行重跑两阶段流水线
  • 类型产物（均可关闭）：route-name.gen.d.ts（WEB 端 RouteNameMap 字面量类型）、define-uni-page.d.ts（宏类型声明）

三、修复：Android 云打包编译错误（UTS 强类型）

两处 UTS 强类型约束导致的 Kotlin 编译失败：

  • Promise.catch 回调参数类型：any → any | null。UTS 的 any 编译为 Kotlin 非空 Any，无法匹配 UTSPromise.catch 要求可空回调参数的重载
  • isNavigationFailure 首参签名：Error | null → any | null（内部 instanceof 收窄），修复 .catch((e) => isNavigationFailure(e)) 链式用法编译失败

四、修复：H5 端两处问题

  • router.push 崩溃：pickAnimation / toUniAnimation / pickEvents 对可选字段 === null 判断后直接取 .length / .size，而 H5（JS 运行时）字段缺省值是 undefined，抛 TypeError 中断导航；统一 ?? null 归一化后判断
  • uni.* 导航 API 编译类型警告：WEB 端导航 options 收敛为统一桥接函数 applyWebNavOptions（动态字段经 as any 桥接），消除 uni.navigateTo 等的编译警告，运行时行为不变

五、补全：App 端导航动画透传

AnimationPlugin 此前 App 端实际未透传动画参数（0.7.0 为规避非蒸汽编译错误，App 端使用了无动画字段的字面量）。0.8.0 换用官方具名 Options 补全：uni.navigateTo / uni.navigateBack 携带 animationType / animationDuration。

按 HBuilderX 官方类型声明（@uniPlatform 标注），动画字段仅 App 支持：

平台 动画字段支持 本库行为
App-Android / iOS / HarmonyOS ✅ 4.18+ / 4.25+ / 4.61+ 透传原生窗口打开 / 关闭动画
Web / H5 ❌ WAAPI（element.animate）播放进入 / 退出动画
小程序各端 ❌（官方 uniVer: "x"） 不携带动画字段
redirectTo / reLaunch / switchTab 官方 Options 无动画字段 各端均不携带

六、文档站与 core 全量对齐

  • 新增「基于文件的路由」章节（文件约定 / 扩展路由 / 三插件选型 / HBuilderX 接入说明）、query-utils / useOpenerEventChannel / type-plugin（PluginContext）API 页
  • 重写 file-based-routing 主指南，双语侧边栏更新
  • 全量精校中英文档与源码一致性，更正动画「仅 App 支持」的平台差异表述（含兼容性矩阵）

七、升级指南

0.7.0 → 0.8.0 无破坏性变更，升级后无需改动代码：

pnpm add @meng-xi/unix-router@0.8.0

版本兼容性

功能 0.7.0 0.8.0
导航 / 守卫 / 状态 / 参数 / 事件 API ✅ ✅（不变）
插件实例化注册 ✅ ✅（不变）
基于文件的路由生成 ❌ ✅ @meng-xi/unix-router/vite-plugin
Android 云打包（Promise.catch / isNavigationFailure 链式用法） ❌ 编译报错 ✅
App 端 navigateTo / navigateBack 原生动画 ❌ 未透传 ✅ 透传（官方仅 App 支持）
H5 端 router.push（携带动画 / events 缺省字段） ❌ 崩溃 ✅

相关链接

欢迎反馈与共建：GitHub

posted @ 2026-09-27 22:10  PedroQue99  阅读(22)  评论(0)    收藏  举报