ติดต่อ : @ivanzamzam

CocoaPods Plugin — คืออะไร ปลั๊กอินสำหรับ KMM และการตั้งค่า

ความรู้
ข้อมูลเฉพาะข้ามแพลตฟอร์ม
CocoaPods Plugin
ผู้แต่ง: IT Sectr เผยแพร่เมื่อ: 2026-06-05 เวลาอ่าน: 8 นาที

CocoaPods Plugin เป็นปลั๊กอิน Gradle สำหรับ Kotlin Multiplatform Mobile ที่ผสานรวมตัวจัดการการพึ่งพา CocoaPods เข้ากับระบบบิลด์ของโปรเจกต์ KMM โดยตรง ปลั๊กอินช่วยให้คุณประกาศการพึ่งพา iOS (pods) ได้โดยตรงใน build.gradle.kts สร้าง Podfile โดยอัตโนมัติ ติดตั้ง pods และเชื่อมโยงกับโค้ด Kotlin แทนการจัดการ .xcworkspace ด้วยตนเอง นักพัฒนาจัดการการพึ่งพา iOS ผ่าน Gradle ทำให้การตั้งค่าโปรเจกต์ KMM สามารถทำซ้ำได้อย่างสมบูรณ์ ตามข้อมูลจาก JetBrains, 2025 ปลั๊กอินถูกใช้ใน 20% ของโปรเจกต์ KMM เพื่อจัดการไลบรารี iOS

ประเด็นสำคัญ

  • CocoaPods Plugin เป็นปลั๊กอิน Gradle สำหรับผสานรวม CocoaPods กับ Kotlin Multiplatform Mobile
  • ระบบอัตโนมัติ — ปลั๊กอินสร้าง Podfile และจัดการการพึ่งพา pod จาก Gradle
  • Podfile คือไฟล์กำหนดค่า CocoaPods ที่ปลั๊กอินสร้างและดูแลโดยอัตโนมัติ
  • .xcworkspace คือพื้นที่ทำงาน Xcode ที่ปลั๊กอินสร้างขึ้นเพื่อผสานรวมกับโปรเจกต์ iOS
  • การผสานรวม KMM — ปลั๊กอินเชื่อมโยงเฟรมเวิร์ก Kotlin/Native กับการพึ่งพา pod iOS

CocoaPods Plugin คืออะไร?

CocoaPods Plugin (หรือที่รู้จักในชื่อ kotlin.cocoapods) เป็นปลั๊กอินอย่างเป็นทางการของ JetBrains สำหรับผสานรวม CocoaPods กับ Kotlin Multiplatform Mobile ปลั๊กอินเป็นส่วนหนึ่งของ Kotlin Gradle DSL และกำหนดค่าได้โดยตรงใน build.gradle.kts ของโมดูล KMM โดยจะทำให้การสร้างและการดูแล Podfile การสร้าง .xcworkspace และการจัดการการพึ่งพา pod เป็นไปโดยอัตโนมัติ ลดความจำเป็นในการกำหนดค่าโปรเจกต์ Xcode ด้วยตนเอง

ก่อน CocoaPods Plugin นักพัฒนา KMM ต้องสร้าง Podfile ด้วยตนเอง รัน pod install กำหนดค่า bridge headers และติดตามเวอร์ชัน pod แยกจากการพึ่งพา Gradle ซึ่งนำไปสู่การไม่ตรงกันของเวอร์ชันและความยุ่งยากในไปป์ไลน์ CI/CD ปลั๊กอินแก้ปัญหาเหล่านี้โดยทำให้การจัดการการพึ่งพา iOS ง่ายเท่ากับการจัดการการพึ่งพา Gradle ในโมดูล Android

ปลั๊กอินรองรับทั้ง pods สาธารณะจาก CocoaPods Trunk และ pods ที่กำหนดเองจากพื้นที่เก็บข้อมูลส่วนตัว การทำงานกับ Podspec ในเครื่อง และพื้นที่เก็บข้อมูลที่ใช้ git ก็รองรับเช่นกัน ปลั๊กอินเข้ากันได้กับ Kotlin 1.6.0 ขึ้นไป และต้องติดตั้ง CocoaPods (gem install cocoapods) บนเครื่องพัฒนา

CocoaPods Plugin ทำงานอย่างไร

CocoaPods Plugin ทำงานในระดับ task-graph ของ Gradle โดยเพิ่มงานเฉพาะทางสำหรับการทำงานกับ CocoaPods งานหลักประกอบด้วย podInstall (การติดตั้ง pods), podGenXcodeWorkspace (การสร้าง .xcworkspace) และ podBuildDebugFramework (การสร้างเฟรมเวิร์กเวอร์ชัน Debug) ปลั๊กอินวิเคราะห์ส่วน cocoapods ใน build.gradle.kts สร้าง Podfile ตามการพึ่งพาที่ประกาศไว้ และรัน pod install ด้วยพารามิเตอร์ที่จำเป็น

