Cara Migrasi Aplikasi Capacitor Anda ke Pengelola Paket Swift

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

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

Apa yang berubah di aplikasi

Aplikasi berbasis CocoaPods Capacitor bergantung pada file-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 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.

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

Sebelum Anda memigrasikan

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 kerja. Migrasi menyentuh file proyek iOS yang dihasilkan, sehingga memiliki titik rollback bersih sangat penting.

Selanjutnya, tinjau apa yang telah Anda modifikasi di ios/App/File dan pengaturan umum yang perlu Anda simpan termasuk:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftJika ada
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistJika Anda menggunakan Firebase
Kustom .xcconfig File-file
Pengaturan tanda tangan, identifikasi aplikasi, ID tim, dan profil pengaturan
Aplikasi ekstensi, file-file Swift native, file-file Objective-C, atau kerangka kerja 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 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 Setelah selesai, buka proyek iOS:

Jika ada

npx cap open ios

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

Selesai langkah-langkah Xcode

Di 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 meminta Anda untuk melakukannya.
Atasi peringatan paket di Xcode.
Buat aplikasi sekali dari Xcode.

Jika Xcode tidak dapat menyelesaikan paket, gunakan File > Paket > Reset Cache PaketSetelah itu, resolusi paket lagi.

Sinkron dan bangun lagi

Setelah Xcode dikonfigurasi, kembali ke terminal dan sinkron Capacitor:

npx cap sync ios

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

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

Alternatif: buat ulang iOS dengan SPM

Jika folder Anda ios/ dekat dengan template default Capacitor, maka lebih cepat untuk membuat ulangnya dengan SPM daripada migrasi di tempat.

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

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

Lalu restor file dan pengaturan native aplikasi khusus Anda. Jalur ini memberikan proyek SPM bersih, tapi lebih mudah kehilangan perubahan Xcode yang kustom jika Anda tidak menginventarisir mereka terlebih dahulu.

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

npx cap add ios

Anda masih bisa eksplisit:

npx cap add ios --packagemanager SPM

Membersihkan sisa CocoaPods

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

Hapus langkah seperti:

pod install

Juga hapus 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 jalur proyek atau workspace yang ada setelah migrasi. Jangan biarkan jalur CocoaPods yang ketinggalan zaman tetap ada hanya karena pekerjaan lama menggunakan mereka.

Pengaturan Masalah

Asisten mengingatkan tentang dependensi yang tidak kompatibel

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

Xcode tidak dapat menyelesaikan paket

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

Aplikasi dibangun secara lokal tetapi CI gagal

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

Tanda tangan atau hak istimewa berubah

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

Daftar periksa migrasi

Sebelum migrasi:

Buat cabang.
Konfirmasi aplikasi iOS saat ini dibangun.
Komit keadaan kerja.
Daftar file native kustom 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.
Atasi peringatan paket.
Jalankan npx cap sync ios.

Setelah migrasi:

Buat aplikasi dari Xcode.
Uji kemampuan native pada simulator atau perangkat.
Hapus perintah CocoaPods dari CI.
Hapus cache CocoaPods yang hanya ada di CocoaPods.
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 Mengulas struktur aplikasi sebelum mengubahnya ios/.
cocoapods-to-spm Mengatur langkah-langkah migrasi SPM dan Xcode.
capacitor-ci-cd Menghilangkan asumsi CocoaPods dari pipeline pembangunan.
debugging-capacitor dan ios-android-logs Menginvestigasi masalah perangkat hanya setelah migrasi.

Pakailah mereka sebelum mengubah proyek iOS sehingga agen memeriksa file native, CI, dan konsistensi dependensi bukannya hanya menjalankan perintah migrasi.

Kesimpulan

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

Jika proyek iOS Anda sangat disesuaikan, migrasikan di tempat. Jika itu dekat dengan template Capacitor default, membuat ios/ dengan npx cap add ios --packagemanager SPM lebih bersih.

Cara Mengganti Capacitor Aplikasi Anda ke Swift Package Manager