Android Gradle复合构建报错：Unresolved reference: libs

1. 检查libs.version.toml文件位置 #

• 这个文件必须放在根项目的gradle目录下（路径为 <root>/gradle/libs.version.toml），不能放到build-logic或其他子模块里。如果位置不对，直接移到根目录的gradle文件夹即可。

2. 根项目settings.gradle.kts需启用版本目录 #

• 确认根项目的settings文件里有以下配置，确保Gradle能识别libs目录：

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.version.toml"))
        }
    }
}

• 注：Gradle 7.4以下版本需额外加上enableFeaturePreview("VERSION_CATALOGS")。

3. build-logic模块需关联根版本目录 #

• 由于build-logic是复合构建的独立模块，得在它的settings.gradle.kts里显式引入根项目的libs文件：

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("../gradle/libs.version.toml"))
        }
    }
}

• 路径要根据build-logic的实际位置调整，保证能找到根目录的libs.version.toml。

4. 子模块引用格式需匹配libs.toml条目 #

• 比如在app或convention模块的build.gradle.kts里，引用方式要和libs.version.toml里的条目对应：
  • toml文件里的写法：

  [versions]
  androidxCoreKtx = "1.12.0"
  
  [libraries]
  androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "androidxCoreKtx" }
  

  • 模块里的引用写法：

  implementation(libs.androidx.core.ktx)
  

• 注意命名规则：toml里的androidx-core-ktx会被Gradle转为libs.androidx.core.ktx的引用格式。

5. 清理Gradle缓存后重试 #

• 执行命令清理缓存并重新构建：

./gradlew clean build --refresh-dependencies

• 也可以手动删除根目录下的.gradle文件夹，再重新同步项目。

内容的提问来源于stack exchange，提问作者bobby I.