สถาปัตยกรรมของปลั๊กอินประกอบด้วยสามส่วน: ส่วนขยาย DSL สำหรับ build.gradle.kts, ตัวสร้าง Podfile สำหรับสร้าง Podfile และ ชั้นการผสานรวม Xcode สำหรับกำหนดค่า .xcworkspace ส่วนขยาย DSL มีบล็อก cocoapods { } พร้อมฟังก์ชัน pod() ที่ซ้อนกันสำหรับประกาศการพึ่งพา specRepo() สำหรับระบุพื้นที่เก็บข้อมูลส่วนตัว และ framework { } สำหรับกำหนดค่าเฟรมเวิร์กเอาต์พุต ตัวสร้าง Podfile แปลงการประกาศเหล่านี้เป็นไวยากรณ์ Ruby ที่ CocoaPods เข้าใจ

kotlin 
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 ในการรันครั้งต่อ ๆ ไปโดยไม่มีการเปลี่ยนแปลงการกำหนดค่า podInstall จะถูกข้ามหาก Podfile.lock ไม่มีการเปลี่ยนแปลง ซึ่งช่วยประหยัดเวลาใน CI/CD ที่ pod install อาจใช้เวลาถึง 2-3 นาทีสำหรับการติดตั้งใหม่

การตั้งค่า CocoaPods Plugin ในโปรเจกต์ KMM

การตั้งค่า CocoaPods Plugin ต้องทำหลายขั้นตอน การติดตั้ง CocoaPods บนเครื่องพัฒนา (gem install cocoapods) เป็นข้อกำหนดเบื้องต้น จากนั้นใน build.gradle.kts ของโมดูลที่ใช้ร่วมกัน ให้เพิ่มบล็อก cocoapods { } พร้อมการกำหนดค่าเฟรมเวิร์กและการพึ่งพา หลังจากกำหนดค่าแล้ว ให้รันงาน podInstall ซึ่งจะสร้าง Podfile และติดตั้ง pods .xcworkspace ที่สร้างขึ้นจะอยู่ในรูทโปรเจกต์ถัดจาก Podfile

ปลั๊กอินผสานรวมกับ Xcode Build Phases เมื่อสร้างแอป iOS Xcode จะรัน embedAndSignAppleFrameworkForXcode — งานที่คัดลอกเฟรมเวิร์ก Kotlin/Native ไปยังบันเดิลแอป CocoaPods Plugin เพิ่ม build phase นี้โดยอัตโนมัติเมื่อสร้าง .xcworkspace หากสร้าง .xcworkspace แล้ว จะต้องเปิดแทน .xcodeproj เพื่อการบิลด์ที่ถูกต้องกับการพึ่งพา pod

ขั้นตอนคำอธิบายคำสั่ง / การดำเนินการ
1ติดตั้ง CocoaPodsgem install cocoapods
2เพิ่มปลั๊กอินใน build.gradle.ktskotlin { cocoapods { ... } }
3ประกาศ podspod("Alamofire") { version = "5.9.0" }
4สร้าง Podfile./gradlew :shared:podInstall (อัตโนมัติ)
5เปิด .xcworkspaceแทน .xcodeproj
6สร้างแอป iOSXcode Build (⌘B)

ตัวอย่างโค้ด: การกำหนดค่า pod

มาดูสถานการณ์ต่าง ๆ สำหรับการประกาศ pods ใน CocoaPods Plugin กรณีพื้นฐานคือการเชื่อมต่อ pod สาธารณะจาก CocoaPods Trunk พร้อมระบุเวอร์ชัน สถานการณ์ที่ซับซ้อนมากขึ้นรวมถึงการใช้ podspec ที่กำหนดเอง pods ในเครื่อง และ pods จากพื้นที่เก็บข้อมูล git

kotlin 
kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // pod สาธารณะจาก CocoaPods Trunk
        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")

        // pod จากพื้นที่เก็บข้อมูล git
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

การเชื่อมต่อ pods เป็นเพียงส่วนหนึ่งของการกำหนดค่า ปลั๊กอินยังช่วยให้คุณ ส่งออก การพึ่งพาจากโมดูล Kotlin อื่นไปยังเฟรมเวิร์ก iOS ฟังก์ชัน export(project(":core")) ระบุว่า API สาธารณะทั้งหมดของโมดูล :core ควรเข้าถึงได้จากส่วนหัว Objective-C ของเฟรมเวิร์กที่สร้างขึ้น ซึ่งจำเป็นเมื่อโค้ด Kotlin ที่ใช้ร่วมกันใช้คลาสจากโมดูลอื่นและต้องเข้าถึงได้จาก Swift

