Compose Destinations V2 导航图生成问题解析与解决方案

问题背景

在 Compose Destinations 库从 V1 升级到 V2 的过程中，开发者遇到了导航图生成异常的问题。具体表现为在 V1 版本中正常工作的多层级导航结构（包括 LoginNavGraph 和 AppNavGraph 等）在 V2 版本中无法正确生成。

问题现象

在 V1 版本中，项目能够正确生成包含多个层级导航图的结构，包括：

• 根导航图
• 登录导航图(LoginNavGraph)
• 应用导航图(AppNavGraph)
• 以及其他不属于这两个导航图的目的地

但在迁移到 V2 后，生成的导航图结构出现了异常，无法正确识别和生成预期的导航层级。

迁移变化

从 V1 到 V2 的注解语法发生了显著变化：

V1 版本语法：

@RootNavGraph(start = true)
@NavGraph
annotation class LoginNavGraph(
  val start: Boolean = false
)

@RootNavGraph
@NavGraph
annotation class AppNavGraph(
  val start: Boolean = false
)

@AppNavGraph
@Destination
@Composable()

V2 版本语法：

@NavGraph<RootGraph>(start = true)
annotation class LoginNavGraph

@NavGraph<RootGraph>
annotation class AppNavGraph

@Destination<AppNavGraph>
@Composable

问题根源

经过分析，发现问题的根本原因在于 V2 版本中缺少必要的 @NavHostGraph 注解定义。在 V2 架构中，需要一个明确的顶级导航宿主图来作为整个导航结构的容器。

临时解决方案

在等待官方修复的同时，开发者可以采用以下临时解决方案：

1. 定义一个主导航图注解：

@NavHostGraph
annotation class MainNavGraph

2. 修改现有导航图定义，使其基于主导航图：

@NavGraph<MainNavGraph>(start = true)
annotation class LoginNavGraph

@NavGraph<MainNavGraph>
annotation class AppNavGraph

3. 在 Activity 中使用时，引用 NavGraphs.main 而非原来的根图。

后续优化

官方在后续版本中会修复这个问题，届时开发者可以恢复使用 RootGraph 而无需定义额外的 MainGraph。同时，官方也会改进错误提示机制，在类似配置缺失时提供更明确的错误信息，而非静默失败。

相关扩展问题

在测试过程中还发现了共享元素过渡(Shared Element Transition)功能的一个相关问题：AnimatedVisibilityScope 参数未能自动注入。这个问题已在 2.1.0-beta03 版本中得到修复，开发者只需升级依赖即可解决。

迁移建议

对于计划从 V1 迁移到 V2 的开发者，建议：

1. 仔细检查所有导航图注解的转换是否正确
2. 确保每个导航图都明确指定了 start 属性
3. 暂时采用 MainGraph 作为替代方案
4. 关注官方更新，及时调整回 RootGraph
5. 测试所有导航功能，特别是带有特殊参数（如共享元素过渡）的界面

通过遵循这些建议，开发者可以更顺利地完成从 V1 到 V2 的迁移过程。