🧭 uni-app 页面与路由

uni-app 页面路径以 pages.json 为唯一维护入口。页面文件、路由工具、装修链接都围绕 pages.json 中的 path、name、guest 管理，避免在多个常量列表重复维护路径。

📜 pages.json

页面登记在：

frontend/uniapp/src/pages.json

系统页面在 pages/system 下。多数页面使用：

{
  "style": {
    "navigationStyle": "custom"
  }
}

底部 tabBar 包含：

tab	pagePath
首页	pages/system/index/index
我的	pages/system/my/index

原生 tabBar 在运行时会被 MainTabBar 组件隐藏，取而代之的是自定义底部栏——这样可以自由定制样式和交互，不受原生 tabBar 限制。

🔢 页面路径工具

定义在：

frontend/uniapp/src/utils/page.ts

核心内容：

• 页面 name：在 pages.json 页面项中声明的稳定名称。
• resolvePage(nameOrPath)：根据页面 name 或页面路径解析出当前可跳转路径，供路由工具内部使用。
• isGuestPage()：根据页面项的 guest: true 判断是否允许游客访问。
• isTabBarPage()：根据 pages.json 的 tabBar 判断是否为 tab 页面。

业务代码跳转页面时可直接使用页面 name：

toRouter('home')

也可以传当前有效页面路径：

toRouter('/pages/system/article/detail?id=1')

页面登录规则由 pages.json 页面项决定。页面默认需要登录；只有声明 guest: true 的页面允许游客访问，路由工具会据此处理登录拦截。

示例：

{
  "path": "pages/system/index/index",
  "name": "home",
  "guest": true,
  "style": {
    "navigationStyle": "custom"
  }
}

可安装业务模块的页面不直接长期写入主工程，安装器根据模块资源清单合并 pages.json 的 subPackages。

🧑‍💻 路由工具

定义在：

frontend/uniapp/src/utils/router.ts

提供能力：

方法	说明
toRouter()	统一跳转，处理登录拦截、tabBar、外链、装修链接协议和跳转模式
backRouter()	统一后退，页面栈不足时跳转到兜底页面
getLoginUrl()	生成登录页并带 redirect

toRouter() 默认使用 navigateTo。目标页是 tabBar 页面时会优先使用 switchTab；非 tabBar 页面可通过 mode 指定 redirectTo 或 reLaunch：

toRouter('articleDetail?id=1')
toRouter('profile', { mode: 'redirectTo' })
toRouter('home', { mode: 'reLaunch' })

toRouter() 接受的参数格式：

格式	示例	说明
页面 name	'home'、'login'	从 pages.json 解析为路径
页面路径	'pages/system/my/login'	直接使用
外部 URL	'https://example.com'	自动包裹为 WebView 页跳转
装修链接协议	'article:detail:1'	见下方协议表

跳转前会自动执行登录守卫：如果目标页面未声明 guest: true，会先检查 Token；无 Token 时微信小程序尝试静默登录，失败则跳转登录页。

页面返回统一使用 backRouter()。当页面栈长度不足以返回时，会跳转到兜底页面，默认兜底页是 home：

backRouter()
backRouter({ delta: 2 })
backRouter({ fallback: 'userCenter' })

🧱 页面路径

"当前有效路径"指 pages.json 中实际注册的 path 值。装修数据和模块资源清单应直接使用这些路径，例如 /pages/system/article/list、/pages/system/public/agreement、/modules/{module}/pages/index。

业务代码跳转固定页面时直接使用 toRouter('页面 name')，由路由工具自动解析为当前有效路径，避免在多处硬编码路径字符串。

导入或迁移外部装修数据时，应先在数据层将旧路径映射为当前有效路径；前端路由层只处理当前有效路径。

🪢 装修链接协议

toRouter() 当前支持：

协议	行为
action:contact	触发联系客服弹层
http:// / https://	打开 WebView
article:list	打开文章列表
article:detail:{id}	打开文章详情
/pages/...	打开当前有效系统页面路径
/modules/{module}/pages/...	打开已安装模块的分包页面

✨ 新增模块页面规范

新增业务模块时：

src/modules/{module}

模块页面放在：

src/modules/{module}/pages

模块私有 API、组件、Store、类型和常量放在：

src/modules/{module}/apis
src/modules/{module}/components
src/modules/{module}/stores
src/modules/{module}/types

只有跨模块复用的接口、组件或类型才放到公共目录，例如：

src/apis/{module}
src/components/{domain}
src/types/{domain}.ts

pages.json 中可安装模块的分包 root 指向：

modules/{module}/pages

这样模块源码集中在 src/modules/{module}，而页面仍然进入 uni-app 分包。会被主包引用的模块 API、工具、类型不要放到 pages 分包目录内。

如果模块需要支持安装、卸载，源码应先放在模块资源包：

modules/{Module}/Resources/uniapp/src/modules/{module}

安装器会根据 Resources/publish-manifest.json 发布到 frontend/uniapp/src，并把 uniapp.subPackages 合并进 pages.json。未安装模块时，主工程不应包含该模块页面和模块私有代码。

🧰 框架通用工具

多个模块都会使用的格式化、列表归一化、图片处理和支付调起能力放在 src/utils，业务模块只保留自己的业务适配。

文件	能力
src/utils/format.ts	formatMoney()，统一金额显示
src/utils/list.ts	normalizeListResult()，统一接口列表结果
src/utils/media.ts	imageList()、firstImage()，统一提取图片字段
src/utils/payment.ts	getPayChannel()、requestPayment()，统一支付渠道判断和调起支付
src/utils/value.ts	isEnabledValue()，统一启用状态判断

模块私有工具只放模块自己的业务规则，例如模块主题色、模块装修链接兜底、模块字段适配等。