VersionCatalog 必须定义在 settings.gradle.kts 中，位于 dependencyResolutionManagement 块内，不可置于 build.gradle.kts；默认目录名为 libs，对应 gradle/libs.versions.toml 文件，引用时需用完整 leaf node 路径（如 libs.okhttp.logging），且须确保 TOML 格式规范、路径正确、Gradle 版本 ≥7.4。
VersionCatalog 必须定义在 settings.gradle.kts 里
Gradle 的版本目录（versionCatalogs）不是 build 脚本的一部分，它属于构建初始化阶段的全局策略配置。如果你把它写在某个 build.gradle.kts 里，Gradle 直接忽略——不会报错，但其他模块也根本读不到。正确位置只有 settings.gradle.kts，且必须放在 dependencyResolutionManagement 块内。
常见错误现象：Cannot access 'libs' in version catalog 或 IDE 里 libs 不提示、跳转失败。
- 确保
settings.gradle.kts中已启用 Kotlin DSL（即文件名是.kts，不是.gradle） -
dependencyResolutionManagement必须在pluginManagement之后、include之前 - 目录名默认是
libs，不可改；想用别的名字需显式声明alias("xxx")，但不推荐
子模块通过 libs.xxx 语法引用，不写版本号
一旦版本目录生效，所有子模块的 build.gradle.kts 就可以直接用 libs.xxx 引用依赖，完全不用手写版本号或坐标字符串。Gradle 会在解析时自动补全。
使用场景：比如你在 libs.versions.toml 里写了 [versions.kotlin] = "1.9.24" 和 [libraries.kotlin-stdlib] = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }，那么任意子模块里写 implementation(libs.kotlin.stdlib) 就够了。
- 路径层级对应 TOML 里的嵌套结构：
libs.okhttp.logging→[libraries.okhttp.logging] - 不能用
libs.okhttp这种中间段直接当依赖，必须到 leaf node（如.logging） - 如果用了
alias，引用时仍用 alias 名，不是原始 module 名
libs 无法识别？检查 TOML 文件路径和格式
Gradle 默认只认 gradle/libs.versions.toml 这个固定路径。放错位置（比如放在根 buildSrc 下、或叫 versions.toml）会导致整个目录加载失败，但不会报错，只会静默失效。
容易踩的坑：
- TOML 文件里不能有注释行以
#开头且后面带空格（某些 Gradle 版本会 parse 失败） - 版本号字符串必须加引号，如
"1.6.0"，写成1.6.0会被当成浮点数解析出错 - 别在
libs.versions.toml里写 Groovy 风格的=赋值，必须用 TOML 标准语法（key = value） - Android Studio 同步后，
libs提示没出来？先执行./gradlew --stop清掉 daemon，再重新 sync
多模块下如何让 common 模块暴露公共依赖给 consumer？
版本目录本身不解决“模块间依赖传递”，它只管“统一声明”。如果你希望 common 模块把 libs.retrofit.core 作为 API 透出，让 app 模块直接用而不用重复声明，就得配合 Gradle 的依赖传递机制。
关键点：
-
common的build.gradle.kts里用api(libs.retrofit.core)，不是implementation -
app模块声明implementation(project(":common"))即可间接获得 Retrofit 类型，无需再写libs.retrofit.core - 注意：这种传递只对 compile classpath 生效；运行时依赖仍由各自模块的
runtimeClasspath决定 - 如果
common还要封装 CDKTF 的 Provider（如前文terraform-cdk示例），记得用api暴露libs.cdktf.core，否则 consumer 编译会找不到类型
真正麻烦的不是配置本身，而是团队协作时有人绕过 libs 直接写死版本号——这会让版本目录形同虚设。建议在 CI 里加一条检查：扫描所有 build.gradle.kts 是否出现 "[0-9]+\.[0-9]+\.[0-9]+" 这类硬编码版本号模式。
