Kotlin项目中IntelliJ报Unresolved reference但Gradle构建成功问题排查

我有一个Java库skycavelib，希望在Kotlin项目中使用。以下是引入该库作为依赖的项目build.gradle配置（Kotlin DSL）：

import java.util.Properties
import java.io.FileInputStream

plugins {
    kotlin("jvm") version "1.7.10"
}

group = "de.skycave"
version = "1.0.0"

val localProperties = Properties()
localProperties.load(FileInputStream(rootProject.file("local.properties")))

repositories {
    mavenCentral()
    maven { url = uri("https://repo.papermc.io/repository/maven-public/") }
    maven { url = uri("https://jitpack.io") }
    maven {
        url = uri("https://maven.pkg.github.com/skycavemc/skycavelib")
        credentials {
            username = localProperties.getProperty("gpr.user")
            password = localProperties.getProperty("gpr.key")
        }
    }
}

dependencies {
    implementation(kotlin("stdlib"))
    compileOnly("io.papermc.paper:paper-api:1.19.2-R0.1-SNAPSHOT")
    implementation("de.skycave:skycavelib:1.0.2")
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(17))
}

已确保项目中存在local.properties文件且配置正确，认证正常，库已下载并在IntelliJ的「External Libraries」中可见。但尝试使用库中的类时，IntelliJ自动补全能提示正确导入，导入后却在导入语句和使用行提示「Unresolved reference」。不过Gradle构建仍能成功完成，且仅在Kotlin类中出现此问题，Java类中引用正常。其他Java库（如paper-api）在Kotlin和Java文件中均能正常导入，清理缓存、重载Gradle项目也无法解决问题，怀疑是skycavelib的配置有误，以下是该库的build.gradle配置（Groovy DSL）：

plugins {
    id 'java'
    id 'org.jetbrains.kotlin.jvm' version '1.7.10'
    id 'com.github.johnrengelman.shadow' version '7.1.2'
    id 'maven-publish'
}

group = 'de.skycave'
version = '1.0.2'

def localProperties = new Properties()
localProperties.load(new FileInputStream(rootProject.file("local.properties")))

repositories {
    mavenCentral()
    maven {
        name = 'papermc-repo'
        url = 'https://repo.papermc.io/repository/maven-public/'
    }
    maven {
        name = 'sonatype'
        url = 'https://oss.sonatype.org/content/groups/public/'
    }
    maven {
        name = 'jitpack'
        url = 'https://jitpack.io'
    }
}

dependencies {
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.7.10'
    compileOnly 'io.papermc.paper:paper-api:1.19.2-R0.1-SNAPSHOT'
    implementation 'org.mongodb:mongodb-driver-sync:4.7.1'
    implementation 'com.google.code.gson:gson:2.9.1'
    implementation group: 'org.apache.commons', name: 'commons-lang3', version: '3.12.0'
    implementation group: 'commons-io', name: 'commons-io', version: '2.11.0'
    implementation 'com.github.heuerleon:mcguiapi:v1.3.5'
}

def targetJavaVersion = 17
java {
    def javaVersion = JavaVersion.toVersion(targetJavaVersion)
    sourceCompatibility = javaVersion
    targetCompatibility = javaVersion
    if (JavaVersion.current() < javaVersion) {
        toolchain.languageVersion = JavaLanguageVersion.of(targetJavaVersion)
    }
    manifest {
        attributes 'Main-Class': "de.skycave.skycavelib.SkyCaveLib"
    }
}

tasks.withType(JavaCompile).configureEach {
    if (targetJavaVersion >= 10 || JavaVersion.current().isJava10Compatible()) {
        //noinspection GroovyAssignabilityCheck, GroovyAccessibility
        options.release = targetJavaVersion
    }
}

processResources {
    def props = [version: version]
    inputs.properties props
    filteringCharset 'UTF-8'
    filesMatching('plugin.yml') {
        expand props
    }
}

build {
    dependsOn(shadowJar)
}

shadowJar {
    archiveFileName.set("${project.name}-${project.version}.jar")
}

publishing {
    repositories {
        maven {
            name = "GitHubPackages"
            url = "https://maven.pkg.github.com/skycavemc/skycavelib"
            credentials {
                username = localProperties.getProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
                password = localProperties.getProperty("gpr.token") ?: System.getenv("ACCESS_TOKEN")
            }
        }
    }
    publications {
        library(MavenPublication) {
            from components.java
        }
    }
}

核心问题出在skycavelib的Maven发布配置上：你的库引入了Kotlin插件，但发布时使用components.java作为构件来源，这只会打包Java相关产物，缺少Kotlin元数据文件（.kotlin_module）。Gradle构建能通过是因为它会直接处理完整的jar包，但IntelliJ的Kotlin插件需要元数据才能正确识别库中的类，从而导致IDE解析失败。

修复步骤： #

1. 修改skycavelib的publishing配置，将components.java替换为components.kotlin，确保包含Kotlin元数据：

publishing {
    repositories {
        // 保持原仓库配置不变
    }
    publications {
        library(MavenPublication) {
            from components.kotlin // 替换此处
        }
    }
}

2. 重新发布库到GitHub Packages，建议先清理本地的旧版本缓存（可删除~/.m2/repository/de/skycave/skycavelib目录）。
3. 在依赖项目中重载Gradle项目，IntelliJ即可正确解析Kotlin类中的引用。

补充说明： #

paper-api能正常工作是因为它是纯Java库，不需要Kotlin元数据；而你的skycavelib依赖了Kotlin标准库，必须提供Kotlin元数据才能让IDE的Kotlin插件正确识别类结构。

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