Jetpack Compose类型安全导航：如何设置嵌套NavGraph起始目标？

核心问题原因 #

你遇到的IllegalStateException是因为根NavGraph无法直接访问嵌套导航（HomeGraph）内部的子目的地。根导航仅能识别直接挂载在它下的节点：RouteA和HomeGraph这个嵌套导航容器，而RouteC是HomeGraph的子节点，根导航无法直接定位到它，因此直接将RouteC设为根导航的startDestination会报错。

解决方案 #

方案1：修改嵌套导航的起始目标，根导航指向嵌套容器

如果需求是启动应用时直接进入HomeGraph下的RouteC，最直接的方式是调整嵌套导航的startDestination，再让根导航指向该嵌套容器：

private fun NavGraphBuilder.addNavGraph(navController: NavController) {
    composable<RouteA> {
        RouteAScreen(navController)
    }

    // 将HomeGraph的起始目标改为RouteC
    navigation<HomeGraph>(
        startDestination = RouteC
    ) {
        composable<RouteB> {
            RouteBScreen(navController)
        }

        composable<RouteC>(
            deepLinks = listOf(
                navDeepLink<RouteC>(basePath = "$uri/routeC")
            )
        ) {
            RouteCScreen(navController)
        }

        // 修正笔误：RouteD的deepLink应匹配自身路由
        composable<RouteD>(
            deepLinks = listOf(
                navDeepLink<RouteD>(basePath = "$uri/routeD")
            )
        ) {
            RouteDScreen(navController)
        }
    }
}

然后在NavHost中设置根导航的起始目标为HomeGraph：

@Preview
@Composable
fun NavCreateTest() {
    val navController = rememberNavController()

    Column {
        NavHost(
            modifier = Modifier.fillMaxSize(),
            navController = navController,
            startDestination = HomeGraph // 根导航指向嵌套容器
        ) {
            addNavGraph(navController)
        }
    }
}

方案2：动态条件跳转至嵌套内的目的地

如果需要根据DeepLink等条件动态切换起始目标到RouteC，不能直接将RouteC设为根导航的startDestination，而是要在初始化时通过navController的导航方法完成跳转：

@Composable
fun NavCreateTest() {
    val navController = rememberNavController()
    val context = LocalContext.current
    val intent = (context as? MainActivity)?.intent
    val deeplinkUri = intent?.data
    val isDeeplink = deeplinkUri != null

    // 初始化时根据条件执行导航
    LaunchedEffect(isDeeplink) {
        if (isDeeplink) {
            // 跳转至RouteC并清空返回栈，确保作为起始页面
            navController.navigate(RouteC) {
                popUpTo(navController.graph.id) { inclusive = true }
            }
        } else {
            navController.navigate(RouteA) {
                popUpTo(navController.graph.id) { inclusive = true }
            }
        }
    }

    Column {
        NavHost(
            modifier = Modifier.fillMaxSize(),
            navController = navController,
            startDestination = RouteA // 设一个默认的顶级起始目标
        ) {
            addNavGraph(navController)
        }
    }
}

修复DeepLink不生效问题 #

1. 修正代码笔误：你代码中RouteD的deepLink错误使用了navDeepLink<RouteC>，应改为navDeepLink<RouteD>，否则无法正确识别RouteD的DeepLink。
2. 配置Manifest文件：确保在MainActivity的AndroidManifest.xml中添加DeepLink的intent-filter，系统才能正确拦截并跳转：

<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <!-- 添加DeepLink拦截规则 -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="test"
            android:host="www.example.com" />
    </intent-filter>
</activity>

关键知识点总结 #

• 嵌套导航的子目的地不能直接作为根NavGraph的startDestination，根导航仅识别直接挂载的顶级目的地或嵌套导航容器。
• 若要启动时进入嵌套内的目的地，要么修改嵌套导航的startDestination并让根导航指向该容器；要么在初始化时通过navController.navigate完成跳转。
• 类型安全导航中，跨层级跳转内部目的地时，Compose Navigation会自动处理层级路径，无需手动拼接字符串路由。

内容的提问来源于stack exchange，提问作者Thracian