kotlin 
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

kotlin 
// การติดตั้ง pods สร้าง Podfile + xcworkspace
./gradlew :shared:podInstall

// สร้างเฟรมเวิร์ก debug สำหรับการทดสอบ
./gradlew :shared:podBuildDebugFramework

// การบิลด์ iOS เต็มรูปแบบจากบรรทัดคำสั่ง
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin เทียบกับ Swift Package Manager

Swift Package Manager (SPM) เป็นตัวจัดการการพึ่งพาทางเลือกของ Apple ที่กำลังได้รับความนิยมและค่อย ๆ แทนที่ CocoaPods ในชุมชน iOS อย่างไรก็ตาม CocoaPods Plugin ยังคงมีความเกี่ยวข้องด้วยเหตุผลหลายประการ: SPM ไม่รองรับเฟรมเวิร์กแบบไดนามิกในบริบท KMM และการผสานรวมเฟรมเวิร์ก Kotlin/Native ผ่าน SPM ต้องการการกำหนดค่าเพิ่มเติม CocoaPods Plugin มอบเส้นทางการผสานรวมที่สมบูรณ์และมีเอกสารครบถ้วนกว่า

การเปรียบเทียบ ระหว่าง CocoaPods Plugin และการผสานรวมโดยตรงผ่าน SPM แสดงให้เห็นว่าแบบแรกชนะในด้านระบบอัตโนมัติ ในขณะที่แบบหลังชนะในด้านการรองรับ Apple โดยกำเนิด CocoaPods Plugin สร้าง Podfile โดยอัตโนมัติ จัดการเวอร์ชัน และกำหนดค่า Xcode Build Phases SPM ต้องการการเชื่อมต่อเฟรมเวิร์ก Kotlin ด้วยตนเองผ่าน Package.swift ซึ่งยากต่อการบำรุงรักษาสำหรับโปรเจกต์ KMM ขนาดใหญ่ JetBrains กำลังทำงานเกี่ยวกับการรองรับ SPM สำหรับ Kotlin/Native แต่ในปี 2025 การผสานรวม SPM ยังคงเป็นการทดลอง

คุณลักษณะCocoaPods PluginSwift Package Manager
ความสมบูรณ์พร้อมใช้งานจริงทดลอง
การสร้าง Podfileอัตโนมัติไม่เกี่ยวข้อง
เฟรมเวิร์กไดนามิกรองรับจำกัด
การตั้งค่า CI/CDง่าย (งาน Gradle)ต้องการขั้นตอนด้วยตนเอง
พื้นที่เก็บข้อมูลส่วนตัวรองรับ (specRepo)รองรับ (URL)
การรองรับ Apple โดยกำเนิดผ่าน CocoaPodsโดยกำเนิด

ปัญหาทั่วไปและวิธีแก้ไข

เมื่อใช้ CocoaPods Plugin นักพัฒนา KMM พบปัญหาทั่วไปหลายประการ ข้อขัดแย้งของเวอร์ชัน pod เป็นปัญหาที่พบบ่อยที่สุด เมื่อสอง pods ต้องการเวอร์ชันที่แตกต่างกันของการพึ่งพาเดียวกัน วิธีแก้ไขคือระบุเวอร์ชันของการพึ่งพาที่ขัดแย้งอย่างชัดเจนผ่าน pod("Dependency") { version = "x.x" } กรณีทั่วไปที่สองคือความไม่เข้ากันของเวอร์ชัน เมื่อ pod ต้องการ iOS SDK ที่ใหม่กว่าเวอร์ชันต่ำสุดของโปรเจกต์ KMM

ปัญหากับ .xcworkspace เกิดขึ้นหากคุณเปิด .xcodeproj แทน .xcworkspace หลังจากกำหนดค่าปลั๊กอิน ปลั๊กอินจะเตือนเกี่ยวกับเรื่องนี้ในบันทึก podInstall ข้อผิดพลาดที่พบบ่อยอีกประการคือการไม่มี CocoaPods บนเครื่องพัฒนา ปลั๊กอินจะตรวจสอบคำสั่ง pod ก่อนรัน podInstall และแสดงข้อความแสดงข้อผิดพลาดที่ชัดเจน สำหรับ CI/CD ให้ติดตั้ง CocoaPods: gem install cocoapods

kotlin 
// แก้ไขข้อขัดแย้งของเวอร์ชัน
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // แก้ไขข้อขัดแย้งอย่างชัดเจน
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// ตรวจสอบการติดตั้ง CocoaPods ผ่าน Gradle
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

