Bagaimana Migrasi Aplikasi Capacitor Anda ke Paket Swift Manager

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 JavaScript code, proyek Android, atau alur rilis dari awal.

Panduan ini untuk tim aplikasi. Panduan ini menjelaskan bagaimana memindahkan aplikasi Capacitor iOS dari CocoaPods ke SPM, apa saja perubahan yang dilakukan asisten migrasi, apa saja 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

Sebuah aplikasi Capacitor yang didasarkan pada SPM memindahkan pengaturan dependensi iOS ke Manager Paket Swift. Selama migrasi, Capacitor membuat paket lokal bernama Capacitor CapApp-SPM dan menggunakan paket tersebut untuk menghubungkan target aplikasi dengan Capacitor dan dependensi native yang diinstal.

Build web masih berjalan 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 Anda 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

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

Selanjutnya, tinjau apa saja yang telah Anda modifikasi di bawah __CAPGO_KEEP_0__ ios/App/File dan pengaturan yang umum untuk 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, identifier paket, ID tim, dan profil penyediaan
ekstensi aplikasi, file Swift native, file Objective-C, atau kerangka framework yang diintegrasikan

Periksa juga Capacitor dan dependensi Cordova yang terinstal. 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. Asisten menghapus integrasi CocoaPods, membuat paket lokal, menghasilkan referensi paket untuk dependensi native yang terinstal, dan menambahkan konfigurasi yang dihasilkan yang dibutuhkan oleh proyek iOS. CapApp-SPM Setelah selesai, buka proyek iOS:

Baca keluaran asisten sebelum menutup terminal. Jika meminta Anda untuk menyelesaikan langkah-langkah manual Xcode, lakukan langkah-langkah tersebut 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.
Konfirmasikan tautan aplikasi target menghubungkan produk paket yang dihasilkan.
Tambahkan debug.xcconfig ke konfigurasi proyek jika asisten meminta.
Pecahkan peringatan paket di Xcode.
Bangun aplikasi sekali dari Xcode.

Jika Xcode tidak dapat memecahkan paket, gunakan File > Paket > Reset Cache Paket, lalu pecahkan paket lagi.

Sinkronisasi dan bangun lagi

Setelah Xcode dikonfigurasi, kembali ke terminal dan sinkronisasi Capacitor:

npx cap sync ios

Kemudian bangun dari Xcode lagi. Jangan anggap migrasi selesai sampai bangun bersih bekerja dari Xcode, karena tanda tangan rilis, hak istimewa, ekstensi aplikasi, dan pemecahan 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 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 membuat backup setiap file dan pengaturan 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 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
Migrasi Repositori 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, Perbarui ke Jalur Proyek atau Workspace yang Ada Setelah Migrasi. Jangan Biarkan Jalur CocoaPods Tua Berada di Sekitar Hanya Karena Tugas Lama Menggunakannya.

Pengaturan

context

Page/area: Support / premium support page or footer support section. Role: Section or page heading. Seen in: page support-policy.astro. Message key `support_policy_troubleshooting_title` (Support Policy Troubleshooting Title).

Pemberi Tahu Membatalkan Karena Ketergantungan Tidak Kompatibel

Perbarui Ketergantungan Terlebih Dahulu dan Jalankan Pemberi Tahu Lagi. Jika Tidak Ada Versi yang Kompatibel dengan SPM, Biarkan Aplikasi di CocoaPods Sampai Anda Mengganti Ketergantungan atau Pengembang Menambahkan Support SPM. CapApp-SPM Xcode Tidak Dapat Mengatasi Paket npx cap sync ios Reset Cache Paket di Xcode, Periksa bahwa __CAPGO_KEEP_1__ Hadir sebagai Paket Lokal, dan Jalankan __CAPGO_KEEP_2__ Lagi.

Aplikasi membangun secara lokal tetapi CI gagal

Cari asumsi CocoaPods yang sudah ketinggalan: pod install, Pods/ cache Podfile.lock cache keys, atau perintah pembangunan yang mengarah ke file yang sudah dihapus .xcworkspace.

Signing atau akses hak yang berubah

Samaikan target Xcode yang sudah di migrasi dengan proyek sebelum migrasi. Restor identifikasi paket, tim, profil pengaturan, file akses hak, kemampuan, dan pengaturan ekstensi.

Daftar Pemeriksaan Migrasi

Sebelum migrasi:

Buat cabang.
Konfirmasi bahwa aplikasi iOS saat ini dapat dibangun.
Commit keadaan yang berjalan.
Daftar file native yang di custom dan pengaturan tanda tangan.
Perbarui dependensi native yang sudah memiliki rilis yang lebih baru yang kompatibel dengan SPM.

Dalam proses 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 pengemasan.
Jalankan npx cap sync ios.

Setelah migrasi:

Bangun aplikasi dari Xcode.
Migrasikan kemampuan native di simulator atau perangkat.
Hapus perintah CocoaPods dari CI.
Hapus cache CocoaPods yang hanya tersedia.
Verifikasi tanda tangan arsip dan rilis.

Pakai Capgo Kemampuan untuk migrasi.

Jika Anda menggunakan agen AI untuk menghandle migrasi, mulai dari __CAPGO_KEEP_0__ Kemampuan. Capgo Skills untuk meninjau struktur aplikasi sebelum mengubahnya.

capacitor-best-practices untuk merencanakan langkah migrasi SPM dan langkah-langkah Xcode yang diikuti. ios/.
cocoapods-to-spm untuk menghilangkan asumsi CocoaPods dari pipeline pembangunan.
capacitor-ci-cd dan
debugging-capacitor dan ios-android-logs Migrasikan aplikasi __CAPGO_KEEP_0__ ke Swift Package Manager untuk menginvestigasi masalah perangkat hanya setelah migrasi.

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

Kesimpulan

Migrasi aplikasi Capacitor ke Swift Package Manager sebagian besar adalah 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 bisa lebih bersih.

How to Migrate Your Capacitor App to Swift Package Manager