CocoaPods Plugin — nó là gì, plugin cho KMM và thiết lập

CocoaPods Plugin là gì?

CocoaPods Plugin (còn được gọi là kotlin.cocoapods) là một plugin chính thức của JetBrains để tích hợp CocoaPods với Kotlin Multiplatform Mobile. Plugin là một phần của Kotlin Gradle DSL và được cấu hình trực tiếp trong build.gradle.kts của mô-đun KMM. Nó tự động hóa việc tạo và duy trì Podfile, tạo .xcworkspace và quản lý các phụ thuộc pod, loại bỏ nhu cầu cấu hình thủ công dự án Xcode.

Trước CocoaPods Plugin, các nhà phát triển KMM buộc phải tự tạo Podfile, chạy pod install, cấu hình bridge header và theo dõi phiên bản pod riêng biệt với các phụ thuộc Gradle. Điều này dẫn đến mất đồng bộ phiên bản và khó khăn trong các pipeline CI/CD. Plugin đã giải quyết những vấn đề này bằng cách làm cho việc quản lý phụ thuộc iOS trở nên đơn giản như quản lý phụ thuộc Gradle trong các mô-đun Android.

Plugin hỗ trợ cả pods công khai từ CocoaPods Trunk và pods tùy chỉnh từ kho lưu trữ riêng. Làm việc với Podspec cục bộ và kho lưu trữ dựa trên git cũng được hỗ trợ. Plugin tương thích với Kotlin 1.6.0 trở lên và yêu cầu cài đặt CocoaPods (gem install cocoapods) trên máy phát triển.

CocoaPods Plugin hoạt động như thế nào

CocoaPods Plugin hoạt động ở cấp độ task-graph của Gradle, thêm các tác vụ chuyên biệt để làm việc với CocoaPods. Các tác vụ chính bao gồm podInstall (cài đặt pods), podGenXcodeWorkspace (tạo .xcworkspace) và podBuildDebugFramework (xây dựng phiên bản Debug của framework). Plugin phân tích phần cocoapods trong build.gradle.kts, tạo Podfile dựa trên các phụ thuộc đã khai báo và chạy pod install với các tham số cần thiết.

Kiến trúc của plugin bao gồm ba thành phần: phần mở rộng DSL cho build.gradle.kts, Trình tạo Podfile để tạo Podfile và Lớp tích hợp Xcode để cấu hình .xcworkspace. Phần mở rộng DSL cung cấp khối cocoapods { } với các hàm pod() lồng nhau để khai báo phụ thuộc, specRepo() để chỉ định kho lưu trữ riêng và framework { } để cấu hình framework đầu ra. Trình tạo Podfile dịch các khai báo này thành cú pháp Ruby mà CocoaPods hiểu được.

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"
        }
    }
}

Vòng đời của tác vụ podInstall

Khi thực thi podInstall, plugin tuần tự: tạo Podfile trong thư mục gốc của dự án, chạy pod install qua dòng lệnh, tạo .xcworkspace, kiểm tra phiên bản pod khớp với các phiên bản đã khai báo và lưu cache Podfile.lock. Trong các lần chạy sau mà không có thay đổi cấu hình, podInstall được bỏ qua nếu Podfile.lock không thay đổi. Điều này tiết kiệm thời gian trong CI/CD, nơi pod install có thể mất tới 2-3 phút cho một lần cài đặt sạch.

Thiết lập CocoaPods Plugin trong dự án KMM

Thiết lập CocoaPods Plugin yêu cầu một số bước. Cài đặt CocoaPods trên máy phát triển (gem install cocoapods) là điều kiện tiên quyết. Sau đó, trong build.gradle.kts của mô-đun shared, thêm khối cocoapods { } với cấu hình framework và các phụ thuộc. Sau khi cấu hình, chạy tác vụ podInstall để tạo Podfile và cài đặt pods. .xcworkspace được tạo sẽ nằm trong thư mục gốc của dự án bên cạnh Podfile.

Plugin tích hợp với Xcode Build Phases. Khi xây dựng ứng dụng iOS, Xcode chạy embedAndSignAppleFrameworkForXcode — một tác vụ sao chép framework Kotlin/Native vào gói ứng dụng. CocoaPods Plugin tự động thêm build phase này khi tạo .xcworkspace. Nếu .xcworkspace đã được tạo, nó phải được mở thay vì .xcodeproj để build chính xác với các phụ thuộc pod.

Ví dụ mã: cấu hình pod

Hãy xem xét các kịch bản khác nhau để khai báo pods trong CocoaPods Plugin. Trường hợp cơ bản là kết nối một pod công khai từ CocoaPods Trunk với phiên bản được chỉ định. Các kịch bản phức tạp hơn bao gồm sử dụng podspec tùy chỉnh, pods cục bộ và pods từ kho git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Pod công khai từ CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Phiên bản tùy chỉnh với toán tử
        pod("SnapKit") { version = "~> 5.6" }

        // Pod từ kho riêng
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Pod cục bộ với đường dẫn
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // Pod từ kho git
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

