第2章环境搭建与依赖配置

课程目录第2章环境搭建与依赖配置

2、环境搭建与依赖配置：在build.gradle中引入Navigation依赖，配置Safe Args插件

好，咱们正式开始动手了。这一章其实特别关键——环境搭好了，后面写代码才顺。我见过不少新手，代码写了一半发现版本冲突，或者Safe Args死活不生成代码，回头一查，原来是依赖没配对。嗯，咱们今天就把这事一次搞定。

2.1 整体思路：我们要配什么？

说白了，Navigation组件要跑起来，你需要做三件事：

引入核心依赖——Navigation Fragment和Navigation UI
配置Safe Args插件——它帮你生成类型安全的跳转代码
检查版本兼容性——别让Kotlin版本和Navigation版本打架

我个人习惯先把版本号抽出来，放在一个统一的地方管理。这样以后升级，改一个地方就行，不用满项目翻。

2.2 第一步：在根项目的 build.gradle 中声明版本

我习惯在根项目的 build.gradle（或者 build.gradle.kts）里，用 ext 或者 buildscript 块把版本号统一管理起来。你想想看，如果以后 Navigation 升级了，你只需要改这一个地方，多省心。

// 根项目 build.gradle
buildscript {
    ext {
        nav_version = "2.7.7"
        kotlin_version = "1.9.22"
    }
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

💡 我的小建议： 如果你用的是 Kotlin DSL（.kts 文件），语法略有不同，但逻辑完全一样。我个人更推荐用 Groovy 写根项目配置，因为社区示例多，遇到问题好搜。

2.3 第二步：在模块的 build.gradle 中应用插件和添加依赖

这一步很多人会漏掉——光在根项目声明了插件还不够，你必须在 app 模块里应用它。我曾经帮一个学员排查问题，他折腾了两小时，Safe Args 就是不生成代码，最后发现是忘了在 app 的 build.gradle 里加 apply plugin。

// app/build.gradle
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'androidx.navigation.safeargs.kotlin'  // 就是这行！
}

android {
    // ... 你的 android 配置
}

dependencies {
    // Navigation 核心依赖
    implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
    implementation "androidx.navigation:navigation-ui-ktx:$nav_version"
    
    // 可选：如果你要用动态特性模块
    // implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"
}

⚠ 注意： 插件名称是 androidx.navigation.safeargs.kotlin，不是 safeargs 也不是 safe-args。写错了 Gradle 不会报错，但就是不生成代码——我当年就被这个坑过。

2.4 第三步：版本兼容性速查

为什么我要单独列一张表？因为版本不兼容是环境搭建中最隐蔽的问题。Gradle 同步可能成功，但运行时会报 NoSuchMethodError 或者 ClassNotFoundException。嗯，这里我直接给你整理好了，照着配就行。

Navigation 版本	最低 Kotlin 版本	最低 AGP 版本	备注
2.5.x	1.7.0	7.2.0	较老，但稳定
2.6.x	1.8.0	7.4.0	支持类型安全参数
2.7.x	1.9.0	8.1.0	推荐，最新稳定版

我的推荐组合（2024年）：

Navigation 2.7.7
Kotlin 1.9.22
AGP 8.2.2

这个组合我目前在两个生产项目里跑着，没出过兼容性问题。

2.5 第四步：验证配置是否成功

配完了怎么知道对不对？别急着写代码，先做两件事：

执行一次 Gradle Sync——看有没有红色报错。
创建一个最简单的 NavGraph——在 res/navigation 目录下新建一个 nav_graph.xml，随便加两个 Fragment 的 destination。然后 Clean + Rebuild 项目。

如果 Safe Args 配置正确，你会在 build/generated/source/navigation-args 目录下看到自动生成的 FragmentDirections 类。看到了？那就稳了。

💡 一个小技巧： 如果你用的是 Android Studio，可以在 build 目录上右键 → "Show in Explorer"，直接定位到生成目录。我第一次看到自动生成的代码时，说实话还挺兴奋的——终于不用手写 Bundle 和 arguments 了。

2.6 避坑指南：我踩过的三个坑

坑一：插件版本和依赖版本不一致。 我曾经把 Safe Args 插件写成 2.7.7，但依赖写成 2.6.0，结果编译通过，运行时崩溃。记住：插件和依赖的版本号必须完全一致。
坑二：忘了在 app 模块应用插件。 这个前面说过了，但值得再强调一次——根项目声明了不等于 app 模块能直接用。
坑三：Kotlin 版本太老。 如果你还在用 Kotlin 1.6.x，Navigation 2.7.x 是跑不起来的。升级 Kotlin 时注意同时升级 AGP，不然又会有新的兼容问题。

好，环境搭建就到这里。配置好之后，下一章我们就可以真正开始写 Navigation 的代码了——从创建 NavGraph 到 Fragment 之间的跳转，我会带你一步步走通。

📚 课程目录

2、环境搭建与依赖配置：在build.gradle中引入Navigation依赖，配置Safe Args插件

2.1 整体思路：我们要配什么？

2.2 第一步：在根项目的 build.gradle 中声明版本

2.3 第二步：在模块的 build.gradle 中应用插件和添加依赖

2.4 第三步：版本兼容性速查

2.5 第四步：验证配置是否成功

2.6 避坑指南：我踩过的三个坑