Cara Migrasi Aplikasi Capacitor Anda ke Swift Package Manager

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

Panduan ini untuk tim aplikasi. Panduan ini menjelaskan bagaimana migrasi aplikasi iOS Capacitor 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 berdasarkan CocoaPods bergantung pada file seperti:

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

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

The web build masih berfungsi 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 yang bersih dan pastikan aplikasi saat ini dapat dibangun sebelum mengubah manajer dependensi:

git status
npm run build
npx cap sync ios

Lalu, commit keadaan kerja. Migrasi ini menyentuh file proyek iOS yang dihasilkan, jadi memiliki titik tolak rollback yang bersih sangat penting.

Selanjutnya, tinjau apa yang telah disesuaikan aplikasi Anda di bawah ios/App/File umum dan pengaturan 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
pengaturan .xcconfig file
pengaturan tanda tangan, identifikasi paket, ID tim, dan profil pengaturan
ekstensi aplikasi, file Swift native, file Objective-C native, 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 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

Lakukan hal itu dari root direktori proyek Capacitor Anda. Asisten menghapus integrasi CocoaPods, membuat file lokal CapApp-SPM package, menghasilkan referensi package untuk dependensi native yang terinstall, serta menambahkan konfigurasi yang dihasilkan yang diperlukan oleh proyek iOS.

Setelah itu, buka proyek iOS:

npx cap open ios

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

Selesai dengan langkah-langkah Xcode

Pada Xcode, periksa konfigurasi proyek dan target aplikasi:

Confirm CapApp-SPM Ditambahkan sebagai dependensi paket lokal.
Konfirmasikan tautan aplikasi target menghubungkan produk paket yang dihasilkan.
Tambahkan kode yang dihasilkan debug.xcconfig Menambahkan ke konfigurasi proyek jika asisten memintanya.
Selesaikan peringatan paket di Xcode.
Buat aplikasi sekali dari Xcode.

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

Sinkronisasi dan buat lagi

Setelah Xcode dikonfigurasi, kembali ke terminal dan sinkronisasi Capacitor:

npx cap sync ios

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

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

Alternatif: Buat ulang iOS dengan SPM

Jika aplikasimu ios/ Folder ini mirip dengan template default Capacitor, sehingga lebih cepat untuk membuatnya ulang dengan SPM daripada melakukan migrasi langsung.

Hanya gunakan metode ini setelah mengkomit atau membuat backup setiap file dan pengaturan native yang dibutuhkan:

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. Metode ini memberikan proyek SPM yang bersih, tetapi lebih mudah kehilangan perubahan Xcode yang disesuaikan jika Anda tidak menginventarisir 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
Repositori spesifikasi CocoaPods
Migrasi Aplikasi Capacitor ke SPM

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 it to the project or workspace path that exists after migration. Do not keep stale CocoaPods paths around just because the old job used them.

Troubleshooting

Asisten memberi peringatan tentang dependensi yang tidak kompatibel

Update the dependency first and run the assistant again. If no SPM-compatible version exists, keep the app on CocoaPods until you replace that dependency or the maintainer adds SPM support.

Xcode tidak dapat menyelesaikan paket

Xcode tidak dapat menyelesaikan paket CapApp-SPM Reset cache paket di Xcode, pastikan npx cap sync ios again.

Aplikasi membangun secara lokal tetapi CI gagal

Mencari asumsi CocoaPods yang sudah usang: pod install, Pods/ Membuang cache, Podfile.lock kunci cache, atau perintah pembangunan yang mengarah ke file yang telah dihapus .xcworkspace.

Signing atau hak istimewa berubah

Menggambarkan target Xcode yang sudah di migrasi terhadap proyek sebelum migrasi. Restor identifikasi paket, tim, profil pengaturan, file hak istimewa, kemampuan, dan pengaturan ekstensi.

Daftar Pemeriksaan Migrasi

Sebelum migrasi:

Membuat cabang.
Konfirmasikan pembangunan aplikasi iOS saat ini.
Mengkomitkan keadaan kerja.
Menghitung file native yang sudah dimodifikasi dan pengaturan tanda tangan.
Perbarui dependensi native yang sudah memiliki rilis yang lebih baru yang kompatibel dengan SPM.

Migrasi selama:

Jalankan npx cap spm-migration-assistant.
Terbuka 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.

Migrasi setelah:

Bangun aplikasi dari Xcode.
Uji 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 Keterampilan Capgo Alihkan aplikasi Capacitor Anda ke SPM. Keterampilan yang paling berguna untuk pekerjaan ini adalah:

capacitor-best-practices Mengatur langkah-langkah migrasi SPM dan Xcode. ios/.
cocoapods-to-spm Menghapus asumsi CocoaPods dari pipeline pembangunan.
capacitor-ci-cd menghilangkan asumsi CocoaPods dari pipeline pembangunan.
debugging-capacitor and ios-android-logs Menghapus perintah CocoaPods dari CI.

Migrasikan aplikasi __CAPGO_KEEP_0__ Anda ke Swift Package Manager sebelum mengubah proyek iOS sehingga agen melakukan audit file native, CI, dan kompatibilitas dependensi bukan hanya menjalankan perintah migrasi.

Kesimpulan

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

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

Cara Mengmigrasikan Aplikasi Capacitor Anda ke Pengelola Paket Swift