Bagaimana Migrasi Aplikasi Capacitor Anda ke Pengelola Paket Swift

Pengelola Paket Swift adalah arah default untuk proyek Capacitor iOS. Jika aplikasi Anda masih menggunakan CocoaPods, Anda dapat memindahkan aplikasi itu sendiri ke SPM tanpa harus membangun kembali proyek JavaScript code, proyek Android, atau alur rilis dari awal.

Petunjuk ini untuk tim aplikasi. Ini menjelaskan cara memindahkan aplikasi Capacitor iOS dari CocoaPods ke SPM, apa yang berubah dalam asisten migrasi, apa yang masih perlu Anda cek di Xcode, dan bagaimana membersihkan CI setelah aplikasi dibangun.

Apa yang berubah di aplikasi

Aplikasi Capacitor yang berbasis CocoaPods bergantung pada file seperti:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

Aplikasi berbasis SPM Capacitor memindahkan pengaturan dependensi iOS ke dalam Swift Package Manager. Selama migrasi, Capacitor membuat paket lokal bernama CapApp-SPM dan menggunakan paket tersebut untuk menghubungkan target aplikasi dengan Capacitor dan dependensi native yang diinstal.

Build web masih berjalan dengan cara yang sama. Anda masih menjalankan build web, sinkron Capacitor, membuka Xcode, dan mengarsipkan aplikasi. Perbedaan utama adalah bahwa CocoaPods tidak lagi mengontrol grafik dependensi iOS.

Sebelum melakukan migrasi

Mulai dari cabang bersih dan pastikan aplikasi saat ini dapat dibangun sebelum mengubah manajer dependensi:

git status
npm run build
npx cap sync ios

Lalu komitkan keadaan yang berjalan. Migrasi ini menyentuh file proyek iOS yang dihasilkan, sehingga memiliki titik rollback yang bersih sangat penting.

Kemudian, tinjau apa yang telah diubah oleh aplikasi Anda di bawah ios/App/File dan pengaturan umum yang perlu diselamatkan termasuk:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, jika ada
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, jika Anda menggunakan Firebase
file .xcconfig file
pengaturan tanda tangan, identifikasi paket, ID tim, dan profil penyediaan
ekstensi aplikasi, file Swift native, file Objective-C, atau kerangka framework yang diintegrasikan

Periksa juga Capacitor dan dependensi Cordova yang terpasang. Migrasi SPM aplikasi dapat diblokir oleh dependensi native yang tidak memiliki jalur SPM yang kompatibel. Perbarui paket-paket tersebut sebelum melakukan migrasi jika memungkinkan.

Pakai asisten migrasi

Untuk aplikasi yang sudah ada, mulai dengan asisten migrasi resmi Capacitor:

npx cap spm-migration-assistant

Jalankan asisten dari root proyek Capacitor Anda. Asisten menghapus integrasi CocoaPods, membuat paket lokal, menghasilkan referensi paket untuk dependensi native yang terpasang, dan menambahkan konfigurasi yang dihasilkan yang dibutuhkan oleh proyek iOS. CapApp-SPM Sesudahnya, buka proyek iOS:

Baca keluaran asisten sebelum menutup terminal. Jika meminta Anda untuk menyelesaikan langkah-langkah manual Xcode, lakukan langkah-langkah tersebut sebelum menyinkronisasi lagi.

npx cap open ios

Selesai langkah-langkah Xcode

Pada Xcode, periksa konfigurasi proyek dan target aplikasi:

Konfirmasi

Konfirmasi CapApp-SPM ditambahkan sebagai dependensi paket lokal.
Konfirmasi tautan aplikasi target yang menghubungkan produk paket yang dihasilkan.
Tambahkan debug.xcconfig ke konfigurasi proyek jika asisten meminta.
Selesaikan peringatan paket di Xcode.
Bangun aplikasi sekali dari Xcode.

Jika Xcode tidak dapat menyelesaikan paket, gunakan File > Paket > Reset Cache Paket, kemudian selesaikan lagi.

Sinkronkan dan bangun lagi

Setelah Xcode dikonfigurasi, kembali ke terminal dan sinkronkan Capacitor:

npx cap sync ios

Lalu bangun dari Xcode lagi. Jangan anggap migrasi selesai sampai bangun bersih berhasil dari Xcode, karena penandatanganan rilis, hak istimewa, ekstensi aplikasi, dan penyelesaian paket diverifikasi di sana.

Jika aplikasi menggunakan notifikasi push, domain terkait, mode latar belakang, kelompok aplikasi, Firebase, atau konfigurasi native SDK apa pun, jalankan aliran-aliran tersebut pada simulator atau perangkat setelah proses build berhasil.

Alternatif: buat ulang iOS dengan SPM

Jika folder Anda sangat mirip dengan template default __CAPGO_KEEP_0__, maka lebih cepat untuk membuat ulangnya dengan SPM daripada melakukan migrasi secara langsung. ios/ folder is close to the default Capacitor template, it can be faster to recreate it with SPM instead of migrating in place.