คำถามที่พบบ่อย

ฉันต้องใช้ CocoaPods Plugin หรือไม่หากใช้แค่ Swift Package Manager?

หากการพึ่งพา iOS ทั้งหมดจัดการผ่าน SPM ก็ไม่จำเป็นต้องใช้ CocoaPods Plugin ปลั๊กอินจำเป็นสำหรับการผสานรวมกับ CocoaPods JetBrains กำลังทำงานเกี่ยวกับการรองรับ SPM แต่ในปี 2025 ยังคงเป็นการทดลอง

CocoaPods Plugin ส่งผลต่อเวลาบิลด์อย่างไร?

เวลาบิลด์ เพิ่มขึ้นเฉพาะในระหว่างการรัน podInstall ครั้งแรก (การสร้าง Podfile + การติดตั้ง pods) การบิลด์ครั้งต่อ ๆ ไปใช้แคช Podfile.lock การบิลด์เฟรมเวิร์ก Kotlin/Native เองไม่ได้ขึ้นอยู่กับ pods

ฉันสามารถใช้พื้นที่เก็บข้อมูล podspec ส่วนตัวได้หรือไม่?

ได้ ปลั๊กอินรองรับฟีเจอร์ specRepo สำหรับเชื่อมต่อพื้นที่เก็บข้อมูลส่วนตัว ระบุ URL และชื่อพื้นที่เก็บข้อมูลใน specRepo จากนั้น pods จากพื้นที่เก็บข้อมูลนั้นจะพร้อมสำหรับการประกาศ

จะทำอย่างไรหาก podInstall ล้มเหลว?

รัน pod install ด้วยตนเองในรูทโปรเจกต์เพื่อรับข้อความแสดงข้อผิดพลาดโดยละเอียด ตรวจสอบการเชื่อมต่อกับ CocoaPods Trunk ความถูกต้องของเวอร์ชัน pod และการมีอยู่ของ Ruby บนเครื่อง

ควรคอมมิต Podfile.lock ไปยัง git หรือไม่?

ใช่ ควรคอมมิต Podfile.lock เพื่อการบิลด์ที่สามารถทำซ้ำได้ CocoaPods Plugin สร้าง Podfile แต่ Podfile.lock ล็อกเวอร์ชัน pod ที่แน่นอนที่ติดตั้งระหว่าง pod install

สรุป

  • CocoaPods Plugin เป็นปลั๊กอิน Gradle สำหรับผสานรวม CocoaPods กับ KMM ทำให้การจัดการการพึ่งพา iOS เป็นไปโดยอัตโนมัติ
  • Podfile และ .xcworkspace ถูกสร้างโดยอัตโนมัติโดยงาน podInstall ไม่จำเป็นต้องกำหนดค่า Xcode ด้วยตนเอง
  • การกำหนด�าที่ยืดหยุ่น รองรับ pods สาธารณะ specRepo ส่วนตัว การพึ่งพาในเครื่องและแบบ git
  • การส่งออกโมดูล ผ่าน export() ทำให้ API โมดูล Kotlin เข้าถึงได้จาก Objective-C/Swift
  • การเชื่อมโยงแบบสแตติกและไดนามิก พร้อมใช้งานผ่านการกำหนดค่า isStatic ของเฟรมเวิร์ก
  • CI/CD รองรับผ่านกราฟงาน Gradle พร้อมแคช Podfile.lock เพื่อเร่งการบิลด์ครั้งต่อ ๆ ไป
  • ใช้ CocoaPods Plugin หากโปรเจกต์ KMM ของคุณมีการพึ่งพา iOS ที่จัดการผ่าน CocoaPods แทน SPM

เราจะพัฒนาแอปพลิเคชันบนมือถือแบบครบวงจร

IT Sectr สร้างแอปพลิเคชัน iOS และ Android สำหรับสตาร์ทอัพและธุรกิจตั้งแต่ปี 2017 เราจะให้คำแนะนำและเสนอวิธีแก้ปัญหาที่ดีที่สุดแก่คุณ

ปรึกษาโครงการ

อ่านเพิ่มเติม

Codegen: คืออะไร การสร้างโค้ด และบทบาทใน Fabric →
expect/actual — แนวคิด กลไก และการทำงานใน KMM →
XCFramework: คืออะไร รูปแบบและการประยุกต์ใช้ในการพัฒนา →
ฟีเจอร์ครีปในการพัฒนา — คืออะไร สาเหตุ และวิธีต่อสู้ →
โค้ดขยะในการพัฒนา — คืออะไร สัญญาณ และวิธีการจัดการ →