发布KMM库后typealias、inline functions及extension functions引用未解析问题求助

这问题我之前帮好几个KMM开发者排查过，核心原因基本都是符号可见性配置或Maven构件打包不全导致的——虽然代码存在，但Kotlin编译器找不到这些元素的public API声明。下面给你一步步的排查和解决思路：

1. 先检查KMM模块的可见性配置（最容易踩坑） #

Kotlin Multiplatform默认会把未显式声明可见性的符号设为internal，即使你在commonMain里写了代码，外部依赖时也访问不到。解决这个的关键步骤：

• 在你的KMM模块的build.gradle.kts里，启用explicitApi()强制显式声明可见性：

  kotlin {
      explicitApi() // 必须加！避免默认internal导致的符号不可见
      // ... 其他target、sourceSets配置
  }
  

• 确保所有需要对外暴露的inline functions、extension functions、typealias都加上public修饰符，包括它们依赖的所有内部元素（比如inline函数里调用的函数、typealias指向的类型）也必须是public——inline函数因为需要内联到调用方代码，不能依赖internal符号，否则外部会直接报错。

2. 验证Maven构件的完整性 #

你提到代码已存在但无法访问，那要确认发布的构件里有没有包含Kotlin编译器需要的元数据：

• 找到本地Maven仓库里你的库目录（一般在~/.m2/repository/你的groupId/你的artifactId/版本号）
• 检查是否存在这几个关键文件：
  • *-metadata.jar：存放common模块的Kotlin元数据，里面必须包含.kotlin_module文件（记录public API的符号信息）
  • *-sources.jar：确保里面有你写的inline/扩展函数源码
  • 对应平台的jar（比如*-jvm.jar）：里面的.kotlin_module也必须包含这些符号的声明
• 如果缺失metadata.jar，说明你发布配置里没包含元数据构件，需要在publishing块里补充：

  kotlin {
      publishing {
          publications {
              // 针对common metadata的发布
              create<MavenPublication>("mavenCommon") {
                  from(components["kotlin"])
                  artifact(tasks.getByName("metadataJar"))
                  artifact(tasks.getByName("kotlinSourcesJar"))
              }
              // 针对各平台的发布（比如JVM）
              create<MavenPublication>("mavenJvm") {
                  from(components["jvm"])
                  artifact(tasks.getByName("jvmSourcesJar"))
              }
          }
      }
  }
  

3. 检查依赖项目的依赖声明是否正确 #

依赖方需要正确引用KMM库的构件，不能只引用平台特定的jar：

• 在Android/iOS/JVM项目里，直接用groupId:artifactId:version的方式依赖，Gradle会自动解析对应平台的构件和metadata：

  dependencies {
      api("com.your.group:your-kmm-lib:1.0.0")
  }
  

• 如果你手动指定了平台后缀（比如your-kmm-lib-jvm），可能会漏掉metadata jar，导致common里的扩展函数/typealias无法被解析。

4. 清理缓存，排除环境干扰 #

有时候是Gradle缓存或Maven本地缓存导致的旧构件残留：

• 在KMM模块里执行：./gradlew clean publishToMavenLocal，彻底清理后重新发布
• 在依赖项目里执行：./gradlew clean build --refresh-dependencies，强制刷新依赖缓存

5. 排查inline函数的特殊限制 #

Inline函数有额外的访问限制，要确保：

• 没有在inline函数里引用internal或private的类、函数、属性
• 如果inline函数是在expect/actual结构里，要确保actual实现也保持public可见性，并且逻辑和expect一致

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