Lalu, restore file dan pengaturan native aplikasi khusus Anda. Jalur ini memberikan Anda proyek SPM yang bersih, tetapi lebih mudah kehilangan perubahan Xcode yang disesuaikan jika Anda tidak menginventarisir terlebih dahulu.

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Untuk aplikasi __CAPGO_KEEP_0__ baru, __CAPGO_KEEP_1__ 8 membuat proyek iOS dengan SPM secara default:

For new Capacitor apps, Capacitor 8 creates iOS projects with SPM by default:

npx cap add ios

Hapus sisa-sisa CocoaPods

npx cap add ios --packagemanager SPM

Setelah aplikasi SPM dibangun, hapus asumsi CocoaPods yang tertinggal dari skrip lokal dan CI.

Hapus langkah-langkah seperti:

Hapus juga cache yang hanya ada untuk CocoaPods:

pod install

Hapus juga cache yang hanya ada untuk CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Repositori spesifikasi CocoaPods
Kunci cache CI berdasarkan Podfile

Alur CI dasar setelah migrasi harus menginstal dependensi JavaScript, membangun aplikasi web, sinkronisasi Capacitor, dan membangun dengan Xcode:

npm ci
npm run build
npx cap sync ios

Jika CI Anda masih membangun App.xcworkspace, update ke path proyek atau workspace yang ada setelah migrasi. Jangan biarkan path CocoaPods kuno ada hanya karena pekerjaan lama menggunakan mereka.

Pengaturan Masalah

Asisten memberi peringatan tentang dependensi yang tidak kompatibel

Perbarui dependensi terlebih dahulu dan jalankan asisten lagi. Jika tidak ada versi yang kompatibel dengan SPM, biarkan aplikasi di CocoaPods sampai Anda menggantikan dependensi tersebut atau pengembang menambahkan dukungan SPM.

Xcode tidak dapat menyelesaikan paket

Reset cache paket di Xcode, pastikan CapApp-SPM hadir sebagai paket lokal, dan jalankan npx cap sync ios lagi.

Aplikasi membangun secara lokal tetapi CI gagal

Cari asumsi CocoaPods yang lama: pod install, Pods/ cache, Podfile.lock cache keys, atau perintah pembangunan yang mengarah ke file yang telah dihapus .xcworkspace.

Signing atau hak akses yang berubah

Bandingkan target Xcode yang telah dipindahkan dengan proyek sebelum migrasi. Restor identifikasi paket, tim, profil pengembangan, file hak akses, kemampuan, dan pengaturan ekstensi.

Daftar periksa migrasi

Sebelum migrasi:

Buat cabang.
Konfirmasi bahwa aplikasi iOS saat ini dapat dibangun.
Commit keadaan yang berjalan.
Daftar inventaris file native yang disesuaikan dan pengaturan tanda tangan.
Perbarui dependensi native yang sudah memiliki rilis yang lebih baru yang kompatibel dengan SPM.

Selama migrasi:

Jalankan npx cap spm-migration-assistant.
Buka proyek dengan npx cap open ios.
Tambahkan CapApp-SPM di Xcode jika diperlukan.
Tambahkan debug.xcconfig di Xcode jika diperlukan.
Selesaikan peringatan paket.
Jalankan npx cap sync ios.

Setelah migrasi:

Buat aplikasi dari Xcode.
Tes kemampuan asli pada simulator atau perangkat.
Hapus perintah CocoaPods dari CI.
Hapus cache CocoaPods-only.
Verifikasi tanda tangan arsip dan rilis.

Gunakan Capgo Kemampuan untuk migrasi

Jika Anda menggunakan agen AI untuk menghandle migrasi, mulai dari Capgo Kemampuan sebaliknya dari prompt kosong. Kemampuan yang paling berguna untuk pekerjaan ini adalah:

capacitor-best-practices untuk meriview struktur aplikasi sebelum mengubah ios/.
cocoapods-to-spm untuk merencanakan langkah-langkah migrasi SPM dan Xcode.
capacitor-ci-cd untuk menghapus asumsi CocoaPods dari pipeline pembangunan.
debugging-capacitor dan ios-android-logs untuk menyelidiki masalah perangkat saja setelah migrasi.

Gunakan mereka sebelum mengubah proyek iOS sehingga agen memeriksa file native, CI, dan kompatibilitas dependensi bukan hanya menjalankan perintah migrasi.

Kesimpulan

Migrasi sebuah Capacitor aplikasi ke Swift Package Manager sebagian besar adalah perubahan manajemen dependensi iOS. Jalur yang paling aman adalah memulai dari cabang bersih, jalankan npx cap spm-migration-assistant, selesai langkah-langkah manual Xcode, sinkronisasi lagi, dan hapus CocoaPods dari CI hanya setelah aplikasi berhasil dibangun.

Jika proyek iOS Anda sangat disesuaikan, migrasi secara langsung. Jika itu sangat dekat dengan template Capacitor default, membuat ios/ dengan npx cap add ios --packagemanager SPM dapat lebih bersih.