Bagaimana Migrasi Aplikasi Capacitor ke Pengelola Paket Swift

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

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

Mengapa migrasi sekarang?

CocoaPods akan bergerak menuju truk baca-saja. Rencana saat ini adalah CocoaPods trunk akan berhenti menerima podspecs baru pada 2 Desember 2026. Pembangunan yang ada seharusnya tetap berfungsi, tetapi rilis baru dan pembaruan dependensi yang bergantung pada truk tidak akan dipublikasikan di sana setelah perubahan.

SPM juga adalah arah yang Capacitor sedang mengambil. Capacitor telah mendukung memilih CocoaPods atau SPM sejak Capacitor 6, dan Capacitor 8 sekarang membuat proyek iOS SPM sebagai template default.

Apa perubahan yang terjadi dalam proyek Capacitor SPM

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

CapApp-SPM mengganti Podfile

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

Dalam aplikasi SPM, Capacitor membuat paket lokal bernama CapApp-SPM. Paket ini menjadi tempat pusat di mana Capacitor mengacu pada dependensi plugin iOS native Anda. Capacitor CLI diperbarui CapApp-SPM ketika Anda sinkronkan plugin, jadi lihatlah sebagai output yang dihasilkan dan hindari mengeditnya secara manual.

debug.xcconfig menggantikan konfigurasi Pods

Asisten migrasi juga membuat file yang dihasilkan debug.xcconfig File ini membawa pengaturan pembangunan yang CocoaPods dahulu menyediakan melalui file xcconfig yang dihasilkannya.

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

Setiap plugin harus mendukung SPM

Tidak dapat campuran CocoaPods dan SPM di proyek iOS yang sama Capacitor. Sebelum melakukan migrasi, periksa setiap Capacitor dan plugin Cordova di package.json.

Jika plugin tidak mendukung SPM yet, update, ganti, atau migrasi plugin terlebih dahulu. Plugin Swift sederhana sering dapat dikonversi dengan Ionic’s capacitor-plugin-converter, tetapi plugin dengan tata letak Objective-C dan Swift yang lebih kompleks mungkin memerlukan pekerjaan manual.

Apa yang harus dibackup terlebih dahulu

Mulai dari cabang Git yang bersih dan komitkan keadaan saat ini sebelum menyentuh proyek iOS. Kemudian daftar file native yang aplikasi Anda bergantung.

File umum untuk dipertahankan dari ios/App/ termasuk:

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
Custom .xcconfig berkas-berkas
Pengaturan tanda tangan, identifikasi paket, ID tim, dan pengaturan profil penyediaan

Juga simpan berkas-berkas native Swift, 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 diinginkan dan 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 file konfigurasi SPM yang dihasilkan. CapApp-SPM Pilihan 2: Gunakan jalur ini ketika Anda tidak ingin kehilangan pengaturan tanda tangan, identifikasi paket, ID tim, dan pengaturan profil penyediaan.

Setelah selesai, buka proyek:

bunx cap open ios

Lalu ikuti langkah-langkah manual Xcode yang dicetak oleh asisten. Pada umumnya ini berarti:

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

Setelah proyek Xcode dibangun, sinkron ulang lagi:

bunx cap sync ios

Pilihan 2: Re-susun kembali proyek iOS dengan SPM

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

Terlebih dahulu, pastikan file-file yang tercantum dalam bagian backup telah dikomit atau dicopy ke tempat yang aman. Kemudian hapus dan buat kembali proyek iOS dengan SPM:

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

Mengembalikan file-file native yang dibutuhkan aplikasi Anda, kemudian buka proyek:

bunx cap open ios

Jalur ini seringkali lebih bersih daripada migrasi di tempat karena memberikan Anda template iOS yang segar Capacitor 8. Namun, Anda harus dengan hati-hati menerapkan kembali tanda tangan, hak istimewa, file Firebase, perubahan kode sumber 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 untuk menentukan secara eksplisit, Anda masih dapat melewati opsi manajer paket:

bunx cap add ios --packagemanager SPM

Perbarui CI setelah migrasi

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

Hapus langkah-langkah yang menjalankan:

pod install

Juga hapus cache untuk:

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

Keep your regular web build and Capacitor sync steps. A typical iOS job should install JavaScript dependencies, build the web assets, sync Capacitor, and then build with Xcode:

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

Daftar checklist migrasi

Sebelum migrasi:

Buat cabang git baru.
Commit aplikasi kerja saat ini.
Pastikan setiap plugin yang terinstal mendukung SPM.
Catat file-file iOS yang diatur sendiri dan pengaturan tanda tangan.
Pastikan aplikasi dapat dibangun sebelum migrasi.

Selama migrasi:

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

Setelah migrasi:

Buat dan jalankan aplikasi di Xcode.
Menghapus 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 Masalah

Jika Xcode tidak dapat menyelesaikan paket, reset cache paket dari Xcode dan jalankan lagi. bunx cap sync ios lagi.

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 sudah ketinggalan zaman. Penyebab umum adalah jalur pembangunan paksa, perintah yang sudah ketinggalan zaman, atau caching dari bangunan sebelumnya. .xcworkspace Kesimpulan pod install Migrasi aplikasi __CAPGO_KEEP_0__ ke Swift Package Manager sebagian besar tentang mengganti pengaturan ketergantungan iOS. Pods/ SPM mengambil alih referensi ketergantungan, mengganti konfigurasi pembangunan CocoaPods yang dihasilkan, dan CI tidak lagi memerlukan

Untuk proyek iOS yang disesuaikan, mulai dengan

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM SPM mengambil alih referensi ketergantungan, mengganti konfigurasi pembangunan CocoaPods yang dihasilkan, dan CI tidak lagi memerlukan debug.xcconfig Untuk proyek iOS yang disesuaikan, mulai dengan pod install.

mengganti pengaturan ketergantungan iOS. bunx cap spm-migration-assistant. Untuk proyek yang dekat dengan template default, re-scaffolding SPM yang bersih seringkali lebih cepat dan lebih mudah dipahami.