Navigation State 驱动的页面调试方法论

@toc

如果你在 RN 项目里遇到问题时，经常是这样一种状态：

• 页面行为不稳定
• Bug 偶现，复现成本极高
• 多个开发同时改导航，互相踩
• 最终只能靠"经验 + 试错"

那基本可以确定一件事：

项目已经超过"靠直觉调试"的规模了。

这时候，你需要的不是更多 log，而是一套确定性的调试入口 。

在 RN 项目里，这个入口就是：Navigation State。

一、先统一一个共识：页面问题，本质是状态问题

我们先把一个非常关键的认知统一掉：

页面异常 ≠ 页面写错了
页面异常 = 当前导航状态不符合你的预期模型

比如：

• 返回错位
• 页面重复 mount
• Modal 关闭后逻辑还在
• Tab 切换状态丢失

这些都不是"页面 bug"，而是：

导航状态已经偏离设计模型，但你还在按 UI 去理解它。

二、方法论的核心：先定义"正确状态"，再看"当前状态"

Navigation State 调试的第一步，不是打印，而是：

你得知道"对的状态长什么样"。

举个非常具体的例子

业务预期是：

Tab(Home)
 └─ Stack
    ├─ List
    └─ Detail

那你期望看到的 state，至少应该满足：

• Tab 下是 Stack
• Stack index 指向 Detail
• Detail 是 active route

如果你打印出来发现：

Tab
 ├─ Home
 ├─ Detail

那就已经不对了。

调试不是对错判断，是模型对齐。

三、方法论第一步：给 Navigation State 建"视图"

在任何中大型 RN 项目里，我都会做一件事：

把 Navigation State 变成"随时可见"的东西。

基础实现（可直接用）

export function dumpNavState(ref) {
  const state = ref.getRootState()
  console.log(JSON.stringify(state, null, 2))
}

在开发环境：

if (__DEV__) {
  global.dumpNav = () => dumpNavState(navigationRef)
}

这一步的意义是：

• 不依赖断点
• 不依赖页面上下文
• 随时能看"真实世界"

四、第二步：把问题"翻译"成状态问题

很多人描述问题时是这样的：

"从 A 页面点到 B，再点返回就不对了"

这种描述对调试毫无帮助。

正确的翻译方式应该是：

"当前 Navigation State 里，B 不在我预期的 Stack 层级"

这是一个可验证的判断。

一个真实的翻译过程

原始描述：

"Modal 关了，但逻辑还在跑"

状态翻译：

"Modal route 已被 pop，但副作用仍然存活"

接下来你就知道该查哪里了：

• 页面是否真的 unmount
• 副作用是否绑定在 focus 上
• 是否用了错误的 navigator 层级

五、第三步：用 State 切割"问题归因"

这是这套方法论里最重要的一步。

你要学会问三个问题：

1. 这个页面是否真的在 State 里？

const state = navigationRef.getRootState()

如果 route 不在 state 中：

• 页面逻辑还在跑 → 副作用没清理
• 页面 UI 还在 → 没用正确的 navigator

2. 这个页面是不是 active？

index: 2
routes: [A, B, C]

如果 index 指向的不是你以为的页面：

• 返回异常是必然的
• focus / blur 行为一定错

3. 这个页面属于哪一层？

这是最容易忽略，但杀伤力最大的一个问题。

• Root？
• Flow？
• Section？
• Page？

层级一旦错，所有行为都会错。

六、一个完整调试案例（真实工程向）

问题现象

• 从列表进入详情
• 打开编辑 Modal
• 保存并关闭
• 按返回，直接回首页

状态检查

dumpNav()

输出（简化）：

{
  "routes": [
    { "name": "MainTabs" },
    { "name": "EditModal" }
  ]
}

问题立刻暴露：

• EditModal 挂在 Root
• Detail 不在 Root Stack
• 返回自然会 pop 到 Tabs

正确模型应该是

MainTabs
 └─ HomeStack
    ├─ List
    ├─ Detail
    └─ EditModal

此时，问题不需要再"修返回"，

而是：

重新调整 Modal 所属层级

七、第四步：建立"状态断言"，防止回归

这是高手和普通工程师的分水岭。

示例：页面是否非法进入 Root

const state = navigationRef.getRootState()

const hasIllegalRoute = state.routes.some(
  r => r.name === 'Detail'
)

if (hasIllegalRoute) {
  reportError('Detail should not be in Root')
}

你可以把这种逻辑：

• 放在开发环境
• 放在 CI
• 放在关键发布版本

八、用 Navigation State 驱动"工程规范"

当你真正用 State 调试后，你会自然形成这些规范：

1. 所有导航问题，先看 state
2. PR 中修改导航，必须附 state 变化说明
3. 新页面必须声明所属层级
4. 禁止页面直接 navigate Root 级页面

这些规范不是人为约束，而是：

被状态事实倒逼出来的。

九、这套方法论真正解决了什么？

• 不再靠"感觉"调试导航
• 不再怕项目复杂
• 不再怕新人改导航
• 不再出现"玄学返回"

你会发现：

当 Navigation State 成为第一观察对象时，复杂度是可控的。

最后一句总结

调试的本质不是找 bug，而是对齐"运行时状态"与"设计模型"。

在 RN 项目里：

• UI 会骗人
• 经验会过期
• 但 Navigation State 不会

当你真正把它当成调试入口，

你就已经站在了工程化 RN 的门内。