Kết nối pods chỉ là một phần của cấu hình. Plugin cũng cho phép xuất các phụ thuộc từ các mô-đun Kotlin khác sang framework iOS. Hàm export(project(":core")) chỉ định rằng tất cả API công khai của mô-đun :core phải có thể truy cập được từ tiêu đề Objective-C của framework được tạo. Điều này cần thiết khi mã Kotlin dùng chung sử dụng các lớp từ mô-đun khác và chúng cần có thể truy cập từ Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Xuất mô-đun sang framework iOS
        export(project(":network"))
        export(project(":domain"))

        // Liên kết tĩnh hoặc động
        isStatic = true
    }

    // Pod cần thiết cho các mô-đun đã xuất
    pod("Moya") { version = "15.0" }
}

Build và kiểm thử

Sau khi cấu hình, bạn cần chạy podInstall để tạo Podfile và cài đặt các phụ thuộc. Sau đó, .xcworkspace được tạo sẽ được mở trong Xcode, nơi ứng dụng có thể được build theo cách tiêu chuẩn. Đối với CI/CD, hãy đảm bảo CocoaPods và Ruby được cài đặt trên máy build. Plugin hỗ trợ cờ --no-daemon để làm việc trong môi trường CI.

// Cài đặt pods tạo Podfile + xcworkspace
./gradlew :shared:podInstall

// Build framework debug để kiểm thử
./gradlew :shared:podBuildDebugFramework

// Build iOS đầy đủ từ dòng lệnh
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) là một trình quản lý phụ thuộc thay thế của Apple đang trở nên phổ biến và dần thay thế CocoaPods trong cộng đồng iOS. Tuy nhiên, CocoaPods Plugin vẫn phù hợp vì một số lý do: SPM không hỗ trợ framework động trong ngữ cảnh KMM, và việc tích hợp framework Kotlin/Native qua SPM yêu cầu cấu hình bổ sung. CocoaPods Plugin cung cấp một đường dẫn tích hợp trưởng thành và có tài liệu đầy đủ hơn.

So sánh CocoaPods Plugin và tích hợp trực tiếp qua SPM cho thấy cái đầu tiên thắng về tự động hóa, trong khi cái thứ hai thắng về hỗ trợ gốc Apple. CocoaPods Plugin tự động tạo Podfile, quản lý phiên bản và cấu hình Xcode Build Phases. SPM yêu cầu kết nối thủ công framework Kotlin qua Package.swift, điều này khó bảo trì hơn cho các dự án KMM lớn. JetBrains đang làm việc trên hỗ trợ SPM cho Kotlin/Native, nhưng tính đến năm 2025, tích hợp SPM vẫn là thử nghiệm.

Các vấn đề thường gặp và giải pháp

Khi sử dụng CocoaPods Plugin, các nhà phát triển KMM gặp phải một số vấn đề điển hình. Xung đột phiên bản pod là vấn đề phổ biến nhất, khi hai pods yêu cầu các phiên bản khác nhau của cùng một phụ thuộc. Giải pháp là chỉ định rõ ràng phiên bản của phụ thuộc xung đột qua pod("Dependency") { version = "x.x" }. Trường hợp phổ biến thứ hai là không tương thích phiên bản, khi một pod yêu cầu iOS SDK mới hơn phiên bản tối thiểu của dự án KMM.

Các vấn đề với .xcworkspace phát sinh nếu bạn mở .xcodeproj thay vì .xcworkspace sau khi cấu hình plugin. Plugin cảnh báo về điều này trong nhật ký podInstall. Một lỗi thường gặp khác là thiếu CocoaPods trên máy phát triển. Plugin kiểm tra sự tồn tại của lệnh pod trước khi chạy podInstall và hiển thị thông báo lỗi rõ ràng. Đối với CI/CD, hãy cài đặt CocoaPods: gem install cocoapods.

// Giải quyết xung đột phiên bản
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Giải quyết xung đột một cách rõ ràng
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Kiểm tra cài đặt CocoaPods qua Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Phiên bản CocoaPods: $result")
    }
}

Gỡ lỗi podInstall

Nếu podInstall thất bại, hãy sử dụng cờ --info để có đầu ra chi tiết: ./gradlew podInstall --info. Plugin ghi nhật ký từng bước: tạo Podfile, thực thi pod install, phân tích Podfile.lock. Hầu hết các lỗi liên quan đến vấn đề mạng (CocoaPods Trunk không khả dụng) hoặc cú pháp Podfile không chính xác. Trong những trường hợp như vậy, hãy thử chạy pod install thủ công trong thư mục gốc của dự án để nhận được thông báo lỗi chi tiết hơn từ CocoaPods.