Bagaimana Migrasi Aplikasi Capacitor ke Pengelola Paket Swift

Capacitor 8 membuat proyek iOS baru dengan Pengelola Paket Swift (SPM) secara default. Aplikasi yang sudah ada yang masih menggunakan CocoaPods bisa juga di migrasi, tapi jalur yang paling aman tergantung pada seberapa banyak customisasi iOS native aplikasi Anda.

Panduan ini menjelaskan apa saja perubahan, apa yang harus dibackup, dan dua jalur migrasi yang praktis: menggunakan asisten migrasi Capacitor atau merekonstruksi proyek iOS dengan SPM.

Mengapa migrasi sekarang

CocoaPods sedang bergerak menuju truk baca-saja. Rencana saat ini adalah untuk truk CocoaPods tidak menerima podspecs baru lagi 2 Desember 2026Setelah perubahan, bangunan yang sudah ada harus tetap berfungsi, tetapi rilis baru dan pembaruan dependensi yang bergantung pada trunk tidak akan dipublikasikan lagi di sana.

SPM juga merupakan arah yang diambil oleh Capacitor. Capacitor telah mendukung memilih CocoaPods atau SPM sejak Capacitor 6, dan Capacitor 8 sekarang membuat proyek iOS SPM sebagai template default.

Apa yang berubah dalam proyek SPM Capacitor

Mengganti CocoaPods ke SPM mengganti lapisan dependensi iOS. Aplikasi web, proyek Android, dan sebagian besar perintah alur kerja Capacitor tetap sama.

CapApp-SPM menggantikan Podfile

Dalam aplikasi CocoaPods, dependensi iOS dihubungkan melalui ios/App/Podfile, Podfile.lock, Pods/dan file yang dihasilkan .xcworkspace.

Dalam aplikasi SPM, Capacitor membuat paket lokal bernama CapApp-SPMPaket ini menjadi tempat pusat di mana Capacitor mengacu pada dependensi plugin iOS native Anda. Capacitor CLI diperbarui CapApp-SPM Saat Anda sinkronkan plugin, jangan mengeditnya secara manual.

debug.xcconfig menggantikan konfigurasi Pods

The assistant migrasi juga membuat file yang dihasilkan debug.xcconfigFile ini membawa pengaturan pembangunan yang CocoaPods dulunya menyediakan melalui file xcconfig yang dihasilkannya.

Setelah migrasi, Anda mungkin perlu menambahkan debug.xcconfig ke pengaturan konfigurasi Xcode jika asisten memberitahu Anda untuk melakukannya.

Setiap plugin harus mendukung SPM

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

dan plugin Cordova jika belum mendukung SPM. capacitor-plugin-converterJika plugin tidak mendukung SPM, update, ganti, atau migrasi plugin terlebih dahulu. Plugin Swift sederhana sering dapat dikonversi dengan

, tetapi plugin dengan tata letak Objective-C dan Swift yang lebih kompleks mungkin memerlukan pekerjaan manual.

Apa yang harus disimpan terlebih dahulu

Mulai dari cabang Git yang bersih dan komitkan keadaan saat ini sebelum menyentuh proyek iOS. Kemudian daftar file native yang aplikasi Anda tergantung. ios/App/ File umum untuk diselamatkan dari

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, jika aplikasi Anda memiliki satu
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, jika Anda menggunakan Firebase
Pengaturan khusus .xcconfig berkas-berkas
Pengaturan tanda tangan, identifikasi paket, ID tim, dan pengaturan profil penyediaan

Juga simpan berkas-berkas Swift native, Objective-C, framework, ekstensi, atau SDK yang Anda tambahkan di luar template standar Capacitor.

Pilihan 1: Gunakan asisten migrasi Capacitor

Gunakan jalur ini ketika proyek iOS Anda memiliki edit native yang khusus yang Anda tidak ingin kehilangan.

Jalankan asisten dari root proyek Capacitor Anda:

bunx cap spm-migration-assistant

Asisten menghapus infrastruktur CocoaPods, membuat paket lokal, menghasilkan referensi paket dari plugin yang terinstal, dan membuat berkas konfigurasi SPM yang dihasilkan. CapApp-SPM Ketika selesai, buka proyek:

Asisten akan menghapus infrastruktur CocoaPods, membuat paket lokal, menghasilkan referensi paket dari plugin yang terinstal, dan membuat berkas konfigurasi SPM yang dihasilkan.

bunx cap open ios

Kemudian ikuti langkah-langkah manual Xcode yang dicetak oleh asisten. Pada proyek kebanyakan ini berarti:

Tambahkan CapApp-SPM sebagai dependensi paket lokal.
Tambahkan yang dihasilkan debug.xcconfig ke konfigurasi aplikasi.
Selesaikan peringatan tentang plugin yang tidak dapat dikonversi ke SPM.
Bangun aplikasi dari Xcode sekali sebelum memperbarui CI.

Setelah proyek Xcode dibangun, sinkronisasi lagi:

bunx cap sync ios

