CocoaPods 概览与设置

这是一种本地集成方法。如果满足以下条件，它可能适合您：

您拥有一个使用 CocoaPods 的 iOS 项目的单仓库 (mono repository) 设置。
您的 Kotlin Multiplatform 项目具有 CocoaPods 依赖项。

选择最适合您的集成方式

Kotlin/Native 提供了与 CocoaPods 依赖管理器的集成。您可以添加对 Pod 库的依赖，也可以将 Kotlin 项目作为 CocoaPods 依赖项使用。

CocoaPods 集成方法不能与用于直接集成的 embedAndSignAppleFrameworkForXcode 机制一起使用。

您可以直接在 IntelliJ IDEA 或 Android Studio 中管理 Pod 依赖项，并享受代码高亮显示和补全等所有附加功能。您可以使用 Gradle 构建整个 Kotlin 项目，而无需切换到 Xcode。

只有当您想要更改 Swift/Objective-C 代码或在 Apple 模拟器或设备上运行应用程序时，才需要 Xcode。若要配合 Xcode 工作，请先更新您的 Podfile。

设置 CocoaPods 工作环境

使用您选择的安装工具安装 CocoaPods 依赖管理器：

RVMRbenv默认 RubyHomebrew

如果您尚未安装 RVM，请先安装。
安装 Ruby。您可以选择特定版本：
bash
```
rvm install ruby 3.4.7
```

安装 CocoaPods：

bash

sudo gem install -n /usr/local/bin cocoapods

如果您尚未安装来自 GitHub 的 rbenv，请先安装。
安装 Ruby。您可以选择特定版本：
bash
```
rbenv install 3.4.7
```
将 Ruby 版本设置为特定目录的本地版本或整台计算机的全局版本：
bash
```
rbenv global 3.4.7
```

安装 CocoaPods：

bash

sudo gem install -n /usr/local/bin cocoapods

这种安装方式在配备 Apple M 芯片的设备上无法正常工作。请使用其他工具设置 CocoaPods 工作环境。

您可以使用 macOS 上默认提供的 Ruby 安装 CocoaPods 依赖管理器：

bash

sudo gem install cocoapods

使用 Homebrew 安装 CocoaPods 可能会导致兼容性问题。
在安装 CocoaPods 时，Homebrew 还会安装 Xcodeproj gem，这是配合 Xcode 工作所必需的。然而，它无法通过 Homebrew 更新，如果安装的 Xcodeproj 尚不支持最新的 Xcode 版本，您在安装 Pod 时会遇到错误。如果是这种情况，请尝试使用其他工具安装 CocoaPods。

如果您尚未安装 Homebrew，请先安装。
安装 CocoaPods：
bash
```
brew install cocoapods
```

如果您在安装过程中遇到问题，请查看可能的问题与解决方案章节。

创建项目

设置好 CocoaPods 环境后，您可以配置 Kotlin Multiplatform 项目以配合 Pod 工作。以下步骤展示了在全新生成的项目上的配置过程：

使用 Kotlin Multiplatform IDE 插件或 Kotlin Multiplatform 网络向导生成一个新的 Android 和 iOS 项目。如果使用网络向导，请解压缩存档并在您的 IDE 中导入项目。

将 Kotlin CocoaPods Gradle 插件添加到版本目录（gradle/libs.versions.toml 文件）中：

toml

[plugins]
kotlinCocoapods = { id = "org.jetbrains.kotlin.native.cocoapods", version.ref = "kotlin" }

导航到项目的根 build.gradle.kts 文件，并将以下别名添加到 plugins {} 块中：
kotlin
```
alias(libs.plugins.kotlinCocoapods) apply false
```
打开您想要集成 CocoaPods 的模块（例如 sharedLogic 模块），并将以下别名添加到该模块 build.gradle.kts 文件的 plugins {} 块中：
kotlin
```
alias(libs.plugins.kotlinCocoapods)
```

现在您已准备好在 Kotlin Multiplatform 项目中配置 CocoaPods。

配置项目

要在您的多平台项目中配置 Kotlin CocoaPods Gradle 插件：

在项目的共享模块的 build.gradle(.kts) 中，应用 CocoaPods 插件以及 Kotlin Multiplatform 插件。
如果您是使用 IDE 插件或网络向导创建的项目，请跳过此步骤。
kotlin
```
plugins {
    kotlin("multiplatform") version "2.3.0"
    kotlin("native.cocoapods") version "2.3.0"
}
```

在 cocoapods 块中配置 Podspec 文件的 version、summary、homepage 和 baseName：

kotlin

