CocoaPods Plugin — 什么是它，用于 KMM 的插件和配置

什么是 CocoaPods Plugin？

CocoaPods Plugin（也称为 kotlin.cocoapods）— 是 JetBrains 用于将 CocoaPods 与 Kotlin Multiplatform Mobile 集成的官方插件。该插件是 Kotlin Gradle DSL 的一部分，并直接在 KMM 模块的 build.gradle.kts 中配置。它自动化了 Podfile 的创建和维护、.xcworkspace 的生成以及 pod 依赖项的管理，使开发人员免于手动配置 Xcode 项目。

在 CocoaPods Plugin 出现之前，KMM 开发人员不得不手动创建 Podfile，运行 pod install，配置 bridge-header，并单独跟踪 pod 版本与 Gradle 依赖项。这导致了版本不同步和 CI/CD 管道中的困难。该插件解决了这些问题，使 iOS 依赖项的管理变得像在 Android 模块中管理 Gradle 依赖项一样简单。

该插件同时支持来自 CocoaPods Trunk 的公共 pod 和来自私有仓库的自定义 pod。与本地 Podspec和基于 git 的仓库的工作也得到支持。该插件与 Kotlin 1.6.0 及以上版本兼容，并且需要在开发人员的机器上安装 CocoaPods（gem install cocoapods）。

CocoaPods Plugin 如何工作

CocoaPods Plugin 在 Gradle 任务图级别工作，添加了用于与 CocoaPods 配合使用的专门任务。主要任务包括 podInstall（安装 pod）、podGenXcodeWorkspace（生成 .xcworkspace）和 podBuildDebugFramework（构建框架的调试版本）。该插件分析 build.gradle.kts 中的 cocoapods 部分，根据声明的依赖项创建 Podfile，并使用必要的参数运行 pod install。

该插件的架构包括三个组件：用于 build.gradle.kts 的 DSL 扩展、用于创建 Podfile 的 Podfile 生成器和用于配置 .xcworkspace 的 Xcode 集成层。DSL 扩展提供 cocoapods { } 块，其中包含用于声明依赖项的嵌套 pod() 函数、用于指定私有仓库的 specRepo() 以及用于配置输出框架的 framework { }。Podfile 生成器将这些声明转换为 CocoaPods 可理解的 Ruby 语法。

kotlin {
    cocoapods {
        summary = "Shared module for iOS project"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = true
            export(project(":core"))
        }
        pod("Alamofire") {
            version = "~> 5.9"
        }
        pod("Kingfisher") {
            version = "7.12"
        }
    }
}

podInstall 任务的生命周期

在执行 podInstall 时，插件依次：在项目根目录生成 Podfile，通过命令行运行 pod install，生成 .xcworkspace，检查 pod 版本与声明版本的一致性，并缓存 Podfile.lock。在配置没有变化的情况下重新运行时，如果 Podfile.lock 没有改变，podInstall 将被跳过。这在 CI/CD 中节省了时间，其中 pod install 在全新安装时可能需要长达 2-3 分钟。

在 KMM 项目中配置 CocoaPods Plugin

配置 CocoaPods Plugin 需要执行几个步骤。在开发人员机器上安装 CocoaPods（gem install cocoapods）是强制条件。然后在 shared 模块的 build.gradle.kts 中添加带有框架和依赖项配置的 cocoapods { } 块。配置后，需要执行 podInstall 任务，该任务将创建 Podfile 并安装 pod。生成的 .xcworkspace 将位于项目根目录中 Podfile 旁边。

该插件与 Xcode Build Phases 集成。在构建 iOS 应用程序时，Xcode 运行 embedAndSignAppleFrameworkForXcode — 一个将 Kotlin/Native 框架复制到应用程序包中的任务。CocoaPods Plugin 在生成 .xcworkspace 时自动添加此构建阶段。如果已生成 .xcworkspace，则应打开它而不是 .xcodeproj 以正确编译 pod 依赖项。

代码示例：配置 pod

让我们看看在 CocoaPods Plugin 中声明 pod 的各种场景。基本情况 — 从 CocoaPods Trunk 连接公共 pod 并指定版本。更复杂的场景包括使用自定义 podspec、本地 pod 和来自 git 仓库的 pod。