Option 2: Re-scaffold proyek iOS dengan SPM

Gunakan jalur ini ketika direktori Anda dekat dengan template default __CAPGO_KEEP_0__ dan Anda dapat aman mengembalikan file-file kustom setelahnya. ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

Gunakan jalur ini ketika direktori Anda dekat dengan template default __CAPGO_KEEP_0__ dan Anda dapat aman mengembalikan file-file kustom setelahnya.

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Kembalikan file native yang dibutuhkan aplikasi Anda, kemudian buka proyek:

bunx cap open ios

Jalur ini seringkali lebih bersih daripada migrasi in-place karena memberikan Anda template iOS segar Capacitor 8. Namun, Anda harus dengan hati-hati menerapkan tanda tangan, hak istimewa, file Firebase, perubahan kode native, dan pengaturan Xcode yang disesuaikan.

Aplikasi Capacitor baru

Untuk aplikasi baru, Capacitor 8 menggunakan SPM secara default ketika menambahkan iOS:

bunx cap add ios

Jika Anda perlu spesifik, Anda masih dapat melewati opsi manajer paket:

bunx cap add ios --packagemanager SPM

Perbarui CI setelah migrasi

Setelah aplikasi dibangun secara lokal, perbarui CI/CD sehingga tidak lagi mengasumsikan CocoaPods.

Hapus langkah yang menjalankan:

pod install

Juga hapus cache untuk:

ios/App/Pods
ios/App/Podfile.lock
Repositori spesifikasi CocoaPods, jika aliran kerja Anda menyimpannya hanya untuk aplikasi ini

Tetapkan langkah build web Anda dan Capacitor sinkronisasi. Langkah iOS biasanya harus menginstal dependensi JavaScript, membangun aset web, sinkronisasi Capacitor, dan kemudian membangun dengan Xcode:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Dokumen migrasi

Sebelum migrasi:

Buat cabang git baru.
Komit aplikasi kerja saat ini.
Pastikan setiap plugin yang terpasang mendukung SPM.
Rekam file-file iOS dan pengaturan tanda tangan khusus.
Pastikan aplikasi dapat dibangun sebelum migrasi.

Selama migrasi:

Jalankan bunx cap spm-migration-assistant atau re-susun ulang ios/.
Tambahkan CapApp-SPM di Xcode jika diperlukan.
Tambahkan debug.xcconfig di Xcode jika diperlukan.
Kembalikan file native aplikasi khusus.
Jalankan bunx cap sync ios.

Setelah migrasi:

Bangun dan jalankan aplikasi di Xcode.
Hapus file CocoaPods yang tersisa.
Hapus pod install dari CI.
Verifikasi tanda tangan rilis masih berfungsi.
Jalankan aplikasi di setidaknya satu simulator dan satu perangkat nyata sebelum mengirim.

Pengaturan Perbaikan

Jika Xcode tidak dapat menyelesaikan paket, reset cache paket dari Xcode dan jalankan bunx cap sync ios Jika migrasi gagal karena plugin, periksa apakah plugin tersebut memiliki rilis yang lebih baru dengan dukungan SPM. Untuk plugin yang Anda kelola, migrasikan terlebih dahulu paket plugin dan kemudian kembali ke migrasi aplikasi.

Ketika aplikasi dibangun secara lokal tetapi CI gagal, periksa asumsi CocoaPods yang ketinggalan zaman. Penyebab umum adalah jalur build yang dipaksakan, perintah yang ketinggalan zaman, atau caching dari build sebelumnya.

Kesimpulan .xcworkspace Mengganti aplikasi __CAPGO_KEEP_0__ ke Manager Paket Swift sebagian besar tentang mengganti pengaturan ketergantungan iOS. pod install SPM mengambil alih referensi ketergantungan, mengganti konfigurasi build CocoaPods yang dihasilkan, dan CI tidak lagi memerlukan Pods/ Untuk proyek iOS yang telah disesuaikan, mulai dengan

. Untuk proyek yang dekat dengan template default, rescaffold SPM yang bersih seringkali lebih cepat dan lebih mudah untuk dipahami.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM When the app builds locally but CI fails, check for old CocoaPods assumptions. Common causes are a forced debug.xcconfig build path, a stale pod install.

command, or caching bunx cap spm-migration-assistantfrom previous builds.

Sumber Daya

Lanjutkan dari Cara Migrasi Aplikasi Capacitor ke Pengelola Paket Swift

Jika Anda menggunakan Cara Migrasi Aplikasi Capacitor ke Pengelola Paket Swift untuk merencanakan migrasi dan operasi bisnis, hubungkannya dengan Capgo Enterprise untuk alur kerja produk di Capgo Enterprise Alternatif Plugin Bisnis Ionic untuk alur kerja produk di Alternatif Ionic Enterprise Plugin Capgo Alternatif untuk alur kerja produk di Capgo Alternatif Capgo Konsultasi untuk alur kerja produk di Capgo Konsultasi, dan Capgo Layanan Premium untuk alur kerja produk di Capgo Layanan Premium.