解密 KMP 多模块构建死锁：Gradle 叶子节点名称 (Leaf Name) 冲突的避坑指南

1. 问题背景：看似合理的模块拆分

在 Kotlin Multiplatform (KMP) 项目架构中，按业务层级与功能模块分类拆分工程是常见做法。例如：

• :provider:media（数据提供层：媒体数据模块）
• :scenario:media（业务场景层：媒体场景模块）

物理磁盘目录结构十分简洁干净：

├── provider/
│   └── media/
└── scenario/
    └── media/

然而，当 :scenario:media 依赖 :provider:media 并触发编译时，构建工具却抛出了死锁与循环依赖（Circular Dependency）：

:scenario:media:allMetadataJar -> 等待元数据编译 -> 引用同名模块 -> 回到 allMetadataJar

2. 深度剖析：Task 命名空间与叶子节点冲突

表面上，Gradle 项目的完整路径（Project Path）分别是 :provider:media 与 :scenario:media，逻辑路径彼此隔离。

但问题的根源在于 Kotlin Gradle Plugin (KGP) 处理跨平台 commonMain 元数据（Metadata）的机制：

1. Metadata Variant Resolution（元数据变体解析）：KMP 在构建 allMetadataJar 等跨平台元数据任务时，KGP 内部的 Task 生成和 Artifact 匹配逻辑过度依赖项目的叶子节点名称（Leaf Name）——即 project.name（均为 media）。
2. 符号与属性混淆：当 :scenario:media 尝试解析被依赖项的 commonMain KLIB 时，KGP 的元数据解析器在查找标识为 media 的产物时，误将当前正在构建的模块自己识别为了目标模块。
3. 构建循环与挂起：模块开始等待“自己”编译完成，从而陷入死锁。

3. 常见方案与架构权衡

针对这个问题，业界常见的解决思路各有优劣：

4. 最佳实践：轻量级声明式 DSL 映射

兼顾物理目录干净、Gradle Task 空间隔离以及 Gradle 9+ / Kotlin 2.4+ 工程隔离（Project Isolation） 的最佳实践，是在 settings.gradle.kts 中编写轻量级的 DSL 映射函数。

核心代码

在 settings.gradle.kts 中添加以下辅助函数：

// settings.gradle.kts

rootProject.name = "your-kmp-project"

/**
 * 声明式引入模块：解耦逻辑 Project 名称与物理磁盘路径
 * 示例：includeModule("provider:media")
 * - 逻辑路径：:provider-media (规避 KGP Leaf Name 冲突)
 * - 物理路径：provider/media (保持磁盘目录简洁)
 */
fun includeModule(path: String) {
    val logicalName = ":" + path.replace(":", "-")
    val physicalPath = path.replace(":", "/")

    include(logicalName)
    project(logicalName).projectDir = file(physicalPath)
}

// =============================================================
// 模块注册：显式受控，无“一刀切”风险，支持任意深层嵌套
// =============================================================
includeModule("provider:media")
includeModule("scenario:media")
includeModule("provider:video:decoder") // 支持深层嵌套：映射为 :provider-video-decoder

5. 改造后的模块依赖写法

映射完成后，子模块内部的 build.gradle.kts 引用方式也随之变得优雅：

// scenario/media/build.gradle.kts

kotlin {
    sourceSets {
        commonMain.dependencies {
            // 推荐：使用 Gradle 自动生成的 Type-Safe Project Accessor
            // 连字符 "-" 会自动转为 CamelCase（驼峰命名）
            implementation(projects.providerMedia)

            // 或传统字符串路径写法：
            // implementation(project(":provider-media"))
        }
    }
}

6. 方案优势总结

1. 解耦物理与逻辑标识：物理上保持 provider/media 的整洁分类，逻辑上通过 :provider-media 给 KGP 提供了全局唯一的 project.name，彻底消除 Task 命名空间死锁。
2. 声明式且受控：没有动态文件系统扫描（I/O）的模糊性，显式声明每一个模块，完全兼容 Gradle Configuration Cache。
3. Type-Safe Project Accessors 友好：自动推导出干净的 projects.providerMedia 强类型访问器，IDE 自动补全体验极佳。