kotlin {
    iosArm64()
    iosSimulatorArm64()

    cocoapods {
        framework {
            baseName = "Shared"
            isStatic = false
        }

        // 来自 CocoaPods Trunk 的公共 pod
        pod("Alamofire") { version = "5.9.0" }

        // 带运算符的自定义版本
        pod("SnapKit") { version = "~> 5.6" }

        // 来自私有仓库的 pod
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // 带路径的本地 pod
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // 来自 git 仓库的 pod
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

连接 pod 只是配置的一部分。该插件还允许导出来自其他 Kotlin 模块的依赖项到 iOS 框架。export(project(":core")) 函数指示 :core 模块的所有公共 API 都应该可以从生成的框架的 Objective-C 头文件访问。当共享 Kotlin 代码使用另一个模块的类并且这些类必须可以从 Swift 访问时，这是必要的。

cocoapods {
    framework {
        baseName = "Shared"
        // 将模块导出到 iOS 框架
        export(project(":network"))
        export(project(":domain"))

        // 静态或动态连接
        isStatic = true
    }

    // 导出的模块所需的 pod
    pod("Moya") { version = "15.0" }
}

构建和测试

配置后，需要执行 podInstall 以生成 Podfile 并安装依赖项。然后生成的 .xcworkspace 在 Xcode 中打开，可以在其中以标准方式构建应用程序。对于 CI/CD，请确保在构建机器上安装了 CocoaPods 和 Ruby。该插件支持 --no-daemon 标志以在 CI 环境中工作。

// 安装 pod 生成 Podfile + xcworkspace
./gradlew :shared:podInstall

// 构建调试框架用于测试
./gradlew :shared:podBuildDebugFramework

// 从命令行完整构建 iOS
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager（SPM）— Apple 的替代依赖管理器，越来越受欢迎，并逐渐在 iOS 社区中取代 CocoaPods。然而，CocoaPods Plugin 由于几个原因仍然具有相关性：SPM 在 KMM 上下文中不支持动态框架，并且通过 SPM 集成 Kotlin/Native 框架需要额外配置。CocoaPods Plugin 提供了更成熟和文档化的集成路径。

比较 CocoaPods Plugin 和通过 SPM 的直接集成表明，前者在自动化方面胜出，后者在 Apple 原生支持方面胜出。CocoaPods Plugin 自动生成 Podfile，管理版本并配置 Xcode Build Phases。SPM 需要通过 Package.swift 手动连接 Kotlin 框架，这对于大型 KMM 项目来说更难维护。JetBrains 正在为 Kotlin/Native 开发 SPM 支持，但到 2025 年，SPM 集成仍然是实验性的。

常见问题及解决方案

在使用 CocoaPods Plugin 时，KMM 开发人员会遇到几个常见问题。Pod 版本冲突 — 最常见的问题，当两个 pod 需要同一依赖项的不同版本时发生。解决方案是通过 pod("Dependency") { version = "x.x" } 明确指定冲突依赖项的版本。第二种常见情况 — 版本不兼容，当 pod 需要比 KMM 项目最低版本更新的 iOS SDK 时。

.xcworkspace 的问题出现在配置插件后打开 .xcodeproj 而不是 .xcworkspace 时。插件会在 podInstall 日志中警告这一点。另一个常见错误 — 开发人员机器上没有 CocoaPods。插件在运行 podInstall 之前检查 pod 命令的存在性，并显示清晰的错误消息。对于 CI/CD，请安装 CocoaPods：gem install cocoapods。

// 解决版本冲突
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // 显式解决冲突
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// 通过 Gradle 检查 CocoaPods 安装
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods 版本：$result")
    }
}

调试 podInstall

如果 podInstall 以错误结束，请使用 --info 标志获取详细输出：./gradlew podInstall --info。该插件记录每个步骤：生成 Podfile，运行 pod install，解析 Podfile.lock。大多数情况下，错误与网络问题（CocoaPods Trunk 不可用）或 Podfile 语法错误有关。在这种情况下，请尝试在项目根目录手动运行 pod install 以从 CocoaPods 获取更详细的错误消息。