Cara Migrasi Aplikasi Capacitor Anda ke Manajer Paket Swift

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

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

Apa yang berubah dalam aplikasi

Aplikasi Capacitor yang berbasis CocoaPods bergantung pada file-file seperti:

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

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

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

Sebelum Anda memigrasi

Mulai dari cabang yang bersih dan pastikan aplikasi saat ini dapat dibangun sebelum mengubah pengelola 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.

Migrasi selanjutnya, tinjau apa saja yang telah Anda modifikasi di aplikasi Anda di bawah ios/App/. File-file umum dan pengaturan yang perlu Anda simpan 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
pengaturan .xcconfig file-file
pengaturan tanda tangan, identifikasi paket, ID tim, dan profil penyediaan
ekstensi aplikasi, file-file native Swift, file-file Objective-C, atau kerangka kerja yang diintegrasikan

Periksa juga ketergantungan Capacitor dan Cordova yang terpasang. Migrasi SPM aplikasi dapat diblokir oleh dependensi native yang tidak memiliki jalur yang kompatibel dengan SPM. 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 ini menghilangkan integrasi CocoaPods, membuat local CapApp-SPM Menginstal paket, menghasilkan referensi paket untuk dependensi native yang terpasang, dan menambahkan konfigurasi yang dihasilkan yang dibutuhkan oleh proyek iOS.

Setelah itu selesai, buka proyek iOS:

npx cap open ios

Baca keluaran asisten sebelum menutup terminal Anda. Jika asisten meminta Anda untuk menyelesaikan langkah-langkah manual Xcode, lakukan terlebih dahulu sebelum sinkronisasi lagi.

Lakukan langkah-langkah Xcode

Pada Xcode, periksa konfigurasi proyek aplikasi dan target:

Konfirmasi CapApp-SPM ditambahkan sebagai dependensi paket lokal.
Konfirmasi bahwa target aplikasi menghubungkan produk paket yang dihasilkan.
Tambahkan debug.xcconfig ke konfigurasi proyek jika asisten memintanya.
Pecahkan peringatan paket pada Xcode.
Bangun aplikasi sekali dari Xcode.

Mengapa Xcode tidak dapat menyelesaikan paket, gunakan File > Paket > Reset Paket CacheMaka, selesaikan kembali menyelesaikan paket.

Dan bangun kembali

Setelah Xcode dikonfigurasi, kembali ke terminal dan sync Capacitor:

npx cap sync ios

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

Mengapa aplikasi menggunakan push notifikasi, domain terkait, mode latar belakang, grup aplikasi, Firebase, atau konfigurasi native SDK lainnya, jalankan aliran-aliran tersebut pada simulator atau perangkat setelah bangun berhasil.

Alternatif: Buat kembali iOS dengan SPM

Mengapa aplikasi Anda ios/ Folder Anda dekat dengan template Capacitor default, maka dapat lebih cepat untuk membuatnya kembali dengan SPM daripada melakukan migrasi di tempat.

Hanya gunakan jalur ini setelah mengkomit atau mengarsip setiap file native dan pengaturan tanda tangan yang Anda butuhkan:

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

Lalu kembalikan file dan pengaturan native aplikasi Anda. Jalur ini memberikan Anda proyek SPM bersih, tetapi lebih mudah kehilangan perubahan Xcode yang kustom jika Anda tidak mengarsipkannya terlebih dahulu.

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

npx cap add ios

Migrasi Aplikasi Capacitor Anda ke SPM

npx cap add ios --packagemanager SPM

Hapus Sisa CocoaPods

Hapus sisa asumsi CocoaPods dari skrip lokal dan CI setelah aplikasi SPM dibangun.

Hapus langkah-langkah seperti:

pod install

Hapus juga cache yang hanya ada untuk CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Hapus repositori spesifikasi CocoaPods
Hapus 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.xcworkspacePerbarui ke jalur proyek atau workspace yang ada setelah migrasi. Jangan biarkan jalur CocoaPods kuno tetap ada hanya karena pekerjaan lama menggunakan mereka.

Pengaturan Tambahan

Penasihat memberi peringatan tentang dependensi yang tidak kompatibel

Perbarui dependensi terlebih dahulu dan jalankan penasihat lagi. Jika tidak ada versi yang kompatibel dengan SPM, biarkan aplikasi tetap menggunakan CocoaPods sampai Anda mengganti dependensi tersebut atau pemelihara mengaktifkan 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 dapat dibangun secara lokal tetapi CI gagal

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

Signing atau hak istimewa berubah

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

Migrasi checklist

Sebelum migrasi:

Buat cabang.
Pastikan aplikasi iOS saat ini dapat dibangun.
Simpan keadaan kerja.
Daftar file native yang diubah dan pengaturan tanda tangan.
Perbarui dependensi native yang sudah memiliki rilis yang lebih baru yang kompatibel dengan SPM.

Saat migrasi:

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

Migrasi Selesai:

Membangun aplikasi dari Xcode.
Menguji kemampuan native di simulator atau perangkat.
Menghapus perintah CocoaPods dari CI.
Menghapus cache CocoaPods yang hanya tersedia.
Mengverifikasi tanda tangan arsip dan rilis.

Menggunakan Capgo Kemampuan untuk migrasi

Jika Anda menggunakan agen AI untuk mengelola 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 mengubahnya ios/.
cocoapods-to-spm untuk merencanakan langkah migrasi SPM dan Xcode.
capacitor-ci-cd dan
debugging-capacitor context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan). ios-android-logs untuk menyelidiki masalah perangkat hanya saja setelah migrasi.

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

Kesimpulan

Migrasi aplikasi Capacitor ke Manajer Paket Swift sebagian besar adalah perubahan manajemen dependensi iOS. Jalur yang paling aman adalah memulai dari cabang bersih, menjalankan npx cap spm-migration-assistantselesai langkah manual Xcode, sinkron ulang, dan hapus CocoaPods dari CI hanya setelah aplikasi berhasil dibangun.

Jika proyek iOS Anda sangat disesuaikan, migrasi di tempat. Jika itu dekat dengan template Capacitor default, buat ulang ios/ bersama npx cap add ios --packagemanager SPM bisa lebih bersih.

Bagaimana Migrasi Aplikasi Capacitor Anda ke Manajer Paket Swift