Bagaimana Migrasi Aplikasi Capacitor Anda ke Pengelola Paket Swift

Migrasi ke Manager Paket Swift adalah arah default untuk Capacitor proyek 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 pelepasan dari awal.

Panduan ini untuk tim aplikasi. Panduan 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 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 Capacitor yang berbasis SPM memindahkan pengaturan dependensi iOS ke Manager Paket Swift. Selama migrasi, Capacitor membuat paket lokal bernama Capacitor dan menggunakan paket tersebut untuk menghubungkan target aplikasi dengan Capacitor dan dependensi native yang diinstal. CapApp-SPM Build web masih berfungsi dengan cara yang sama. Anda masih menjalankan build web, sinkronisasi Capacitor, membuka Xcode, dan mengarsipkan aplikasi. Perbedaan utama adalah bahwa CocoaPods tidak lagi mengelola grafik dependensi iOS.

The web build still works the same way. You still run a web build, sync Capacitor, open Xcode, and archive the app. The main difference is that CocoaPods no longer owns the iOS dependency graph.

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

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

git status
npm run build
npx cap sync ios

Kemudian, tinjau apa yang telah Anda modifikasi di bawah __CAPGO_KEEP_0__

File dan pengaturan umum yang perlu Anda simpan termasuk: ios/App/__CAPGO_KEEP_0__

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
custom .xcconfig file
pengaturan tanda tangan, identifier aplikasi, ID tim, dan profil pengaturan
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 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 project Capacitor. Asisten ini 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 Anda mengalami masalah, lihat panduan migrasi __CAPGO_KEEP_0__ untuk mendapatkan informasi lebih lanjut.

npx cap open ios

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

Selesai langkah-langkah Xcode

Dalam Xcode, periksa konfigurasi proyek dan target aplikasi:

Konfirmasi CapApp-SPM tertambah 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.
Pecahkan peringatan paket dalam Xcode.
Bangun aplikasi sekali dari Xcode.

Jika Xcode tidak dapat memecahkan paket, gunakan File > Paket > Reset Cache Paketlalu resolve paket lagi.

Sync dan build lagi.

Setelah Xcode dikonfigurasi, kembali ke terminal dan sync Capacitor:

npx cap sync ios

Maka build dari Xcode lagi. Jangan anggap migrasi selesai sampai build bersih berhasil dari Xcode, karena signing rilis, hak istimewa, ekstensi aplikasi, dan resolusi paket diverifikasi di sana.

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

Alternatif: buat ulang iOS dengan SPM

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

Hanya gunakan jalur ini setelah mengkomit atau membuat backup 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

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

npx cap add ios --packagemanager SPM

Menghapus sisa CocoaPods

Setelah aplikasi SPM dibangun, hapus asumsi CocoaPods yang tersisa 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
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 yang ketinggalan zaman tetap ada hanya karena pekerjaan lama menggunakan mereka.

Pengaturan

Peringatan asisten 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 menggantikan 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 lama: pod install, Pods/ cache, Podfile.lock nama kunci cache, atau perintah pembangunan yang mengacu ke file yang telah dihapus .xcworkspace.

Signing atau hak istimewa berubah

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

Daftar Pemeriksaan Migrasi

Sebelum migrasi:

Membuat cabang.
Mengonfirmasi aplikasi iOS saat ini dapat dibangun.
Mengkomitkan keadaan kerja.
Menginventaris file native yang diatur sendiri dan pengaturan tanda tangan.
Mengupdate dependensi native yang sudah memiliki rilis yang lebih baru dan 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.
Mengatasi peringatan paket.
Jalankan npx cap sync ios.

Setelah migrasi:

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

Menggunakan Capgo Kemampuan untuk migrasi.

Jika Anda menggunakan agen AI untuk menghandle migrasi, mulai dari __CAPGO_KEEP_0__ Kemampuan Capgo Skills Menggunakan __CAPGO_KEEP_0__ Kemampuan untuk migrasi.

capacitor-best-practices Migrasikan struktur aplikasi sebelum mengubahnya ios/.
cocoapods-to-spm Untuk merencanakan langkah-langkah migrasi SPM dan Xcode.
capacitor-ci-cd Untuk 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 melakukan audit file native, CI, dan konsistensi dependensi bukan hanya menjalankan perintah migrasi.

Kesimpulan

Migrasi aplikasi Capacitor ke Manajer Paket Swift sebagian besar merupakan perubahan manajemen dependensi iOS. Jalur yang paling aman adalah memulai dari cabang bersih, menjalankan npx cap spm-migration-assistantselesai 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 dekat dengan template Capacitor default, membuat ios/ dengan npx cap add ios --packagemanager SPM mungkin lebih bersih.