年初，我们将拥有超过 1000 个页面的 Android 应用从 Navigation 2 迁移到了 Navigation 3。

Navigation 3 引入了类型安全的目标位置、持久化的返回栈还有更现代化的导航 API。虽然整体迁移相对顺利，但我们仍然遭遇了不少意想不到的挑战——包括底部表单处理、发布后才出现的崩溃还有大量合并冲突导致的**加班**和**紧急修复**。

Navigation 3 的使用体验

迁移前的情况

我们的应用开发于 2021 年。导航基础基于 Jetpack Compose Navigation，当时该方案仍相对新颖且未完全稳定。

• 遗留代码
• 导航 函数
• 为弥补标准库不足而编写的自定义方法

底部表单也是基于当时的导航框架实现的。Navigation 3 的出现彻底重新定义了我们的导航方式。

我们为何决定迁移

在权衡技术债务与未来机遇后我们把这次迁移视为对网站的一项长期投资，而非简单升级库。

• 产品路线图：平板电脑和折叠屏设备需要自适应布局和多窗格支持，而旧导航实现无法满足这些需求。
• 维护成本：导航堆栈被大量 功能和自定义逻辑淹没，每新增一个功能都明显提高维护难度。

我们清楚迁移会带来风险、影响范围广还有潜在回归问题。但推迟只会让技术债务进一步累积，未来迁移成本更高。

说服了我们

1. Compose‑first 方法：整个 UI 与导航已基于 Compose 建立。其实，
2. MVI 与状态驱动导航：Nav3 将导航堆栈视为普通状态。与我们的 MVI 架构天然契合。

val navigationState = rememberNavigationState( startKey = MainScreenPointScreen,topLevelKeys = setOf ) val navigator = remember { Navigator }

• 自适应布局：支持平板和 Pixel Fold 等大屏设备。
• Google 要求：Google 正在推动大屏适配，Play 商店也将优先考虑支持大屏幕的应用。

2024 年 1 月

N 3 稳定版发布后我立刻在下个冲刺创建了调研任务，以评估可行性、受影响区域及风险。至于结果显示，增量迁移不可行——只能一次性搬完所有页面否则会产生兼容性灾难。

随后我被指派专门进行两周的大型“迁移冲刺”。所有页面手动重写为 Nav 3 API。按理说，尝试使用 AI自动转换，但因旧代码高度定制化。AI 常常产生不一致甚至错误的 Nav 2 代码。最终，我独自完成了全部工作，用时约两周——期间每日加班。但团队仍在并行开发新功能，这导致大量合并冲突。说起来，

加班——为什么？

Pain Point: 大规模重构必然伴随合并冲突。 我们决定在迁移期间不冻结业务开发，以免影响业务收入。只是当我手动重写每个页面时同事们仍在旧导航上提交新功能。结果是冲突频发，解决冲突所耗时间远超预期。

意外的问题

底部表单实现缺失

N 3 并未提供直接通过导航显示底部表单的方案。我不得不自行包装 ,在 metadata 中标记为底部工作表。并使用 ModalBottomSheetLayout 渲染：

val NavEntry.isBottomSheet: Boolean
get = metadata as?Boolean == true
inline fun  EntryProviderScope.bottomSheetEntry(
noinline content: @Composable -> Unit,) {
entry(
metadata = mapOf。content = content
)
}
NavDisplay(
entries = navigationState.toEntries
.filter { it.isBottomSheet.not },onBack = { navigator.goBack },)

This was a temporary workaround;later we replaced it with official “SceneStrategy” solution.

深层链接重构

The migration gave us an opportunity to clean up deep‑link handling.

之前：

composable(
deepLinks = "$uri/${ScreenName.PROFILE.value}/?$PROFILE_ID={$PROFILE_ID}"
"&$EVENT_CONTEXT={$EVENT_CONTEXT}"
"&$EVENT_ANCHOR={$EVENT_ANCHOR}"
"&$ENTRY_POINT={$ENTRY_POINT}"
"&$STREAM_ID={$STREAM_ID}",route = profileRoute,arguments = profileArguments,) { ProfilePreview }

之后：

@Serializable
data class ProfilePreviewPointScreen(
override val deepLinkPath: String = "${ScreenName.PROFILE.value}"
) : NavKey。DeepLinkableEntry) {
entry -> ProfilePreview
}

This centralized approach dramatically simplified maintenance and debugging.

稳定化阶段

The regression test suite and bug‑fix effort consumed roughly one and a half weeks. Automated tests uncovered many hard‑to‑reproduce issues that would have orwise slipped into production.

发布与紧急修复

The rollout began with a small % of users via Crashlytics monitoring. Crashes appeared almost immediately.

后退导航导致崩溃

N 3 要求所有通过导航传递的参数必须可序列化。我们在阻塞使用者场景中传递了一个自定义 NavKey,导致 Kotlinx.serialization.SerializationException.

data class BlockUserRoute
@Serializable
open class NavStateSerializable : NavKey
// Hotfix applied → second release succeeded

积极主动是好事。但并不总是如此A month after release Google introduced Claude Code support for Nav 3 migrations. Using it on pre‑migration branch saved roughly one week of work—essentially doubling our migration speed. However,custom extensions and legacy code still required manual handling and extensive verification.

The built‑in Bottom Sheet solution via “SceneStrategy” replaced our ad‑hoc wrapper,making codebase far cleaner.

结论与经验教训

底部表单…说起来，提醒

• The bottom sheet lives inside navigation stack. If you navigate from a bottom sheet to anor screen without explicitly closing it。pressing back on new screen will reveal sheet again.
• This subtle behavior is easy to forget,especially for new team members. Consider encapsulating close‑logic in a reusable extension.

何时不建议迁移？其实，

• 基于 Fragment 的架构：If you still rely heavily on Fragments,you must first refactor m away—a high‑risk undertaking.
• E​紧迫期限：A tight deadline makes large‑scale regressions costly for business.
• S​专有导航方法：If your custom navigation is stable and well‑tested。migration may not yield enough ROI.
• L​游戏项目：If your app is a game that locks orientation,Google allows exceptions;migrating might be unnecessary.
\endul

优点

• 多窗格 UI ： 自适应布局变得轻松，只需为特定页面指定相应 “sceneStrategy”。
• 可预测的导航 ： 堆栈透明度提高，调试更直观。
• 深层链接统一管理 ： 重构后维护成本显著下降。
\

成功评估标准：

• 发布后无严重崩溃；所有后退/返回流程稳定，* 新页面集成速度提高约30%。* 自适应布局无需额外 就可以。* 导航堆栈调试时间显著缩短。\

---