Bagaimana Migrasi Aplikasi Capacitor ke Pengelola Paket Swift

Capacitor 8 membuat proyek iOS baru dengan Swift Package Manager (SPM) secara default. Aplikasi yang sudah ada yang masih menggunakan CocoaPods dapat di-migrasi juga, tetapi jalur yang paling aman tergantung pada seberapa banyak customisasi iOS native yang aplikasi milik Anda.

Petunjuk ini menjelajahi perubahan apa saja, apa yang harus dibackup, dan dua jalur migrasi yang praktis: menggunakan asisten migrasi Capacitor atau merekonstruksi proyek iOS dengan SPM.

Mengapa migrasi sekarang

CocoaPods sedang bergerak menuju truk yang hanya dapat dibaca. Rencana saat ini adalah untuk truk CocoaPods berhenti menerima podspecs baru pada 2 Desember 2026. Bangunan yang sudah ada harus tetap berjalan, tetapi rilis baru dan pembaruan dependensi yang bergantung pada truk tidak akan dipublikasikan di sana setelah perubahan.

SPM juga adalah arah yang diambil oleh Capacitor. Capacitor telah mendukung memilih CocoaPods atau SPM sejak Capacitor 6, dan Capacitor 8 membuat proyek iOS SPM sebagai template default.

Apa saja perubahan dalam proyek SPM Capacitor

Migrasi dari CocoaPods ke SPM mengganti lapisan dependensi iOS. Aplikasi web, proyek Android, dan sebagian besar perintah alur kerja Capacitor tetap sama.

CapApp-SPM mengganti Podfile

Dalam aplikasi CocoaPods, dependensi iOS dihubungkan melalui ios/App/Podfile, Podfile.lock, Pods/dan yang dihasilkan .xcworkspace.

Dalam aplikasi SPM, Capacitor menciptakan paket lokal bernama CapApp-SPM. Paket ini menjadi tempat pusat di mana Capacitor mengacu dependensi plugin iOS native Anda. Capacitor CLI diperbarui CapApp-SPM ketika Anda sinkronkan plugin, jadi lihatlah sebagai output yang dihasilkan dan hindari mengeditnya secara manual.

debug.xcconfig mengganti konfigurasi Pods

Asisten migrasi juga menciptakan file yang dihasilkan debug.xcconfig. File ini membawa pengaturan build yang CocoaPods dahulu menyediakan melalui file xcconfig yang dihasilkan.

Setelah migrasi, Anda mungkin perlu menambahkan debug.xcconfig ke konfigurasi proyek Xcode jika asisten memberitahu Anda untuk melakukannya.

Setiap plugin harus mendukung SPM

Anda tidak dapat menggabungkan CocoaPods dan SPM di proyek iOS yang sama Capacitor. Sebelum melakukan migrasi, periksa setiap Capacitor dan plugin Cordova di package.json.

Jika plugin tidak mendukung SPM yet, perbarui, gantikan, atau migrasikan plugin terlebih dahulu. Plugin Swift sederhana sering dapat dikonversi dengan Ionic’s capacitor-plugin-convertertetapi plugin dengan tata letak Objective-C dan Swift yang lebih kompleks mungkin memerlukan pekerjaan manual.

Apa yang harus disimpan terlebih dahulu

Mulai dari cabang Git yang bersih dan komitkan keadaan saat ini sebelum menyentuh proyek iOS. Kemudian daftar file native yang digunakan aplikasi Anda.

File umum yang harus disimpan dari ios/App/ termasuk:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, jika aplikasi Anda memiliki satu
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, jika Anda menggunakan Firebase
File khusus .xcconfig file
Pengaturan tanda tangan, identifikasi paket, ID tim, dan pengaturan profil penyediaan

Juga simpan semua file Swift native, Objective-C, framework, ekstensi, atau SDK yang Anda tambahkan di luar template standar Capacitor.

Pilihan 1: Gunakan asisten migrasi Capacitor

Gunakan jalur ini ketika proyek iOS Anda memiliki edit native yang kustom yang Anda tidak ingin kehilangan.

Jalankan asisten dari root proyek Capacitor Anda:

bunx cap spm-migration-assistant

Asisten menghapus infrastruktur CocoaPods, membuat paket lokal, menghasilkan referensi paket dari plugin yang terinstal, dan membuat file konfigurasi SPM yang dihasilkan. CapApp-SPM Saat selesai, buka proyek:

Lalu ikuti langkah-langkah manual Xcode yang dicetak oleh asisten. Pada proyek kebanyakan ini berarti:

bunx cap open ios

Tambahkan

sebagai dependensi paket lokal. CapApp-SPM Tambahkan yang dihasilkan
Gunakan jalur ini ketika proyek iOS Anda memiliki edit native yang kustom yang Anda tidak ingin kehilangan. debug.xcconfig To konfigurasi aplikasi.
Selesaikan peringatan tentang plugin yang tidak dapat dikonversi ke SPM.
Bangun aplikasi dari Xcode sekali sebelum memperbarui CI.

Setelah proyek Xcode dibangun, sinkron ulang:

bunx cap sync ios

