How to Menggunakan CocoaPods dengan Capacitor 8 (dan Kapan Bukan)

Menggunakan CocoaPods dengan Capacitor 8, buat platform iOS dengan bunx cap add ios --packagemanager CocoaPods, instal CocoaPods (Homebrew atau Gemfile dengan Bundler), dan biarkan bunx cap sync ios atur Podfile dan jalankan pod install. Capacitor 8 masih sepenuhnya mendukung CocoaPods. Hanya default untuk proyek baru berubah ke Swift Package Manager.

CocoaPods tidak lagi arah jangka panjang, dan cabangnya menjadi tidak dapat ditulis ulang pada tanggal 2 Desember 2026. Jadi pertanyaan yang sebenarnya adalah kapan CocoaPods masih merupakan pilihan yang tepat, bagaimana menjadikannya berfungsi, dan bagaimana meninggalkannya dengan bersih. Panduan ini mencakup semua tiga hal.

Kapan CocoaPods masih merupakan pilihan yang tepat

Tetapkan CocoaPods, atau pilih CocoaPods, ketika salah satu kondisi ini benar:

• Sebuah plugin yang dibutuhkan tidak Package.swift. Dalam proyek SPM, CLI mengeluarkan peringatan “Beberapa plugin Capacitor yang diinstal tidak kompatibel dengan SPM” dan meninggalkan plugin tersebut, sehingga gagal pada waktu runtime dengan pesan “plugin tidak diimplementasikan”.
• Sebuah vendor SDK hanya didistribusikan dalam bentuk pod. Beberapa SDK analitik, pembayaran, dan identitas masih mengirimkan CocoaPods-only, atau mengirimkan xcframework yang harus Anda wrap sendiri.
• Sebuah plugin Cordova bergantung pada pods. Capacitor menghasilkan paket Swift untuk plugin Cordova dalam proyek SPM, tetapi plugin yang kompleks dengan <podspec> tergantung cenderung lebih baik dengan CocoaPods.
• Anda bergantung pada subspec podspec to pick SDK variants. SPM has package traits now, and Capacitor supports them experimentally since CLI 8.3 (see Sifat Paket SPM di CapacitorTetapi plugin harus mendefinisikan karakteristik terlebih dahulu.
• Proyek Xcode yang besar dan disesuaikan Tapi plugin harus mendefinisikan fitur tersebut terlebih dahulu.

Kolisi identitas paket sebelumnya sering menjadi masalah. Sejak CLI 8.4, Anda dapat mengatasi masalah ini dengan menggunakan SPM. experimental.ios.spm.packageOptions (symlink or moduleAliases) di konfigurasi Capacitor Anda.

Jika tidak ada yang berlaku, gunakan SPM. Ini tidak memerlukan toolchain Ruby, tidak ada Podfile dan tidak .xcworkspace.

dalam konfigurasi Capacitor Anda.

Instal CocoaPods

Pilih satu pendekatan dan gunakan di mana-mana, termasuk CI.

Homebrew (termudah untuk satu pengembang):

brew install cocoapods
pod --version

Bundler (mengunci versi untuk tim seluruhnya, direkomendasikan untuk CI). Buat sebuah Gemfile dalam direktori root proyek atau di ios/App:

source 'https://rubygems.org'
gem 'cocoapods', '~> 1.16'

bundle install

Ketika Capacitor CLI menemukan sebuah Gemfile yang menyebutkan CocoaPods, maka ia menjalankan bundle exec pod install sebaliknya dari pod installJika pod hidup di tempat yang tidak biasa, atur CAPACITOR_COCOAPODS_PATH ke arah file biner.

Buatlah sebuah Capacitor 8 aplikasi dengan CocoaPods

bun add @capacitor/ios
bun run build
bunx cap add ios --packagemanager CocoaPods
bunx cap open ios

cap open ios membuka App.xcworkspaceSelalu bangun dari workspace. Membuka App.xcodeproj langsung akan memberikan Anda No such module 'Capacitor'.

The Podfile, dijelaskan

Ini adalah Podfile Capacitor 8 yang menghasilkan:

require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'

platform :ios, '15.0'
use_frameworks!

install! 'cocoapods', :disable_input_output_paths => true

def capacitor_pods
  pod 'Capacitor', :path => '../../node_modules/@capacitor/ios'
  pod 'CapacitorCordova', :path => '../../node_modules/@capacitor/ios'
end

target 'App' do
  capacitor_pods
  # Add your Pods here
end

post_install do |installer|
  assertDeploymentTarget(installer)
end

Apa yang bisa dan tidak bisa Anda sentuh:

• def capacitor_pods ... end CLI milik Anda. Pada setiap sinkronisasi, itu mengganti blok seluruhnya dengan satu. pod Apapun yang Anda tambahkan di dalamnya akan hilang. node_modulesTambahkan pod Anda di bawah
• Tambahkan pod milik Anda di bawah target 'App', after capacitor_pods.
• assertDeploymentTarget raises any pod with a deployment target below 15.0 up to 15.0, which avoids Xcode warnings about unsupported targets. Keep it, and add your own post_install Contoh dengan pod tambahan dan perbaikan pengaturan build:
• platform :ios harus setidaknya 15.0 untuk Capacitor 8.

Contoh dengan pod tambahan dan perbaikan pengaturan build:

target 'App' do
  capacitor_pods
  pod 'GoogleMLKit/BarcodeScanning', '~> 7.0'
end

post_install do |installer|
  assertDeploymentTarget(installer)
  installer.pods_project.targets.each do |target|
    if target.respond_to?(:product_type) && target.product_type == 'com.apple.product-type.bundle'
      target.build_configurations.each do |config|
        config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
      end
    end
  end
end

Lingkaran ini mematikan tanda tangan code untuk target bundle sumber daya. Signing for "X" requires a development team Tambahkan pods yang mengirimkan paket sumber. Tambahkan hanya jika Anda mengalami kesalahan tersebut.

Perintah Sehari-Hari

# After installing or removing a plugin
bunx cap sync ios

# Use the exact versions in Podfile.lock (good for CI)
bunx cap sync ios --deployment

# Refresh the spec repo when a new pod version isn't found
cd ios/App && pod repo update && pod install

# Update one pod past its locked version
cd ios/App && pod update FirebaseMessaging

cap sync ios Hari ke hari xcodebuild clean juga menjalankan pod installTidak perlu melakukan pembersihan manual setelah menambahkan plugin.

Commit Podfile Commit Podfile.lockJangan commit ios/App/Pods/Ditambahkannya. pod install.

Mengganti aplikasi yang sudah ada dari SPM ke CocoaPods

Tidak ada perintah migrasi balik. Lakukan secara manual:

1. Commit, lalu salin ios/ di tempat yang aman.
2. Delete ios/.
3. Jalankan bunx cap add ios --packagemanager CocoaPods.
4. Reaplikasikan perubahan asli: Info.plist identitas aplikasi, ikon aplikasi dan aset splash, skema URL, ekstensi (widget, layanan notifikasi), dan kode Swift kustom apapun AppDelegate.
5. bunx cap sync ios dan buat.

Mengidentifikasi Perbedaan Lama dan Baru ios/App/App folder adalah cara tercepat untuk menangkap apa yang Anda lewatkan.

Mengatasi Masalah CocoaPods yang Umum

CocoaPods could not find compatible versions for pod "X". Spec lokal Anda sudah ketinggalan atau dua pod memerlukan versi yang tidak kompatibel. Jalankan pod install --repo-update in ios/Appdi dalamnya. Jika masih gagal, baca rantai dependensi dalam kesalahan, cari plugin dengan pin yang ketat, upgrade atau perbaiki spesifikasinya pod.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. Artikel ini Pods folder tidak sesuai dengan file penahan, biasanya setelah berganti cabang. Jalankan bunx cap sync ios.

[!] Unable to find a specification for 'X'. Repositori spec sudah ketinggalan zaman atau nama pod salah. Jalankan pod repo update.

Unable to find compatibility version string for object version '70' (atau 77Project Xcode Anda menggunakan format yang lebih baru daripada CocoaPods/xcodeproj gem memahami. Perbarui CocoaPods ke versi terbaru. Jika tidak mungkin, lakukan backup terlebih dahulu project.pbxproj dan atur objectVersion ke nilai yang didukung oleh CocoaPods.

Sandbox: rsync(...) deny(1) file-write-create. Sandbox pengguna Xcode menghalangi skrip CocoaPods untuk diintegrasikan. dan tetapkan, set Penggunaan Skrip Penggunaan Sandi (ENABLE_USER_SCRIPT_SANDBOXING) to Tidak untuk target App.

No such module 'Capacitor'. Anda telah membuka App.xcodeproj. Buka App.xcworkspace, atau jalankan bunx cap open ios.

pod: command not found di CI. Instal CocoaPods di pekerjaan, atau gunakan Bundler dengan cache vendor/bundle. Tanpa itu, log CLI “Mengabaikan instalasi pod karena CocoaPods tidak terinstal” dan pembangunan gagal kemudian.

Beberapa kesalahan build iOS lainnya dibahas di Capacitor iOS troubleshooting guide.

Tanggal Baca-Only CocoaPods Trunk

Para pemelihara CocoaPods mengumumkan bahwa trunk, repositori spesifikasi pusat, menjadi tidak dapat ditulis pada 2 Desember 2026, setelah tes di awal November 2026. Apa itu berarti untuk sebuah aplikasi Capacitor:

• Bangunan yang sudah ada tetap berfungsi. Setiap spesifikasi pod yang dipublikasikan tetap tersedia.
• Tidak ada versi baru melalui trunk. SDK yang Anda pull dari trunk (Firebase, Google ML Kit, SDK vendor) berhenti mendapatkan pembaruan di sana. Perbaikan keamanan dan dukungan iOS SDK baru hanya akan dikirim melalui SPM atau saluran lain.
• Plugin Capacitor sendiri tidak terpengaruh langsung. Mereka diinstal dari npm dan dirujuk oleh :path di Podfile. Ketergantungan pod transitifnya adalah.

Tangani CocoaPods sebagai jembatan. Daftarkan ketergantungan yang membuat Anda tetap di sana, dan ulangi ketika ketergantungan itu menambah dukungan SPM.

Pindah dari CocoaPods

Ketika Anda siap:

bunx cap spm-migration-assistant

Itu berjalan pod deintegratedan menghapus Podfile, Podfile.lock dan App.xcworkspace, creates CapApp-SPManda menambahkan debug.xcconfigAnda kemudian menambahkan CapApp-SPM sebagai paket lokal di Xcode dan atur debug.xcconfig Konfigurasi Debug file. Langkah-langkah lengkapnya dapat ditemukan di Bagaimana cara migrasi aplikasi Capacitor Anda ke SPMmigrasi plugin __CAPGO_KEEP_0__ ke SPM SPM vs CocoaPods untuk Capacitor.

Penulis plugin yang memerlukan dukungan SPM harus membaca migrasikan sebuah plugin Capacitor ke SPM.

Jika mengelola Ruby, CocoaPods, dan Xcode pada mesin pembangunan adalah bagian yang menyakitkan, Capgo Bangun membangun CocoaPods dan SPM proyek di awan pada Xcode saat ini.