将应用迁移到Navigation 3：痛点、加班和紧急修复

本文译自「Migrating App to Navigation 3: Pain, Overtimes, and Hotfixes」，原文链接https://medium.com/proandroiddev/migrating-app-to-navigation-3-pain-overtimes-and-hotfixes-88321b59314b，由Tetiana Synytsyna发布于2026年6月30日。

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

Navigation 3 引入了类型安全的目标位置、持久化的返回栈以及更现代化的导航 API。虽然整个迁移过程相对顺利，但我们仍然遇到了一些意想不到的挑战——从处理底部面板到修复发布后才出现的崩溃问题。

在本文中，我将分享我们决定迁移的原因、迁移过程、遇到的问题以及从中汲取的经验教训。

如果你正计划迁移到 Navigation 3，本文的经验或许能帮你节省一些时间，并避免一些麻烦。

Navigation 2 的使用体验

我们开始权衡技术债务与未来机遇，最终决定进行迁移。对我们而言，这不仅仅是“更新一个库”。

我们将此次迁移视为对平台的一项投资。

首先，我们的产品路线图已经涵盖平板电脑和折叠屏设备，而现有的导航实现与自适应布局和多窗格场景并不兼容。

其次，导航堆栈逐渐被扩展功能和自定义逻辑所淹没。虽然它能够运行，但导航层中每个后续功能的维护成本都越来越高。

我们明白迁移意味着风险、影响范围广以及潜在的回归问题。然而，推迟迁移只会增加技术债务，并使未来的迁移成本更高。

是什么说服了我们

2025 年 11 月

我看到 Nav3 的稳定版本已发布，作为一名积极主动的开发人员，受到新导航方法的启发，我为下一个冲刺创建了一个调查任务。

调查的目标很简单：评估迁移的可行性、受影响的区域、风险，并了解它对于我们应用程序的规模是否现实。很快，人们就清楚了：这并不容易。

我立即发现了主要风险——增量迁移是不可能的。由于 Nav2 和 Nav3 之间缺乏向后兼容性，只有一次性迁移所有页面才能进行转换。部分迁移不是一种选择。

调查结束后，领导和我评估了风险、潜在的回归以及未来几个季度的路线图。由于已经规划了自适应布局，因此迁移获得了批准。

2026 年 2 月

在下一个冲刺计划中，我被分配了一个专门的迁移冲刺，并且在整个持续时间（漫长而有趣且充满痛苦的两周）中，我专门从事导航工作。迁移完全是手动完成的。

是的，我尝试过使用人工智能。但事实证明，对于遗留下来的代码库来说，迁移过于复杂。由于扩展功能、自定义导航解决方案和重要的依赖关系，Claude Code 有时会为我们的特定旧设置提供不一致的结果。它不会迁移到 Nav3，而是返回 Nav2 代码并写入：“迁移成功完成，该项目现在可以在最新的稳定版本的导航上运行”。但我们稍后会回到这一点。

迁移到 Nav3 花了我漫长的两周时间，而且每天都加班。免责声明：不，公司没有强迫我。是的，他们会给我尽可能多的时间。是的，没有人让我写这个😄。

有趣的事实：Gemini 和 Claude Code 估计整个迁移过程需要团队花费 6 至 8 周的时间。最终我一个人用了两周时间完成了。

加班。为什么？

底页

在计划迁移时，我错过了一个关键细节 - 底页。 Nav3 没有现成的解决方案来通过导航显示底部表单。我必须围绕 entry<> 编写自己的、不太优雅的包装器，在 metadata 中传递信息，指示它是底部工作表，如果为真，则通过 ModalBottomSheetLayout （材料 3）而不是 NavDisplay 显示此页面。

val NavEntry<out NavKey>.isBottomSheet: Boolean
    get() = metadata["isBottomSheet"] as? Boolean == true
