CocoaPods 概览与设置

这是一种本地集成方法。它适用于以下情况：

你有一个使用 CocoaPods 的 iOS 项目的单体版本库设置。
你的 Kotlin Multiplatform 项目有 CocoaPods 依赖项。

选择最适合你的集成方法

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

你可以在 IntelliJ IDEA 或 Android Studio 中直接管理 Pod 依赖项，并享受所有额外特性，例如代码高亮和自动补全。你可以使用 Gradle 构建整个 Kotlin 项目，而无需切换到 Xcode。

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

设置 CocoaPods 工作环境

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

RVMRbenvDefault RubyHomebrew

安装 RVM，如果你尚未安装。
安装 Ruby。你可以选择一个特定版本：
bash
```
rvm install ruby 3.0.0
```

安装 CocoaPods：

bash

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

安装 rbenv from GitHub，如果你尚未安装。
安装 Ruby。你可以选择一个特定版本：
bash
```
rbenv install 3.0.0
```
将 Ruby 版本设置为某个目录的本地版本或整个机器的全局版本：
bash
```
rbenv global 3.0.0
```

安装 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 也会安装对使用 Xcode 必需的 Xcodeproj gem。但是，它无法通过 Homebrew 更新，并且如果已安装的 Xcodeproj 尚不支持最新的 Xcode 版本，你将在 Pod 安装时遇到错误。如果出现这种情况，请尝试其他工具安装 CocoaPods。

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

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

创建项目

当环境设置好后，你可以创建一个新的 Kotlin Multiplatform 项目。为此，请使用 Kotlin Multiplatform 网页向导或 Android Studio 的 Kotlin Multiplatform 插件。

使用网页向导

要使用网页向导创建项目并配置 CocoaPods 集成：

打开 Kotlin Multiplatform 向导并为你的项目选择目标平台。
点击 Download 按钮并解压下载的归档文件。
在 Android Studio 中，选择菜单中的 File | Open。
导航到解压后的项目文件夹，然后点击 Open。
将 Kotlin CocoaPods Gradle 插件添加到版本目录。在 gradle/libs.versions.toml 文件中，将以下声明添加到 [plugins] 代码块中：
text
```
kotlinCocoapods = { id = "org.jetbrains.kotlin.native.cocoapods", version.ref = "kotlin" }
```
导航到项目的根 build.gradle.kts 文件，并将以下别名添加到 plugins {} 代码块中：
kotlin
```
alias(libs.plugins.kotlinCocoapods) apply false
```
打开你想要集成 CocoaPods 的模块，例如 composeApp 模块，并将以下别名添加到 plugins {} 代码块中：
kotlin
```
alias(libs.plugins.kotlinCocoapods)
```

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

在 Android Studio 中

要在 Android Studio 中创建具有 CocoaPods 集成的项目：

在 Android Studio 中安装 Kotlin Multiplatform 插件。
在 Android Studio 中，选择菜单中的 File | New | New Project。
在项目模板列表中，选择 Kotlin Multiplatform App，然后点击 Next。
为你的应用程序命名，然后点击 Next。
选择 CocoaPods Dependency Manager 作为 iOS framework 分发选项。
其他所有选项保持默认。点击 Finish。
该插件将自动生成已设置 CocoaPods 集成的项目。

配置项目

要在你的 Multiplatform 项目中配置 Kotlin CocoaPods Gradle 插件：

在你的项目的共享模块的 build.gradle(.kts) 中，应用 CocoaPods 插件以及 Kotlin Multiplatform 插件。
如果你已通过网页向导或适用于 Android Studio 的 Kotlin Multiplatform 插件创建项目，请跳过此步骤。
kotlin
```
plugins {
    kotlin("multiplatform") version "2.2.0"
    kotlin("native.cocoapods") version "2.2.0"
}
```

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

kotlin

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

kotlin {
    cocoapods {
        // 必需属性
        // 在此处指定所需的 Pod 版本
        // 否则，使用 Gradle 项目版本
        version = "1.0"
        summary = "Some description for a Kotlin/Native module"
        homepage = "Link to a Kotlin/Native module homepage"

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

        framework {
            // 必需属性              
            // Framework 名称配置。请使用此属性而非已弃用的 'frameworkName'
            baseName = "MyFramework"
            
            // 可选属性
            // 指定 framework 链接类型。默认情况下为动态链接。
            isStatic = false
            // 依赖项导出
            // 如果你有其他项目模块，请取消注释并指定：
            // export(project(":<your other KMP module>"))
            transitiveExport = false // 这是默认值。
        }

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

关于 Kotlin DSL 的完整语法，请参阅 Kotlin Gradle 插件版本库。

在 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 framework 作为输出二进制文件。
创建一个 podspec 任务，该任务为项目生成一个 Podspec 文件。

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

更新 Xcode 的 Podfile

如果你想将 Kotlin 项目导入 Xcode 项目：

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

target 'kotlin-cocoapods-xcproj' do
    # ... other dependencies ...
    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。如果你当前的版本早于 1.7.0，则需要额外安装 cocoapods-generate 插件。

但是，cocoapods-generate 与 Ruby 3.0.0 或更高版本不兼容。在这种情况下，请降级 Ruby 或将 Kotlin 升级到 1.7.0 或更高版本。

使用 Xcode 时出现构建错误

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

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

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

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

shell

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

找不到模块或 framework

安装 Pods 时，你可能会遇到与 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
```

指定 framework 名称

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

指定头文件

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

kotlin

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

有关更多信息，请查阅 CocoaPods 文档。如果所有方法都无效，并且你仍然遇到此错误，请在 YouTrack 中报告一个问题。

Rsync 错误

你可能会遇到 rsync error: some files could not be transferred 错误。这是一个已知问题，当 Xcode 中的应用程序目标启用了用户脚本的沙盒化时会发生。

要解决此问题：

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

CocoaPods 概览与设置 ​

设置 CocoaPods 工作环境 ​

创建项目 ​

使用网页向导 ​

在 Android Studio 中 ​

配置项目 ​

更新 Xcode 的 Podfile ​

可能的问题和解决方案 ​

CocoaPods 安装 ​

Ruby 安装 ​

版本兼容性 ​

使用 Xcode 时出现构建错误 ​

找不到模块或 framework ​

更新包 ​

指定 framework 名称 ​

指定头文件 ​

Rsync 错误 ​

下一步 ​

CocoaPods 概览与设置

设置 CocoaPods 工作环境

创建项目

使用网页向导

在 Android Studio 中

配置项目

更新 Xcode 的 Podfile

可能的问题和解决方案

CocoaPods 安装

Ruby 安装

版本兼容性

使用 Xcode 时出现构建错误

找不到模块或 framework

更新包

指定 framework 名称

指定头文件

Rsync 错误

下一步