plugins {
    kotlin("multiplatform") version "2.3.0"
    kotlin("native.cocoapods") version "2.3.0"
}

kotlin {
    cocoapods {
        // 必需属性
        // 在此处指定所需的 Pod 版本
        // 否则将使用 Gradle 项目版本
        version = "1.0"
        summary = "Kotlin/Native 模块的一些描述"
        homepage = "指向 Kotlin/Native 模块主页的链接"

        // 可选属性
        // 在此处配置 Pod 名称，而不是更改 Gradle 项目名称
        name = "MyCocoaPod"

        framework {
            // 必需属性              
            // 框架名称配置。使用此属性代替已弃用的 'frameworkName'
            baseName = "MyFramework"
            
            // 可选属性
            // 指定框架链接类型。默认为动态链接。 
            isStatic = false
            // 依赖项导出
            // 如果您有另一个项目模块，请取消注释并指定它：
            // export(project(":<您的另一个 KMP 模块>"))
            transitiveExport = false // 这是默认值。
        }

        // 将自定义 Xcode 配置映射到 NativeBuildType
        xcodeConfigurationToNativeBuildType["CUSTOM_DEBUG"] = NativeBuildType.DEBUG
        xcodeConfigurationToNativeBuildType["CUSTOM_RELEASE"] = NativeBuildType.RELEASE
    }
}

在 Kotlin Gradle 插件仓库中查看 Kotlin DSL 的完整语法。

在 IntelliJ IDEA 中运行 Build | Reload All Gradle Projects （或在 Android Studio 中运行 File | Sync Project with Gradle Files）以重新导入项目。
生成 Gradle wrapper 以避免在 Xcode 构建期间出现兼容性问题。

应用后，CocoaPods 插件会执行以下操作：

为所有 macOS、iOS、tvOS 和 watchOS 目标添加 debug 和 release 框架作为输出二进制文件。
创建一个 podspec 任务，为项目生成一个 Podspec 文件。

Podspec 文件包含指向输出框架的路径，以及在 Xcode 项目构建过程中自动构建此框架的脚本阶段。

为 Xcode 更新 Podfile

如果您想将 Kotlin 项目导入到 Xcode 项目中：

在 Kotlin 项目的 iOS 部分，对 Podfile 进行更改：
- 如果您的项目有任何 Git、HTTP 或自定义 Podspec 仓库依赖项，请在 Podfile 中指定 Podspec 的路径。
  例如，如果您添加了对 podspecWithFilesExample 的依赖，请在 Podfile 中声明 Podspec 的路径：
  ruby
```
target 'ios-app' do
   # ... 其他依赖项 ...
   pod 'podspecWithFilesExample', :path => 'cocoapods/externalSources/url/podspecWithFilesExample' 
end
```
  :path 应包含指向 Pod 的文件路径。
- 如果您从自定义 Podspec 仓库添加库，请在 Podfile 的开头指定 spec 的位置：
  ruby
```
source 'https://github.com/Kotlin/kotlin-cocoapods-spec.git'

target 'kotlin-cocoapods-xcproj' do
    # ... 其他依赖项 ...
    pod 'example'
end
```
在您的项目目录中运行 pod install。
当您第一次运行 pod install 时，它会创建 .xcworkspace 文件。该文件包含您原始的 .xcodeproj 和 CocoaPods 项目。
关闭您的 .xcodeproj 并改为打开新的 .xcworkspace 文件。这样可以避免项目依赖项出现问题。
在 IntelliJ IDEA 中运行 Build | Reload All Gradle Projects （或在 Android Studio 中运行 File | Sync Project with Gradle Files）以重新导入项目。

如果您未在 Podfile 中进行这些更改，podInstall 任务将失败，并且 CocoaPods 插件将在日志中显示错误消息。

可能的问题与解决方案

CocoaPods 安装

Ruby 安装

CocoaPods 是用 Ruby 构建的，您可以使用 macOS 上默认提供的 Ruby 安装它。 Ruby 1.9 或更高版本内置了 RubyGems 软件包管理框架，可帮助您安装 CocoaPods 依赖管理器。

如果您在安装和运行 CocoaPods 时遇到问题，请按照此指南安装 Ruby，或参考 RubyGems 网站安装该框架。

版本兼容性

我们建议使用最新的 Kotlin 版本。此 CocoaPods 设置所需的最低版本为 1.7.0。

使用 Xcode 时的构建错误

CocoaPods 安装的某些变体可能会导致 Xcode 中的构建错误。通常，Kotlin Gradle 插件会在 PATH 中寻找 pod 可执行文件，但这可能会因您的环境而异，从而导致不一致。

