微信小程序自定义 tabBar 的 switchTab 静默失败陷阱

小程序里用自定义 tabBar（app.json 里 "custom": true）做底部导航是常见做法。代码写完，在开发者工具里点 tab 切换，控制台突然冒出一行红字：

switchTab:fail can not switch to no-tabBar page

诡异的是，目标页面就在 tabBar.list 里，路径一字不差，pages 数组里也有——逻辑上根本不存在「不是 tabBar 页」的理由。

现象

• 自定义 tabBar 组件点击后调用 wx.switchTab，报 can not switch to no-tabBar page
• 目标页路径与 tabBar.list 完全匹配，无拼写错误
• 开发者工具必现，真机预览可能正常（环境差异加剧迷惑性）
• 换成 wx.navigateTo 或 wx.redirectTo 直觉上可以绕路，但这两个 API 无法跳转到 tabBar 页，会遇到另一个报错

根因

开启 custom: true 后，微信框架仍然在内部维护一份 tabBar 页面注册表，并非把路由完全交给开发者。注册表的初始化依赖以下几个条件同时满足：

1. 首次进入 tabBar 页时必须用 switchTab。如果启动页（如 splash 或登录页）通过 wx.redirectTo 跳到第一个 tab 页，框架会丢失 tabBar 上下文，注册表无法激活。

2. custom-tab-bar 目录必须存在且组件不能为空壳。框架用这个组件的存在性来判断是否进入 custom 模式，组件太过精简时（只有空 Component({})）可能触发初始化异常。

3. DevTools 特定版本存在 bug。真机上框架完整运行，注册表正常初始化；DevTools 的精简运行时在上述两点叠加时更容易失败。

正解

修法一：switchTab + reLaunch 兜底（推荐）

在自定义 tabBar 组件的跳转方法里，给 switchTab 加 fail 回调，用 reLaunch 兜底：

goPage(e) {
  const path = e.currentTarget.dataset.path;
  wx.switchTab({
    url: '/' + path,
    fail() {
      // custom tabBar 模式下 switchTab 可能失败，reLaunch 兜底
      wx.reLaunch({ url: '/' + path });
    }
  });
},

reLaunch 会清空整个页面栈再跳转，对 tab 级顶层导航来说副作用可以接受。注意 fail 回调里不要写 console.error——这个失败在某些 DevTools 版本里是预期行为，日志噪声会干扰排查其他问题。

修法二：启动时改用 switchTab（消除根因）

在 splash/登录页的跳转逻辑里，把 redirectTo 换成 switchTab：

// pages/splash/index.js — 跳到第一个 tabBar 页
wx.switchTab({ url: '/pages/home/index' })   // ✅ 建立 tabBar 上下文
// wx.redirectTo({ url: '/pages/home/index' })  // ❌ 丢失 tabBar 上下文

这是从根源修复，修法一的兜底逻辑可以保留作双保险。

一句话外卖

custom: true 只改变了 tabBar 的渲染层，框架内部的 tabBar 页面注册逻辑依然存在——首次进入 tab 页必须经过 switchTab，否则注册表不激活，后续所有 switchTab 都会当面撒谎说「这不是 tabBar 页」。