Kotlin Multiplatform发布Maven时Dokka文档与源码不生效问题

问题现象 #

• 项目为Kotlin Multiplatform项目，当前使用mavenLocal做发布测试
• 执行publishToMavenLocal后，其他多平台项目可正常引入依赖、调用代码，但IDE无法显示对应代码文档，源码反编译/解析表现异常，判定为源码未正确关联
• 已配置Dokka插件生成javadoc.jar，本地.m2仓库中可见包含内容的javadoc.jar，但引入依赖后快速文档查看、源码解析功能仍失效
• 按照官方文档说明添加maven-publish与Dokka插件后，未实现预期的自动配置效果

现有问题配置 #

plugins {
    kotlin("multiplatform") version "1.6.21"
    id("org.jetbrains.kotlinx.benchmark") version "0.4.2"
    id("org.jetbrains.dokka") version "1.6.21"
    `maven-publish`
    signing
}

group = "io.github.quillraven.fleks"
version = "1.4-KMP-SNAPSHOT"
java.sourceCompatibility = JavaVersion.VERSION_1_8

repositories {
    mavenCentral()
}

kotlin {
    targets {
        jvm {
            compilations {
                all {
                    kotlinOptions {
                        jvmTarget = "1.8"
                    }
                }
                val main by getting { }
                // custom benchmark compilation
                val benchmarks by compilations.creating {
                    defaultSourceSet {
                        dependencies {
                            // Compile against the main compilation's compile classpath and outputs:
                            implementation(main.compileDependencyFiles + main.output.classesDirs)
                        }
                    }
                }
            }
            withJava()
            testRuns["test"].executionTask.configure {
                useJUnitPlatform()
            }
        }
    }
    js(BOTH) {
        browser { }
    }
    val hostOs = System.getProperty("os.name")
    val isMingwX64 = hostOs.startsWith("Windows")
    val nativeTarget = when {
        hostOs == "Mac OS X" -> macosX64("native")
        hostOs == "Linux" -> linuxX64("native")
        isMingwX64 -> mingwX64("native")
        else -> throw GradleException("Host OS is not supported in Kotlin/Native.")
    }

    sourceSets {
        val commonMain by getting { }
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test"))
            }
        }
        val jvmMain by getting
        val jvmTest by getting
        val jvmBenchmarks by getting {
            dependsOn(commonMain)
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-benchmark-runtime:0.4.2")
                implementation("com.badlogicgames.ashley:ashley:1.7.4")
                implementation("net.onedaybeard.artemis:artemis-odb:2.3.0")
            }
        }
        val jsMain by getting
        val jsTest by getting
        val nativeMain by getting
        val nativeTest by getting
    }
}

benchmark {
    targets {
        register("jvmBenchmarks")
    }
}

val javadocJar by tasks.registering(Jar::class) {
    archiveClassifier.set("javadoc")
    from(tasks.dokkaHtml)
}

publishing {
    repositories {
        maven {
            url = if (project.version.toString().endsWith("SNAPSHOT")) {
                uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
            } else {
                uri("https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/")
            }

            credentials {
                username = System.getenv("OSSRH_USERNAME")
                password = System.getenv("OSSRH_TOKEN")
            }
        }
    }

    publications {
        val kotlinMultiplatform by getting(MavenPublication::class) {
            version = project.version.toString()
            groupId = project.group.toString()
            artifactId = "Fleks"
            artifact(javadocJar)

            pom {
                name.set("Fleks")
                description.set("A lightweight entity component system written in Kotlin.")
                url.set("https://github.com/Quillraven/Fleks")

                scm {
                    connection.set("scm:git:git@github.com:quillraven/fleks.git")
                    developerConnection.set("scm:git:git@github.com:quillraven/fleks.git")
                    url.set("https://github.com/quillraven/fleks/")
                }


                licenses {
                    license {
                        name.set("MIT License")
                        url.set("https://opensource.org/licenses/MIT")
                    }
                }

                developers {
                    developer {
                        id.set("Quillraven")
                        name.set("Simon Klausner")
                        email.set("quillraven@gmail.com")
                    }
                }
            }
        }

        signing {
            useInMemoryPgpKeys(System.getenv("SIGNING_KEY"), System.getenv("SIGNING_PASSWORD"))
            sign(kotlinMultiplatform)
        }
    }
}

