Cara 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. Petunjuk ini menjelaskan cara memindahkan aplikasi Capacitor iOS dari CocoaPods ke SPM, apa saja perubahan yang dilakukan asisten migrasi, apa saja yang masih perlu dicek di Xcode, dan bagaimana membersihkan CI setelah aplikasi dibangun.

Apa saja perubahan 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 SPM berbasis Capacitor memindahkan pengaturan dependensi iOS ke Manager 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 diinstal.

Pembangunan web masih berfungsi dengan cara yang sama. Anda masih menjalankan pembangunan 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

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

Selanjutnya, tinjau apa yang telah disesuaikan aplikasi Anda di bawah ios/App/File dan pengaturan umum yang perlu dipertahankan 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
custom .xcconfig file
pengaturan tanda tangan, identifikasi paket, ID tim, dan profil penyediaan
ekstensi aplikasi, file Swift native, 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 asisten dari root project Capacitor. Asisten menghapus integrasi CocoaPods, membuat paket lokal, menghasilkan referensi paket untuk dependensi native yang terpasang, dan menambahkan konfigurasi yang dihasilkan yang diperlukan 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 itu sebelum menyinkronisasi lagi.

npx cap open ios

Selesai langkah-langkah Xcode

Dalam 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 yang dihasilkan debug.xcconfig ke konfigurasi proyek jika asisten meminta.
Selesaikan peringatan paket di Xcode.
Buat aplikasi sekali dari Xcode.

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

Sinkronkan dan buat lagi

Setelah Xcode dikonfigurasi, kembali ke terminal dan sinkronkan Capacitor:

npx cap sync ios

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

If aplikasi menggunakan notifikasi push, domain terkait, mode latar belakang, grup aplikasi, Firebase, atau konfigurasi native SDK mana pun, jalankan aliran-aliran tersebut pada simulator atau perangkat setelah proses build 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 melakukan migrasi di tempat.

Hanya gunakan jalur ini setelah mengkomit atau melakukan backup setiap file dan pengaturan signing native yang Anda butuhkan:

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

Lalu restore file dan pengaturan native aplikasi khusus Anda. Jalur ini memberikan proyek SPM yang bersih, tetapi lebih mudah kehilangan perubahan Xcode yang disesuaikan 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 menentukan secara eksplisit:

npx cap add ios --packagemanager SPM

Membersihkan sisa-sisa CocoaPods

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

Hapus langkah-langkah seperti:

pod install

Juga hapus cache yang hanya ada untuk CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Repo Specs 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 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 yang kompatibel dengan SPM, 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 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 nama kunci cache, atau perintah pembangunan yang mengarah ke file yang telah dihapus .xcworkspace.

Perubahan tanda tangan atau hak istimewa

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

Dokumen periksa migrasi

Sebelum migrasi:

Buat cabang.
Pastikan aplikasi iOS saat ini dapat dibangun.
Commit keadaan yang berjalan.
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.
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 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-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 konsistensi dependensi bukan hanya menjalankan perintah migrasi.

Kesimpulan

Migrasi sebuah aplikasi Capacitor 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-assistantselesai langkah-langkah manual Xcode, sinkronisasi lagi, dan hapus CocoaPods dari CI hanya setelah aplikasi dibangun.

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

Bagaimana Migrasi Aplikasi Capacitor Anda ke Pengelola Paket Swift