Kotlin 语言参考文档 中文版 Help

直接集成

如果你想要通过共用代码来同时开发你的 Kotlin Multiplatform 项目和 iOS 项目, 你可以使用一段特别的脚本来设置直接集成.

这段脚本会自动化在 Xcode 中将 Kotlin 框架连接到 iOS 项目的过程:

直接集成

这段脚本使用专门为 Xcode 环境设计的 Gradle 任务 embedAndSignAppleFrameworkForXcode. 在设置过程中, 你要将它添加到 iOS App 构建的运行脚本阶段(Run Script Phase). 然后, 在运行 iOS App 构建之前, Kotlin artifact 会构建, 并包含在派生数据中.

一般来说, 这段脚本会:

  • 将编译后的 Kotlin 框架复制到 iOS 项目结构的正确目录中.

  • 处理内嵌框架的代码签名(code signing)过程.

  • 确保 Kotlin 框架中发生变更的代码 Xcode 中的反应到 iOS App 中.

如何设置

如果你目前在使用 CocoaPods plugin 来连接你的 Kotlin 框架, 首先请进行迁移. 如果你的项目没有 CocoaPods 依赖项, 请跳过这一步.

从 CocoaPods plugin 迁移

要从 CocoaPods plugin 迁移, 请进行以下步骤:

  1. 在 Xcode 中, 使用 Product | Clean Build Folder, 或使用 Cmd + Shift + K 快捷键, 清除构建目录.

  2. 在 Podfile 所在的目录中, 运行以下命令:

    pod deintegrate
  3. 从你的 build.gradle(.kts) 文件中删除 cocoapods {} 代码块.

  4. 删除 .podspec 文件和 Podfile.

将框架连接到你的项目

要将从跨平台项目生成的 Kotlin 框架连接到你的 Xcode 项目, 请进行以下步骤:

  1. 只有声明过 binaries.framework 配置选项, 才会注册 embedAndSignAppleFrameworkForXcode task. 在你的 Kotlin Multiplatform 项目中, 在 build.gradle.kts 文件中选择 iOS 编译目标声明.

  2. 在 Xcode 中, 双击项目名称, 打开 iOS 项目设置.

  3. 在左侧的 Targets 中, 选择你的 target, 然后进入 Build Phases 页.

  4. 点击 +, 并选择 New Run Script Phase.

    添加运行脚本阶段
  5. 调整下面的脚本, 并粘贴到运行脚本(Run Script)栏:

    cd "<跨平台项目的根目录路径>" ./gradlew :<共用的模块名称>:embedAndSignAppleFrameworkForXcode
    • cd 命令中, 指定你的 Kotlin Multiplatform 项目的根目录路径, 例如, $SRCROOT/...

    • ./gradlew 命令中, 指定共用的模块名称, 例如, :shared:composeApp.

    Add the script
  6. 禁用 Based on dependency analysis 选项.

    这样会确保 Xcode 在每次构建期间运行脚本, 而且不会每次都警告缺少输出的依赖项.

  7. Run Script 阶段移动到更高的位置, 放在 Compile Sources 阶段之前.

    拖动 Run Script 阶段
  8. Build Settings 页, 禁用 Build Options 之下的 User Script Sandboxing 选项:

    User Script Sandboxing
  9. 在 Xcode 中构建项目. 如果一切设置正确, 项目将会构建成功.

下一步做什么?

使用 Swift 包管理器时, 你也可以使用本地集成. 学习如何在本地包中添加 Kotlin 框架的依赖项.

2025/08/04