4.1 pages.json 与路由规则

4.1 pages.json 与路由规则

本节导读：动线设计的第一步是登记。本节拆解 pages.json 的结构：pages 数组与首屏规则、globalStyle 与页面级窗口配置的覆盖关系、path 命名公约，顺带把 manifest.json 里影响路由的配置一并交代。读完你应当能写出一份三端行为一致的页面登记表。

没登记就没有页面

uni-app 有一条铁律：pages 目录下的 .vue 文件只是源码，只有登记进 pages.json 才会成为可跳转的页面。新页面"点了没反应"的排查，第一站永远是这份 json。商城项目的登记表长这样：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": { "navigationBarTitleText": "会员商城" }
    },
    {
      "path": "pages/goods/detail",
      "style": { "navigationBarTitleText": "商品详情", "enablePullDownRefresh": false }
    },
    {
      "path": "pages/order/submit",
      "style": { "navigationBarTitleText": "确认订单" }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "会员商城",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f6f7fb"
  }
}
​

三条规则藏在数组里。第一，数组的第一个元素是启动页——想换首屏就调整顺序，而不是找什么"首页配置"。第二，页面级 style 覆盖 globalStyle，窗口表现逐字段合并，页面只写差异项是公约，写全量会让全局改主题时漏改。第三，path 是全端统一的路由标识，跳转 API、TabBar 配置、分包配置引用的都是它，不包含 .vue 后缀、不以斜杠开头（跳转时 url 参数则习惯写以斜杠开头的完整路径，两处写法要分清）。

窗口表现：一套配置三种命运

globalStyle 里的字段在三端的落地程度不同，评审时要有这张心理对照表。导航栏标题与背景色三端一致；navigationStyle: custom 三端一致地"拆掉"原生导航栏，但拆掉之后的顶部安全区要自己补（4.4 节专讲）；enablePullDownRefresh 三端一致，但下拉的交互样式各端长相不同；onReachBottomDistance 的触底阈值在 H5 端以页面滚动为准、在小程序端以配置为准，做无限列表时两端都测。表现类配置还要注意 App 端独有的项（比如原生导航栏按钮、侧滑返回开关）写在条件编译的配置块里，别让它污染其他端的产物——pages.json 本身支持条件编译，这把钥匙在 1.2 节已经发给你了。

命名公约：path 是会过期的资产

项目过半后 pages.json 会变成最拥挤的文件，path 的命名质量决定半年后的可维护性。商城团队吃过亏：早期随手起的 pages/a1、pages/new-goods，半年后没人说得出哪个是有效页面。后来的公约值得抄：目录按业务域分（goods、order、user），页面名用功能名（detail、list、submit），path 一律两级；废弃页面先从 pages 数组摘除再删文件，顺序反了会出现"文件没了还配置着"的幽灵路由。另一个实战细节是 H5 端的路由模式——manifest 里 router.mode 选 history 还是 hash，决定线上部署要不要配服务端回退；商城选 history 配合 nginx 的回退规则，分享链接才不带井号。

⚠️ pages.json 是编译期文件：改动它之后必须重新编译，热刷新有时不会完整应用路由变更。联调时"改了 TabBar 不生效"多半不是写错，而是产物没重编。

页面登记的三个高频问答

把评审与答疑里出现最多的三个问题记录在此。问：pages 数组顺序必须固定吗？答：只有第一项（启动页）有语义，其余顺序影响产物里的排列，建议按业务域排序保持可读，别依赖顺序传递逻辑。问：一个页面文件能在 pages 数组登记两次吗？答：path 重复会在编译期报错，需要"同一界面两种入口"时复制页面文件或用参数区分，不要绕过校验。问：pages.json 能拆分管理吗？答：原生不支持 import 拆分，页面数上百的工程用脚本在构建前合并各业务域的分片文件，产物仍是一份完整 json——脚本合并发生在编译前，条件编译的分端逻辑不受影响。

从动线需求反推登记结构的练习

用一个综合需求把登记知识落成动手能力。需求：商城要加"新人礼包"流程，三个页面——引导页、选择礼包页、领取成功页，只在活动期间开放，入口在首页弹窗。动手前先过登记三问。问入口：引导页从首页弹窗进，用 navigateTo 压栈，登记进主包还是分包？活动页低频偏重，进分包。问顺序：领取成功后不允许回选择页，跳转安排是选择页提交后 redirectTo 成功页（登记结构不受影响，但登记时就把三页归进同一分包，动线才顺）。问窗口：引导页要沉浸头图，页面级 style 开 navigationStyle custom，全局配置不动。三问答完，登记代码的形状自然浮现——先想动线与包归属，再写 json，是这个顺序而非相反。

一个反例：登记表失控的样子

补一个反面样本加深印象。某项目一年后 pages 数组膨胀到六十多项：业务域混杂、同名 path 出现 list、list2、listNew 三代并存、三个长期废弃页面还挂在数组里。后果不只是难看——新人找页面靠猜、H5 端路由表冗长、主包体积里躺着死页面。治理动作用了一下午：全量梳理访问日志确认死页面、摘除登记再删文件、按业务域重排并统一两级命名。之后再没失控，靠的是本章的公约加一条新规：每次迭代评审带上"页面增删清单"。登记表是工程的名片，它的秩序程度几乎就是项目秩序程度。## 本节要点回顾

• 页面登记是路由的前提，数组首位是启动页，页面级 style 只写差异项；
• path 是全端统一的路由标识，命名按业务域两级公约，废弃页面先摘配置再删文件；
• 窗口表现三端落地程度不同，App 专属项用条件编译圈进对应产物；
• H5 路由模式在 manifest 里定，history 模式需要服务端回退规则配合；
• pages.json 是编译期文件，路由类改动以重新编译为准。

登记完毕，下一节让页面真正动起来：四种跳转 API 的栈语义与传参的正确姿势。