pages.json中pages数组顺序决定tabbar页面顺序,且必须包含所有可路由页面,否则跳转报错;页面style优先级高于全局window,平台间字段兼容性差异大需分别测试。

pages.json 里 pages 数组顺序决定 tabBar 页面顺序
uni-app 的路由不是靠文件路径自动注册的,pages 数组的书写顺序直接对应底部 tab 切换时的显示顺序和索引。比如你把“首页”写在第二位,它在 tabBar 里就永远是第二个按钮,哪怕文件路径叫 pages/index/index.vue 也没用。
常见错误现象:tabBar 图标点不动、跳转错页、某个页面死活不进 onLoad —— 很可能只是它没被写进 pages 数组,或者写在了 subNVue 或 subNVues 下面(那属于原生子窗体,不走页面栈)。
-
pages数组必须包含所有可被路由访问的页面,包括 tabBar 页面和非 tabBar 页面 - 非 tabBar 页面也得列进来,否则
uni.navigateTo({ url: '/pages/xxx' })会报错:「找不到页面」 - 如果用了分包,主包的
pages.json只管主包页面;分包自己的pages.json只对本分包生效,且不能配tabBar
配置页面样式时,style 节点优先级高于全局 window
每个 pages 数组项可以带 style 字段,它会覆盖 globalStyle 和 window 下的同名配置。比如你在 window 里设了 "navigationBarBackgroundColor": "#000000",但在某个页面的 style 里写了 "navigationBarBackgroundColor": "#ffffff",那这个页面的导航栏就是白的。
容易踩的坑:navigationStyle 设为 "custom" 后,原生导航栏消失,但很多开发者忘了手动加 <uni-nav-bar></uni-nav-bar> 或自定义 view,结果页面顶部留一大片空白;更隐蔽的是,iOS 下 custom 模式默认不透出状态栏,需要额外加 "statusBarStyle": "black" 才能控制文字颜色。
-
"enablePullDownRefresh": true必须在页面级style里开,window里配无效 -
"onReachBottomDistance"同理,只认页面级配置 - H5 平台不支持
"navigationBarTextStyle"的"white"值,会 fallback 成"black",别在这儿卡测试
tabBar 配置必须满足平台限制,否则编译不报错但运行异常
微信小程序要求 tabBar.list 至少 2 项、最多 5 项;App 端支持 2–9 项;H5 则完全忽略 tabBar 配置(除非你用 uni-app 的 H5 tabBar 插件)。这些限制不会在 vue-cli-service uni-build 时报错,但真机上 tabBar 可能不显示、图标错位、点击无响应。
使用场景:你加了个新页面想放进 tabBar,顺手复制粘贴了旧项,结果漏改了 pagePath 或 iconPath —— 这时图标会显示成默认问号,Android 上甚至可能闪退。
-
pagePath必须和pages数组中某一项的路径完全一致(包括大小写),/pages/home/index≠pages/home/index -
iconPath和selectedIconPath必须是本地静态路径,不支持网络地址或变量,也不支持@/别名 - App 端若开启
"mode": "tab"(老版配置),会强制走原生 tabBar,此时pages.json里的tabBar将被忽略
subNVues 不参与路由栈,但需手动管理显隐和通信
subNVues 是 App 独有功能,用来放原生子窗体(比如悬浮按钮、半屏弹窗),它不进页面栈,uni.navigateBack() 不影响它,也不会触发 onHide/onShow。但它一旦配置在 pages.json 里,就会随所属页面一起创建,生命周期绑定在父页面上。
为什么这样做:为了性能。纯 vue 页面做复杂动效(如地图覆盖物、实时弹幕)卡顿严重,用原生子窗体更稳。但代价是通信麻烦、调试困难。
-
subNVues的id必须全项目唯一,重复会导致后加载的覆盖前一个 - 不能用
uni.$emit直接传数据给 subNVue,得用uni.postMessage+plus.webview.getWebviewById手动取实例 - subNVue 的
style中top/bottom支持百分比,但left/right只支持 px,写"left": "10%"在某些 Android 机型上会失效
navigationBarBackgroundColor 在微信里是十六进制字符串,在 App 里还能接受 rgb(),而 H5 根本不认这个字段。改一处,三个平台各测一遍,才是常态。










