Gradle多模块项目：libs.versions.toml依赖无法在子项目生效求助

问题原因 #

报错Extension with name 'libs' does not exist是因为子项目无法识别版本目录（libs.versions.toml）对应的libs扩展，核心是版本目录未正确加载到子项目的依赖解析上下文中。

解决方案 #

1. 明确声明版本目录加载配置 #

在项目根目录的settings.gradle.kts（Groovy环境为settings.gradle）中添加依赖解析管理配置，确保libs.versions.toml被所有子项目识别：

Kotlin DSL（settings.gradle.kts）

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

rootProject.name = "your-project-name"
// 子项目声明...

Groovy（settings.gradle）

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
    versionCatalogs {
        libs {
            from files('gradle/libs.versions.toml')
        }
    }
}

rootProject.name = 'your-project-name'
// 子项目声明...

2. 优化根项目构建脚本（可选，符合现代Gradle规范） #

将buildscript块中的Shadow插件配置迁移到plugins块，避免旧版类路径配置的潜在冲突：

plugins {
    `kotlin-dsl`
    // 预加载Shadow插件，供子项目按需应用
    id("com.github.johnrengelman.shadow") version "7.1.2" apply false
}

group = "xxx"
version = "0.0.1-SNAPSHOT"
java.sourceCompatibility = JavaVersion.VERSION_19

subprojects {
    apply(plugin = "java")
    apply(plugin = "checkstyle")
    apply(plugin = "maven-publish")
    apply(plugin = "com.github.johnrengelman.shadow")

    repositories {
        mavenCentral()
    }

    dependencies {
        api(libs.jsr305)
        testImplementation(libs.bundles.junit)

        compileOnly(libs.lombok)
        annotationProcessor(libs.lombok)

        testCompileOnly(libs.lombok)
        testAnnotationProcessor(libs.lombok)
    }

    java {
        withSourcesJar()
    }

    tasks.named<Test>("test") {
        useJUnitPlatform()
    }

    tasks.withType<JavaCompile> {
        options.encoding = "UTF-8"
    }

    tasks.withType<Javadoc> {
        options.encoding = "UTF-8"
    }
}

3. 验证文件位置 #

确保libs.versions.toml放置在项目根目录的gradle/文件夹下，这是Gradle默认识别的路径，示例项目结构：

your-project/
├── gradle/
│   └── libs.versions.toml
├── settings.gradle.kts
├── build.gradle.kts
└── subprojects/
    └── ...

原理说明 #

Gradle的版本目录功能需要在settings阶段通过dependencyResolutionManagement加载，才能让所有子项目共享libs扩展。手动声明加载逻辑可以避免自动加载失效的情况，确保子项目初始化时能正确识别该扩展。

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