Gradle同步找不到androidx.navigation.safeargs.kotlin插件

常见触发原因 #

• 插件classpath声明位置错误：androidx.navigation:navigation-safe-args-gradle-plugin的classpath依赖必须配置在项目根目录build.gradle的buildscript.dependencies块下，写在app模块的dependencies块里不会被Gradle识别为插件来源。
• 插件声明缺版本号：如果没有提前配置插件版本映射规则，直接在app模块plugins块写插件id不指定版本，Gradle会因为无法定位具体版本抛出解析失败错误。
• 仓库源缺失：Safe Args是Google官方发布的AndroidX组件，必须在插件解析对应的仓库列表里添加google()源，仅配置mavenCentral、gradlePluginPortal会拉取不到该插件。
• 插件id拼写错误：Kotlin对应的Safe Args插件id固定为androidx.navigation.safeargs.kotlin，不要和Java版本的androidx.navigation.safeargs混淆，也不要出现拼写错漏。
• 版本不兼容：Safe Args版本需要和项目的AGP、Kotlin版本匹配，比如2.7.x系列Navigation要求AGP版本≥7.4、Kotlin版本≥1.8，版本差过大也会导致插件加载失败。

正确配置参考 #

1. 项目根目录 build.gradle #

buildscript {
    ext {
        // 定义全局Navigation版本，插件、运行时依赖必须用同一个版本号
        nav_version = "2.7.7"
    }
    repositories {
        google() // 必须放在仓库列表靠前位置，保证优先拉取
        mavenCentral()
    }
    dependencies {
        // 仅在这里声明Safe Args插件的classpath，不要在app模块重复加
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

// 新版项目如果根目录有plugins块，不要在这里声明safeargs插件

2. 项目级 settings.gradle #

pluginManagement {
    repositories {
        google() // 必须配置，否则plugins块声明的插件无法解析
        mavenCentral()
        gradlePluginPortal()
    }
}
// 其余原有include等配置保持不变即可

3. app模块 build.gradle #

plugins {
    id "com.android.application"
    id "org.jetbrains.kotlin.android"
    // 两种声明方式二选一
    // 方式一：直接指定版本，版本号和全局nav_version完全一致
    id "androidx.navigation.safeargs.kotlin" version "2.7.7"
    // 方式二：已经在根目录buildscript配置好classpath的话，直接声明id即可
    // id "androidx.navigation.safeargs.kotlin"
}

dependencies {
    // Navigation运行时依赖版本必须和插件版本完全一致
    implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
    implementation "androidx.navigation:navigation-ui-ktx:$nav_version"
}

配置修改完成后如果同步仍然失败，先执行./gradlew clean命令清理构建缓存，再通过Android Studio的File -> Invalidate Caches选项重启IDE，排除旧缓存的干扰。

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