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.tsCLI 项目import{defineConfig}fromviteimportunifromdcloudio/vite-plugin-uniimport{routeGen}frommeng-xi/unix-router/vite-pluginexportdefaultdefineConfig({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 languts defineUniPage({ title: 首页, name: home, isTab: true }) /script路由表直接使用生成产物// router/index.tsimport{createRouter}frommeng-xi/unix-routerimport{routes}from./routes.gen.uts// 构建期自动生成exportconstroutercreateRouter({routes})::: warning HBuilderX 项目注意HBuilderX 下项目根存在vite.config.ts时会整体替换内置配置内置的uni()不再生效必须自行从 HBuilderX 内置目录引入dcloudio/vite-plugin-uni否则 dev server 启动后页面空白 //main404。详见文档基于文件的路由生成。:::三个独立插件按需选型插件拆分为三个独立实现node/目录重组为route-gen/pages-gen/routes-genshared可独立或组合注册、互不影响插件职责适用场景routeGen页面文件 →pages.json 路由表默认推荐全链路自动同步pagesGen页面文件 → 仅pages.json含宏 dts页面注册自动化路由表自己手写routesGenpages.json→ 仅路由表pages.json手写或由其他工具维护name / meta / beforeEnter 经扩展声明文件注入pagesGenroutesGen组合可替代routeGen两阶段解耦支持从「手写 pages.json」渐进迁移到「全自动」选项随插件拆分公共选项pagesJsonPath/watch/verbose/errorStrategypages段 /router段二、文件路由的关键设计优先级链宏 route-config自定义块 插件推导titleFallback/tabBar配置兜底字段级合并name 自动规范化末段 camelCase → 冲突回退全路径 camelCase → 终极冲突按errorStrategystrict 抛错 / warn 告警跳过保留你的修改preserveRouteChanges默认开启在重生成时保留对路由文件的既有修改与自定义路由pages.json手写的非页面字段globalStyle、uniIdRouter等合并保留扩展路由routesGen模式经routes.ext.uts声明文件注入显式 name / meta 扩展 /beforeEnter函数原文注入生成文件须自包含router.extensions可改路径或false关闭watch页面新增 / 删除 / 修改200ms 去抖串行重跑两阶段流水线类型产物均可关闭route-name.gen.d.tsWEB 端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而 H5JS 运行时字段缺省值是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❌WAAPIelement.animate播放进入 / 退出动画小程序各端❌官方uniVer: x不携带动画字段redirectTo/reLaunch/switchTab官方 Options 无动画字段各端均不携带六、文档站与 core 全量对齐新增「基于文件的路由」章节文件约定 / 扩展路由 / 三插件选型 / HBuilderX 接入说明、query-utils/useOpenerEventChannel/type-pluginPluginContextAPI 页重写 file-based-routing 主指南双语侧边栏更新全量精校中英文档与源码一致性更正动画「仅 App 支持」的平台差异表述含兼容性矩阵七、升级指南0.7.0 → 0.8.0无破坏性变更升级后无需改动代码pnpmaddmeng-xi/unix-router0.8.0版本兼容性功能0.7.00.8.0导航 / 守卫 / 状态 / 参数 / 事件 API✅✅不变插件实例化注册✅✅不变基于文件的路由生成❌✅meng-xi/unix-router/vite-pluginAndroid 云打包Promise.catch / isNavigationFailure 链式用法❌ 编译报错✅App 端navigateTo/navigateBack原生动画❌ 未透传✅ 透传官方仅 App 支持H5 端router.push携带动画 / events 缺省字段❌ 崩溃✅相关链接更新日志基于文件的路由生成文档导航动画文档平台兼容性矩阵欢迎反馈与共建GitHub