要显式设置 CocoaPods 安装路径，您可以手动或使用 shell 命令将其添加到项目的 local.properties 文件中：

如果使用代码编辑器，请将以下行添加到 local.properties 文件：
text
```
kotlin.apple.cocoapods.bin=/Users/Jane.Doe/.rbenv/shims/pod
```

如果使用终端，请运行以下命令：

shell

echo -e "kotlin.apple.cocoapods.bin=$(which pod)" >> local.properties

未找到模块或框架

安装 Pod 时，您可能会遇到与 C 互操作 (C interop) 问题相关的 module 'SomeSDK' not found 或 framework 'SomeFramework' not found 错误。要解决此类错误，请尝试以下解决方案：

更新软件包

更新您的安装工具和已安装的软件包 (gems)：

RVMRbenvHomebrew

更新 RVM：
bash
```
rvm get stable
```
更新 Ruby 的软件包管理器 RubyGems：
bash
```
gem update --system
```
将所有已安装的 gems 升级到最新版本：
bash
```
gem update
```

更新 Rbenv：
bash
```
cd ~/.rbenv
git pull
```
更新 Ruby 的软件包管理器 RubyGems：
bash
```
gem update --system
```
将所有已安装的 gems 升级到最新版本：
bash
```
gem update
```

更新 Homebrew 软件包管理器：
bash
```
brew update
```
将所有已安装的软件包升级到最新版本：
bash
```
brew upgrade
```

指定框架名称

在下载的 Pod 目录 [shared_module_name]/build/cocoapods/synthetic/IOS/Pods/... 中查找 module.modulemap 文件。
检查模块内的框架名称，例如 SDWebImageMapKit {}。如果框架名称与 Pod 名称不匹配，请显式指定：
kotlin
```
pod("SDWebImage/MapKit") {
    moduleName = "SDWebImageMapKit"
}
```

指定头文件

如果 Pod 不包含 .modulemap 文件（例如 pod("NearbyMessages")），请显式指定主头文件：

kotlin

pod("NearbyMessages") {
    version = "1.1.1"
    headers = "GNSMessages.h"
}

查看 CocoaPods 文档了解更多信息。如果这些方法都不起作用，并且您仍然遇到此错误，请在 YouTrack 中报告问题。

应用程序包中缺少资源

如果您的 iOS 应用构建成功但在启动时崩溃，或者最终的 .ipa 包中缺少自定义字体和图像等资源，则可能是 Pod 与项目的集成方式存在问题。

为了防止此问题：不要直接运行 pod install 命令，而是使用 Kotlin CocoaPods Gradle 插件提供的 Gradle podInstall 任务。该任务会创建所需的目录并为您配置好一切：

bash

./gradlew podInstall
open iosApp/iosApp.xcworkspace

问题发生的原因：当您在全新的项目上（例如，在克隆仓库后或在 CI/CD 流水线中工作时）运行原生的 pod install 命令时，资源目录尚未创建。Compose Multiplatform Gradle 插件在生成的 .podspec 文件中指定了资源的位置：spec.resources = ['build/compose/cocoapods/compose-resources']，但该路径仅在构建后才会存在。因此，CocoaPods 会忽略缺失的目录，并在没有这些资源的情况下配置 Xcode 项目。当项目构建并生成资源后，Xcode 不会将其复制到最终的包中。

Rsync 错误

您可能会遇到 rsync error: some files could not be transferred 错误。这是一个已知问题，如果 Xcode 中的应用程序目标启用了用户脚本沙箱化 (sandboxing)，就会发生此问题。

要解决此问题：

在应用程序目标中禁用用户脚本沙箱化：
停止可能已被沙箱化的 Gradle daemon 进程：
shell
```
./gradlew --stop
```

CocoaPods 概览与设置 ​

设置 CocoaPods 工作环境 ​

创建项目 ​

配置项目 ​

为 Xcode 更新 Podfile ​

可能的问题与解决方案 ​

CocoaPods 安装 ​

Ruby 安装 ​

版本兼容性 ​

使用 Xcode 时的构建错误 ​

未找到模块或框架 ​

更新软件包 ​

指定框架名称 ​

指定头文件 ​

应用程序包中缺少资源 ​

Rsync 错误 ​

后续步骤 ​

CocoaPods 概览与设置

设置 CocoaPods 工作环境

创建项目

配置项目

为 Xcode 更新 Podfile

可能的问题与解决方案

CocoaPods 安装

Ruby 安装

版本兼容性

使用 Xcode 时的构建错误

未找到模块或框架

更新软件包

指定框架名称

指定头文件

应用程序包中缺少资源

Rsync 错误

后续步骤