Kotlin多平台库iOS目标集成RealmSwift时cinterop任务执行失败

cinteropRealmSwiftIos 任务核心作用 #

该任务是Kotlin/Native CocoaPods集成体系的内置桥接生成任务，负责解析CocoaPods安装的RealmSwift原生接口定义，生成Kotlin侧可直接调用的类型安全桥接代码，是iOS侧代码能调用RealmSwift接口的前置必经步骤。任务执行失败本质是桥接生成阶段的环境、依赖配置不符合要求，默认不会输出复杂的通用构建日志。

本次报错的高频根因与修复方式 #

• 使用Android Studio捆绑JRE运行Gradle构建
  从报错日志可见，当前执行构建的Java路径是 /Applications/Android Studio.app/Contents/jre/jdk/Contents/Home/bin/java，属于IDE内置的阉割版JRE环境。Kotlin/Native的cinterop任务依赖完整JDK的原生工具类完成桥接解析，Kotlin 1.4.x分支在调用该JRE路径时，会因为环境完整性不足直接触发非零退出。
  修复方案：在项目根目录的gradle.properties中手动指定独立安装的完整JDK路径，示例配置为 org.gradle.java.home=/Library/Java/JavaVirtualMachines/temurin-11.jdk/Contents/Home，避免依赖IDE自带运行时完成构建。
• CocoaPods本地依赖安装不完整或版本残留
  项目配置指定RealmSwift版本为~> 10.5，如果本地CocoaPods缓存存在历史版本残留、安装的RealmSwift缺失iOS目标对应的模拟器、真机双架构产物，会导致cinterop扫描模块声明时找不到有效接口定义。
  修复方案：先执行缓存清理命令清除残留：

  pod cache clean RealmSwift --all
  

  再删除项目目录下的Pods文件夹、Podfile.lock文件，重新执行pod install完成依赖安装后再触发Gradle构建。
• Kotlin 1.4.31与RealmSwift版本的兼容性问题
  Kotlin 1.4.31是非常早期的Kotlin多平台CocoaPods集成分支，对带复杂Swift宏、属性包装器语法的第三方依赖的桥接解析能力不足。RealmSwift 10.5.x版本引入了大量Swift属性包装器定义，会导致cinterop解析头文件时直接崩溃，且仅返回通用退出码，不输出具体解析错误。
  修复方案：临时将RealmSwift版本调整为10.2.x，该版本的接口结构对老版本Kotlin cinterop的兼容性更稳定。

提取有效排查日志的方法 #

由于默认构建输出仅返回通用退出码，执行构建时可以追加详细输出参数获取具体错误信息：

./gradlew :library:cinteropRealmSwiftIos --info --stacktrace

日志中cinterop环节输出的路径缺失提示、头文件解析错误，即可直接对应具体故障点。

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