Kotlin Multiplatform Development Help

为你的Kotlin跨平台项目选择配置方案

当你为现有项目添加Kotlin跨平台支持或启动新项目时,有多种代码组织方式可供选择。通常你会创建一个或多个Kotlin跨平台共享模块,并在Android和iOS应用中调用这些模块。

为你的具体场景选择最佳方案时,请考虑以下问题:

  • 如何让iOS应用调用Kotlin跨平台模块生成的框架? 是直接集成、通过CocoaPods,还是使用Swift包管理器(SPM)?

  • 你有一个还是多个Kotlin跨平台共享模块? 多个共享模块是否需要伞模块(umbrella module)?

  • 所有代码是存储在单一仓库(monorepo)还是不同仓库中?

  • Kotlin跨平台模块框架是作为本地依赖还是远程依赖?

回答这些问题将帮助你为项目选择最佳配置。

连接Kotlin跨平台模块与iOS应用

要在iOS应用中使用Kotlin跨平台共享模块,首先需要从该模块生成iOS框架 ,然后将其添加为iOS项目的依赖:

Kotlin跨平台共享模块

该框架可作为本地或远程依赖使用。

可通过以下方式之一将Kotlin跨平台模块框架添加至iOS项目:

  • 直接集成 。通过为iOS应用构建添加新的运行脚本阶段直接连接框架。参阅将框架连接至iOS项目了解Xcode中的操作方法。

    使用Android Studio向导创建项目时,选择Regular framework选项可自动生成此配置。

  • CocoaPods集成 。通过Swift和Objective-C常用依赖管理器CocoaPods连接框架,支持本地或远程依赖。详见将Kotlin Gradle项目作为CocoaPods依赖

    可通过向导生成项目或手动编辑脚本配置本地CocoaPods依赖工作流。

  • 使用SPM 。通过Apple的Swift代码分发管理工具Swift包管理器(SPM)连接框架。我们正在开发对SPM的官方支持 。目前可通过XCFrameworks建立Swift包依赖,详见Swift包导出配置

模块配置方案

Kotlin跨平台项目有两种模块配置选项:单一模块或多个共享模块。

单一共享模块

最简单的配置方案是项目中仅包含单个Kotlin跨平台共享模块:

单一共享模块

Android应用可将其作为常规Kotlin模块依赖,而iOS应用必须依赖该模块生成的iOS框架。

优势

劣势

  • 单一模块的简单设计降低认知负荷,无需考虑功能划分

  • 非常适合作为起点

  • 随着模块增长编译时间增加

  • 无法实现功能分离或按需依赖

多个共享模块

当共享模块规模扩大时,建议拆分为功能模块以避免可扩展性问题。

Android应用可选择依赖全部或部分功能模块。iOS应用需通过_伞模块_生成包含所有模块的_伞框架_:

优势

劣势

  • 实现共享代码的关注点分离

  • 更好的可扩展性

  • 配置更复杂(包括伞框架设置)

  • 跨模块依赖管理更繁琐

伞模块设置需创建依赖所有功能模块的新模块并生成框架:

伞框架

Android应用可选择依赖伞模块(通常包含工具函数和依赖注入配置)或独立功能模块。

远程依赖场景下可选择性导出模块以控制产物体积。当前限制是iOS应用必须使用全部功能模块,相关改进可反馈至KT-42247KT-42250

为何需要伞框架?

虽然iOS应用可集成多个独立框架,但不推荐此方案。当不同模块包含相同依赖时,Kotlin/Native编译器会重复打包依赖,导致:

  • 应用体积膨胀

  • 依赖代码结构冲突

  • 状态传递异常

伞框架能避免依赖重复、优化产物体积并解决兼容性问题。Kotlin编译器会精确裁剪所需代码,但当前无法实现依赖共享。

仓库配置方案

Kotlin跨平台项目可采用单一仓库或多仓库组合的配置方案。

单一仓库:所有代码集中存储

常见方案是将Android/iOS应用与共享模块(含伞模块)存放在同一仓库:

单一仓库配置
单一仓库配置

iOS应用通常通过直接集成或CocoaPods使用共享模块,所有组件版本同步。

优势

劣势

  • 向导工具简化配置

  • iOS开发者可便捷访问Kotlin代码

  • iOS开发者需配置陌生工具

  • 不适用于已有独立仓库的现存应用

双仓库:Android+共享模块 | iOS

将Kotlin跨平台代码与Android应用存放在同一仓库,iOS应用单独存放:

双仓库配置

Android与iOS应用可独立版本化,共享模块随Android应用版本更新。

三仓库:Android | iOS | 共享模块

共享模块独立仓库方案:

三仓库配置

各项目可独立版本化。需发布Kotlin跨平台模块(可选择发布功能模块或仅伞模块)。此方案会增加Android开发者的复杂度,但能实现团队间的版本协同。

多仓库:Android | iOS | 多个库

当功能需跨多平台共享时,可采用多仓库方案。例如将通用日志库存放在独立版本化仓库中:

多仓库配置

每个库需独立发布,iOS应用可通过额外仓库配置包含所需库依赖的伞模块。

代码共享工作流

iOS应用可通过_本地_或_远程_方式使用框架:

本地:源码分发

iOS应用直接使用本地生成的框架(无需发布),适合Android/iOS团队共同开发场景:

本地源码分发

优势

劣势

  • 促进团队协作

  • 无需版本发布

  • 开发效率高

  • 需配置完整开发环境

  • iOS开发者需学习新工具

  • 大规模团队管理困难

远程:产物分发

通过发布CocoaPod或SPM包供iOS应用使用,适合渐进式采用场景。推荐使用KMMBridge简化流程:

远程产物分发

优势

劣势

降低iOS团队学习成本

  • 开发流程缓慢

  • 调试困难

  • 团队贡献度下降

  • 维护压力集中

为本地开发配置本地依赖

推荐远程分发团队额外配置本地开发工作流:开发新功能时切换至本地依赖框架,便于即时调试;功能完成后发布变更并切回远程依赖。可通过TouchLab方案实现CocoaPods环境切换。

23 四月 2025