// only sign if version is not a SNAPSHOT release.
// this makes it easier to publish to mavenLocal and test the packed version.
tasks.withType<Sign>().configureEach {
    onlyIf { !project.version.toString().endsWith("SNAPSHOT") }
}

本地仓库生成结构 #

IDE异常表现 #

问题根因 #

• 缺失核心的sources.jar源码构件：现有配置仅生成了javadoc包，没有打包源码，IDE无法关联源码自然无法正常解析代码、显示注释，反编译功能也会异常
• 构件绑定范围错误：仅给根级kotlinMultiplatform发布项绑定了javadoc包，KMP每个目标平台（JVM/JS/Native）都会生成独立的发布变体，IDE拉取平台依赖时会匹配对应变体的sources、javadoc构件，根级构件不会被平台变体识别
• Dokka任务类型使用错误：dokkaHtml任务输出的是独立HTML站点格式，不符合Maven Javadoc构件的标准格式，IDE无法解析该格式的文档包；Kotlin代码的快速文档IDE优先从sources包中的KDoc注释直接渲染，不需要依赖HTML格式输出。

修复方案 #

1. 删除原有单独定义的javadocJar任务，以及仅给kotlinMultiplatform发布项绑定javadoc包的逻辑
2. 在publishing配置块中，为所有类型为MavenPublication的发布项统一绑定源码包和标准Javadoc包，保证每个平台变体都能匹配到对应构件，配置代码如下：

publishing {
    // 原有repositories配置保持不变
    repositories {
        maven {
            url = if (project.version.toString().endsWith("SNAPSHOT")) {
                uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
            } else {
                uri("https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/")
            }

            credentials {
                username = System.getenv("OSSRH_USERNAME")
                password = System.getenv("OSSRH_TOKEN")
            }
        }
    }

    publications {
        // 统一为所有Maven发布项配置源码包、文档包
        withType<MavenPublication> {
            // 配置源码包
            val sourcesJar by tasks.registering(Jar::class) {
                archiveClassifier.set("sources")
                val sourceSet = when (name) {
                    "kotlinMultiplatform" -> kotlin.sourceSets.commonMain.get()
                    "jvm" -> kotlin.sourceSets.jvmMain.get()
                    "js" -> kotlin.sourceSets.jsMain.get()
                    "native" -> kotlin.sourceSets.nativeMain.get()
                    else -> null
                }
                sourceSet?.let { from(it.kotlin) }
            }
            artifact(sourcesJar)

            // 配置标准Javadoc包，使用dokkaJavadoc任务输出
            val javadocJar by tasks.registering(Jar::class) {
                archiveClassifier.set("javadoc")
                from(tasks.named<org.jetbrains.dokka.gradle.DokkaTask>("dokkaJavadoc"))
            }
            artifact(javadocJar)

            // 根发布项保留原有pom配置
            if (name == "kotlinMultiplatform") {
                version = project.version.toString()
                groupId = project.group.toString()
                artifactId = "Fleks"
                pom {
                    name.set("Fleks")
                    description.set("A lightweight entity component system written in Kotlin.")
                    url.set("https://github.com/Quillraven/Fleks")

                    scm {
                        connection.set("scm:git:git@github.com:quillraven/fleks.git")
                        developerConnection.set("scm:git:git@github.com:quillraven/fleks.git")
                        url.set("https://github.com/quillraven/fleks/")
                    }

                    licenses {
                        license {
                            name.set("MIT License")
                            url.set("https://opensource.org/licenses/MIT")
                        }
                    }

                    developers {
                        developer {
                            id.set("Quillraven")
                            name.set("Simon Klausner")
                            email.set("quillraven@gmail.com")
                        }
                    }
                }
            }
        }

        // 签名配置调整为对所有发布项签名
        signing {
            useInMemoryPgpKeys(System.getenv("SIGNING_KEY"), System.getenv("SIGNING_PASSWORD"))
            sign(publishing.publications)
        }
    }
}

3. 清理旧缓存后重新发布：先删除本地.m2仓库中对应库的旧版本目录，执行gradlew clean后再运行publishToMavenLocal，测试项目侧刷新Gradle依赖、清除IDE缓存后即可正常查看文档、关联源码。

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