路由系统

app.json 的 pages 和 subPackages 声明可访问页面；tabBar.list 声明 Tab 页面。非 Tab 页面按页面栈管理，最多保留 10 层。路由参数、页面间通信、返回刷新与转场能力都属于路由系统。

跳转方式

API	页面栈变化	目标页面	参数
wx.navigateTo	保留当前页并压栈	非 Tab 页面	URL 参数、EventChannel
wx.redirectTo	替换当前页	非 Tab 页面	URL 参数
wx.reLaunch	清空全部页面	任意页面	URL 参数
wx.switchTab	关闭全部非 Tab 页面	Tab 页面	不支持 URL 参数
wx.navigateBack	出栈返回	已在页面栈中的页面	不传参数

详情页、表单页等临时页面使用 navigateTo；完成后不应返回的流程使用 redirectTo；登录态失效、切换业务根页面等场景使用 reLaunch；切换底部 Tab 使用 switchTab。不要用 navigateTo 打开 Tab 页面，也不要为绕过栈深限制反复跳转。

wx.navigateTo({
  url: `/pages/detail/index?id=${encodeURIComponent(id)}&from=list`,
})

wx.navigateBack({
  delta: 1,
})

路由参数

URL 参数适合传递 ID、筛选条件等可序列化且长度较小的初始化数据。目标页在 onLoad 读取并校验；对象不要直接拼入 URL，令牌、手机号、订单金额等敏感或关键数据不能信任 URL。

Page({
  onLoad(options) {
    const id = decodeURIComponent(options.id || '')
    if (!id) return

    this.setData({ id, from: options.from })
  },
})

switchTab 不支持 URL 参数。切换 Tab 后需要传递上下文时，使用短生命周期的共享状态或持久化标记，并由目标页自行读取和校验。

EventChannel 页面通信

wx.navigateTo 的 events 用于声明打开方接收的事件；success 回调中的 eventChannel 可向新页面发送初始化数据。新页面通过 getOpenerEventChannel() 获得同一通道，并用 emit、on、once、off 通信和管理监听。

// pages/list/index.js
wx.navigateTo({
  url: '/pages/editor/index',
  events: {
    saved(data) {
      // 合并 data 或按需刷新列表
    },
  },
  success(res) {
    res.eventChannel.emit('init', { draftId: 'draft-1' })
  },
})

// pages/editor/index.js
Page({
  onLoad() {
    this.getOpenerEventChannel().on('init', ({ draftId }) => {
      this.setData({ draftId })
    })
  },
  save() {
    this.getOpenerEventChannel().emit('saved', {
      id: this.data.draftId,
      updated: true,
    })
    wx.navigateBack()
  },
})

EventChannel 仅关联这一次 navigateTo，适合编辑、选择等相邻页面的双向通信；事件名使用业务语义，页面卸载后不再保留异步回调。跨多个页面、需要长期保存的登录态、购物车等数据使用应用级状态或持久化存储，恢复后仍需重新校验。

返回与刷新

从详情页或编辑页返回时，优先通过 EventChannel 返回变更结果并增量更新。无法确定是否有变更时，在列表页的 onShow 按标记刷新；避免每次回到前台都无条件请求接口。

不要通过 getCurrentPages() 查找页面后直接修改其 data 或调用其业务方法。页面栈会随跳转、返回和重启变化，这种依赖也无法覆盖 Tab 切换。

路由重写

wx.rewriteRoute 用于重写正在进行中的路由事件，可改写目标路径或保留原路由参数。适合统一处理路由拦截、目标页替换等框架级需求，不是常规页面跳转 API。基础库 3.8.0 起支持，且不支持 Promise 调用；低版本使用 redirectTo 降级。

wx.onBeforeAppRoute((res) => {
  if (res.path !== '/pages/legacy/index') return

  wx.rewriteRoute({
    url: '/pages/home/index',
  })
})

只能在 wx.onBeforeAppRoute 回调中同步调用，每个路由事件只能重写一次。重写不改变事件类型：switchTab 仍只能指向 Tab 页面，navigateBack 不能重写；目标路径还应符合当前分包限制。

Skyline 自定义路由

wx.router 用于注册和读取自定义路由上下文。它仅适用于连续的 Skyline 页面，可实现半屏、缩放、手势返回等转场；普通 WebView 页面继续使用默认转场。基础库 2.29.2 起支持。

const routeBuilder = () => ({
  opaque: false,
  transitionDuration: 300,
})

wx.router.addRouteBuilder('customRoute', routeBuilder)

wx.navigateTo({
  url: '/pages/sheet/index',
  routeType: 'customRoute',
})

同一 routeType 不再使用时通过 wx.router.removeRouteBuilder 移除；页面或组件可用 wx.router.getRouteContext(this) 读取路由动画上下文。自定义转场涉及 Worklet、手势和前后页面联动，应先确认 Skyline 覆盖范围与低版本体验。