Option 2: Re-scaffold proyek iOS dengan SPM

Pilih jalur ini ketika direktori Anda dekat dengan template default __CAPGO_KEEP_0__ dan Anda dapat aman mengembalikan file-file kustom setelahnya. ios/ directory is close to the default Capacitor template and you can safely restore custom files afterward.

Kembalikan file-file native yang dibutuhkan aplikasi Anda, kemudian buka proyek:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Jalur ini seringkali lebih bersih daripada migrasi in-place karena memberikan Anda template iOS __CAPGO_KEEP_0__ yang segar. Namun, Anda harus berhati-hati dalam mengaplikasikan tanda tangan, hak istimewa, file Firebase, perubahan kode sumber native, dan pengaturan Xcode kustom apa pun.

bunx cap open ios

Aplikasi baru Capacitor

Untuk aplikasi baru, Capacitor 8 menggunakan SPM secara default ketika menambahkan iOS:

Capacitor

bunx cap add ios

Jika Anda perlu untuk lebih eksplisit, Anda masih bisa melewati opsi manajer paket:

bunx cap add ios --packagemanager SPM

Perbarui CI setelah migrasi

Setelah aplikasi dibangun secara lokal, perbarui CI/CD sehingga tidak lagi mengasumsikan CocoaPods.

Hapus langkah-langkah yang menjalankan:

pod install

Juga hapus cache untuk:

ios/App/Pods
ios/App/Podfile.lock
Repositori spesifikasi CocoaPods, jika aliran kerja Anda menyimpannya hanya untuk aplikasi ini

Tetapkan langkah-langkah build web Anda secara normal dan Capacitor sink. Langkah kerja iOS biasanya harus menginstal dependensi JavaScript, membangun aset web, sinkronisasi Capacitor, dan kemudian membangun dengan Xcode:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Daftar checklist migrasi

Sebelum migrasi:

Buat cabang git baru.
Commit aplikasi kerja saat ini.
Pastikan setiap plugin yang terinstal mendukung SPM.
Rekam pengaturan file iOS kustom dan tanda tangan.
Konfirmasi aplikasi dibangun sebelum migrasi.

Selama migrasi:

Jalankan bunx cap spm-migration-assistant atau re-atur ulang ios/.
Tambahkan CapApp-SPM di Xcode jika diperlukan.
Tambahkan debug.xcconfig di Xcode jika diperlukan.
Mengembalikan file native aplikasi khusus.
Jalankan bunx cap sync ios.

Setelah migrasi:

Bangun dan jalankan aplikasi di Xcode.
Hapus file-file CocoaPods yang tersisa.
Hapus pod install dari CI.
Verifikasi tanda tangan rilis masih berfungsi.
Jalankan aplikasi di setidaknya satu simulator dan satu perangkat nyata sebelum mengirim.

Pengaturan

Jika Xcode tidak dapat menyelesaikan paket, reset cache paket dari Xcode dan jalankan bunx cap sync ios lagi.

Jika migrasi gagal karena plugin, periksa apakah plugin tersebut memiliki rilis yang lebih baru dengan dukungan SPM. Untuk plugin yang Anda kelola, migrasikan terlebih dahulu paket plugin dan kemudian kembali ke migrasi aplikasi.

Ketika aplikasi dibangun secara lokal tetapi CI gagal, periksa asumsi CocoaPods yang kuno. Penyebab umum adalah jalur pembangunan paksa, cache yang ketinggalan zaman .xcworkspace Ketika aplikasi dibangun secara lokal tetapi CI gagal, periksa asumsi CocoaPods yang kuno. Penyebab umum adalah jalur pembangunan paksa, cache yang ketinggalan zaman, dan lain-lain. pod install perintah, atau caching Pods/ dari bangunan sebelumnya.

Kesimpulan

Migrasi aplikasi Capacitor ke Swift Package Manager sebagian besar tentang mengganti pengaturan dependensi iOS. CapApp-SPM mengambil alih referensi dependensi, debug.xcconfig mengganti konfigurasi pembangunan CocoaPods yang dihasilkan, dan CI tidak lagi memerlukan pod install.

Untuk proyek iOS yang disesuaikan, mulai dengan bunx cap spm-migration-assistant. Untuk proyek yang dekat dengan template default, re-scaffold SPM yang bersih seringkali lebih cepat dan lebih mudah dipahami.

Sumber Daya

Teruskan dari Cara Migrasi Aplikasi Capacitor ke Pengelola Paket Swift

Jika Anda menggunakan Cara Migrasi Aplikasi Capacitor ke Pengelola Paket Swift untuk merencanakan migrasi dan operasi bisnis, hubungkannya dengan Capgo Enterprise untuk alur kerja produk di Capgo Enterprise, Alternatif Plugin Bisnis Ionic untuk alur kerja produk di Alternatif Plugin Bisnis Ionic, Alternatif Capgo untuk alur kerja produk di Alternatif Capgo, Konsultasi Capgo untuk alur kerja produk di Capgo Consulting, dan Capgo Support Premium untuk alur kerja produk di Capgo Support Premium.

Bagaimana Migrasi Aplikasi Capacitor ke Swift Package Manager