必须显式暴露kotlin-stdlib依赖、生成Java友好API签名、禁用Kotlin元数据干扰，否则Java引用时会报NoClassDefFoundError或NoSuchMethodError。
能发布，但必须显式暴露 Kotlin 运行时依赖、生成 Java 友好的 API 签名，并禁用默认的 Kotlin 元数据干扰。 否则 Java 项目引用后会报 NoClassDefFoundError 或调用失败（比如找不到 getXXX$default 方法）。
Java 调用 Kotlin 库前必须处理的三个关键点
Kotlin 编译后的字节码本身可被 Java 直接加载，但默认行为会引入三类兼容性障碍：
-
kotlin-stdlib不会自动传递给下游 Java 项目 —— 必须声明为api或implementation并确保 POM 正确导出 - Kotlin 的空安全、默认参数、扩展函数等特性会生成桥接方法或元数据（
$annotations、$default），Java 编译器不识别这些符号 - Gradle 默认不为 Kotlin 源码生成
-java-parameters，导致 Java 反射获取不到参数名，影响框架（如 Spring）注入
build.gradle.kts 中必须配置的几项
在库模块的 build.gradle.kts 中，仅启用 java-library 和 maven-publish 插件是不够的，还需以下硬性设置：
- 添加
org.jetbrains.kotlin:kotlin-stdlib-jdk8（或jdk11）作为api依赖，而非implementation，否则 Java 项目 compile 时找不到KotlinNothing等基础类型 - 在
kotlin块中启用jvmToolchain(11)并设置javaParameters = true，保证javac -parameters效果等效 - 使用
@JvmStatic、@JvmOverloads、@JvmName显式修饰顶层函数、伴生对象方法和重载函数，避免生成不可见的合成方法 - 在
publishing块中，确保from(components["java"])被调用 —— 它会自动包含sourcesJar和javadocJar，但需额外确认pom.withXml没有意外移除kotlin-stdlib的 dependency 声明
验证 Java 调用是否真正可用
别只看 Gradle publish 成功就认为完事。最直接的验证方式是：新建一个纯 Java Gradle 项目，在 dependencies 中添加你刚发布的坐标，然后写一段调用代码：
立即学习“Java免费学习笔记（深入）”；
public class JavaUser {
public static void main(String[] args) {
// 假设你的 Kotlin 类叫 StringUtilsKt，有顶层函数 formatName
String result = StringUtilsKt.formatName("Alice", "Smith");
System.out.println(result); // 如果这里编译失败或运行时报 NoSuchMethodError，说明上面某步漏了
}
}
常见失败信号包括：
-
error: cannot find symbol——kotlin-stdlib未导出或版本不匹配 -
java.lang.NoSuchMethodError: StringUtilsKt.formatName$default—— 没加@JvmOverloads或未启用allOpen插件处理内联类 -
NullPointerException在 Kotlin 函数内部抛出，但 Java 层没收到非空断言 —— 这是预期行为，但需在文档里明确标注哪些参数不能为null
最容易被忽略的是：Kotlin 编译器默认生成的 Metadata 注解和 CompiledBy 类属性，虽不影响运行，但某些老旧的 Java 扫描工具（如旧版 ArchUnit 或 Jacoco）会因无法解析它们而静默失败。如需彻底“隐身”，可在 kotlinOptions 中加 freeCompilerArgs += "-Xno-call-assertions" 和 "-Xno-param-assertions"，但代价是失去空安全的运行时保护。
