在开始 Compose 导航路由 之前，必须正确搭建 Navigation 依赖环境。本章手把手带你完成 build.gradle 配置、依赖注入、项目同步以及环境验证，确保后续页面跳转零障碍。

📋 搭建四步走

1. 添加 Navigation Compose 依赖 — 在模块级 build.gradle 中引入库。
2. 配置 build.gradle — 确保 Kotlin 与 Compose 编译器版本兼容。
3. 同步项目 — 使用 Gradle Sync 或直接运行。
4. 验证环境 — 通过简单代码确认 Navigation 可用。

📦 核心依赖一览

依赖名称	作用	典型版本 (2025+)
androidx.navigation:navigation-compose	Compose 导航核心库	2.8.5
androidx.compose.ui:ui	Compose UI 基础	1.7.6
androidx.activity:activity-compose	Activity 集成 Compose	1.9.3
org.jetbrains.kotlin:kotlin-stdlib	Kotlin 标准库	2.0.21

⚙️ 配置 build.gradle (模块级)

打开 app/build.gradle.kts (或 .groovy)，在 dependencies 块内添加以下内容：

// build.gradle.kts (模块级)
dependencies {
    // Compose BOM (统一管理版本)
    implementation(platform("androidx.compose:compose-bom:2025.02.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")

    // Navigation Compose
    implementation("androidx.navigation:navigation-compose:2.8.5")

    // Activity Compose
    implementation("androidx.activity:activity-compose:1.9.3")

    // Kotlin 标准库 (通常自动包含)
    implementation("org.jetbrains.kotlin:kotlin-stdlib:2.0.21")
}

如果使用 Groovy (build.gradle)，格式类似：

// build.gradle (Groovy)
dependencies {
    implementation platform('androidx.compose:compose-bom:2025.02.00')
    implementation 'androidx.compose.ui:ui'
    implementation 'androidx.compose.material3:material3'
    implementation 'androidx.navigation:navigation-compose:2.8.5'
    implementation 'androidx.activity:activity-compose:1.9.3'
}

🧩 依赖架构示意

🔄 同步项目

修改完 build.gradle 后，点击 Android Studio 右上角的 “Sync Now” (大象图标) 或使用快捷键 Ctrl+Shift+O (Windows/Linux) / Cmd+Shift+O (macOS)。等待 Gradle 同步完成，底部 Build 窗口显示 “BUILD SUCCESSFUL”。

• ✅ 如果出现版本冲突，检查 BOM 版本与 Navigation 版本是否匹配。
• ✅ 建议使用 compose-bom 统一管理 Compose 相关库版本。
• ✅ 确认 Kotlin 插件版本 ≥ 2.0.0 以支持 Compose 编译器插件。

🧪 验证环境

创建一个最简单的 NavHost 来验证 Navigation 是否生效。在 MainActivity.kt 中写入：

// MainActivity.kt
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MyAppTheme {
                val navController = rememberNavController()
                NavHost(navController = navController, startDestination = "home") {
                    composable("home") {
                        Text("✅ Navigation 环境正常！", fontSize = 24.sp)
                    }
                }
            }
        }
    }
}

运行项目，如果屏幕显示 “✅ Navigation 环境正常！”，说明环境搭建成功。

🛠️ 常见问题 & 解决

问题	原因	解决方案
Unresolved reference: NavHost	缺少 navigation-compose 依赖	检查依赖是否添加并同步
Compose 版本不兼容	BOM 与 Kotlin 插件版本冲突	使用最新 BOM + Kotlin 2.0+ 编译器插件
Gradle 同步失败	网络或仓库未配置	确保 google() 和 mavenCentral() 在 settings.gradle