如何在Xcode iOS项目中集成Kotlin Multiplatform静态库

前置信息 #

已在共享模块的build.gradle.kts中配置静态库生成：

listOf(
    iosX64(),
    iosArm64(),
    iosSimulatorArm64()
).forEach {
    it.binaries.staticLib {
        baseName = "shared"
    }
}

执行./gradlew build后已生成libshared.a和libshared_api.h文件，且已完成以下操作：

• 将库文件添加至Xcode项目
• 在Build Settings的Header Search Paths中添加.h文件路径
• 在Library Search Paths中添加.a文件路径
• 在Build Phases的Link Binary With Libraries中添加.a文件路径

后续集成步骤 #

1. 架构适配处理 #

生成的静态库分三个架构版本：iosX64（x86模拟器）、iosArm64（真机）、iosSimulatorArm64（M系列模拟器），需确保Xcode能匹配编译目标：

• 方案一：分路径存放架构库
  将三个架构的libshared.a分别放入不同文件夹（如libs/ios/x64、libs/ios/arm64、libs/ios/sim_arm64），在Build Settings的Library Search Paths中添加对应路径，并设置为根据编译条件切换。
• 方案二：合并为通用库
  使用lipo命令合并三个架构为通用库，替换项目中的单架构库：

  lipo -create libshared-iosX64.a libshared-iosArm64.a libshared-iosSimulatorArm64.a -output libshared-universal.a
  

2. 头文件导入与桥接 #

• Objective-C项目：直接在需要调用KMM代码的源文件中导入头文件：

  #import "libshared_api.h"
  

• Swift项目：创建桥接文件（如Project-Bridging-Header.h），在文件内添加上述导入语句，然后在Build Settings的Objective-C Bridging Header中设置该文件的相对路径（如$(SRCROOT)/Project-Bridging-Header.h）。

3. 调用KMM暴露的API #

确保KMM代码中需要暴露的函数/类已添加@ObjCName或@ExportObjCName注解，比如：

@ObjCName(name = "greet")
fun greet(): String = "Hello from KMM"

然后在iOS代码中调用：

• Objective-C：

  NSString *greeting = greet();
  NSLog(@"%@", greeting);
  

• Swift：

  let greeting = greet()
  print(greeting)
  

4. 常见问题排查 #

• undefined symbol错误：检查库是否包含当前编译目标的架构，或KMM函数是否正确添加暴露注解。
• 头文件找不到：确认Header Search Paths设置为递归（recursive），路径使用相对路径（如$(SRCROOT)/../shared/build/bin/ios/releaseStatic）。
• duplicate symbol错误：检查是否重复添加库文件，或同时链接了静态库与动态库。

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