inline fun <reified T : NavKey> EntryProviderScope<NavKey>.bottomSheetEntry(
    noinline content: @Composable (T) -> Unit,
) {
    entry<T>(
        metadata = mapOf("isBottomSheet" to true),
        content = content
    )
}
NavDisplay(
    entries = navigationState.toEntries(mainEntryProvider)
        .filter { it.isBottomSheet.not() },
    onBack = { navigator.goBack() },
)

这不是一个理想的解决方案——更多的是一个让我们能够继续前进的临时解决方案。如今，通过“SceneStrategy”存在更好的方法，我们后来替换了这个实现。

深层链接

完整的回归测试、稳定性和错误修复花费了大约一周半的时间。老实说，我以为我们会发现错误并再稳定一个月（只是不要告诉我的领导）。借助自动化测试，我们发现了大量很难手动重现的问题，但用户肯定会留下有关这些问题的评论。

发布

还记得我提到过我手动迁移了所有内容吗？尝试过人工智能，但失败了。好吧，在我们发布一个半月后，Google 专门针对 Nav3 迁移推出了 Claude Code 技能。

我很好奇克劳德·科德会对我有多大帮助。我切换回迁移前分支并尝试使用 Claude Code 进行迁移。我可以自信地说，这可以节省我一周的工作时间。这意味着迁移速度会快两倍。是的，扩展和遗留代码仍然需要手动迁移，并且在 Claude Code 之后验证更改会花费大量时间，但不可否认的是，Claude Code 会优化我所做的大量单调的手动工作。

此外，Google 已经为 Bottom Sheets 提供了内置解决方案 - 特别是通过“SceneStrategy”。我们已经用“BottomSheetSceneStrategy”替换了自定义解决方法。这种方法要方便得多。

你可以在此处找到“BottomSheetSceneStrategy”的完整代码。

因此，如果我没有急于迁移并等待几个月，那么由于 Claude Code 和 Bottom Sheets 的现成解决方案，迁移会更容易一些，并且开发速度会快两倍。不过，我认为稳定和修复错误所需的时间不会有太大变化。

结论和经验教训

我强烈建议在以下情况下权衡转向 Nav3 的必要性：

基于片段的架构： 在迁移之前，你必须完全摆脱片段。这可能意味着具有高风险的大规模重构。
紧迫的期限： 即使你已经使用 Compose 导航，迁移也会造成巨大的受影响区域，并且由于回归可能会给业务带来高昂的成本。
专有导航解决方案： 如果你的自定义解决方案已经稳定运行，则迁移可能是不合理的。
游戏： 如果你的应用程序是游戏并且你严格依赖屏幕方向（在本例中主要是横向），Google 允许例外以保持方向固定。

优点

整个迁移过程大致可以总结为：

团队： 1 名活跃且尚未精疲力竭的开发人员
开发时间： 2 周
解决合并冲突： 1 天
受影响区域： 302 个文件，或者简单地说 — 整个应用程序
测试和稳定： ~1.5 周
修补程序： 1

至关重要的是，我们通过几个实际标准评估了迁移的成功：

发布后导航流程的稳定性（崩溃和与导航相关的回归）。
将新页面集成到新导航框架的速度。
能够无缝构建自适应布局，无需额外的解决方法。
调试导航堆栈（是否变得更容易重现场景）。

迁移后，最明显的变化出现在日常开发中：

新页面更容易连接导航，无需额外的扩展功能。
导航堆栈更可预测且更易于调试。
很大一部分遗留逻辑就这样消失了。
Nav3 事实证明更接近于状态驱动的方法，并且自适应布局不再感觉像一个巨大的独立项目。

但如果你还计划迁移，请分配更多时间来保持稳定，不要低估底部工作表，并仔细检查导航中的序列化设置。

希望我的经验可以帮助你避免我的错误，让你的迁移更快、更少痛苦！

祝撸码快乐！ 😃

稀有猿诉

十年磨一剑，历炼出锋芒，说话千百句，不如码二行。

将应用迁移到Navigation 3：痛点、加班和紧急修复

2025 年 11 月

2026 年 2 月

底页

Comments