Bagaimana Migrasi Aplikasi Capacitor ke Pengelola Paket Swift

Capacitor 8 creates new iOS projects with Swift Package Manager (SPM) by default. Existing apps that still use CocoaPods can migrate too, but the safest path depends on how much native iOS customization your app has.

Petunjuk ini menjelaskan 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 berfungsi, tetapi rilis baru dan pembaruan dependensi yang bergantung pada truk tidak akan dipublikasikan di sana setelah perubahan.

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

Apa saja perubahan di proyek SPM Capacitor

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

CapApp-SPM menggantikan Podfile

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

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

debug.xcconfig menggantikan konfigurasi Pods

Asisten migrasi juga membuat 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 mencampur CocoaPods dan SPM dalam proyek iOS Capacitor yang sama. Sebelum melakukan migrasi, periksa setiap Capacitor dan plugin Cordova di package.json.

Jika plugin tidak mendukung SPM yet, update, ganti, atau migrasi plugin terlebih dahulu. Plugin Swift sederhana dapat sering dikonversi dengan Ionic’s capacitor-plugin-converter, tetapi plugin dengan tata letak Objective-C dan Swift yang lebih kompleks mungkin memerluit pekerjaan manual.

Apa yang harus dibackup terlebih dahulu

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

File umum untuk dipertahankan 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
Tidak Standar .xcconfig file
Pengaturan tanda tangan, identifier aplikasi, ID tim, dan pengaturan profil penyediaan

Juga pertahankan file native Swift, 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 Setelah 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
ke konfigurasi aplikasi. debug.xcconfig Selesaikan peringatan tentang plugin yang tidak dapat dikonversi ke SPM.
Buat aplikasi dari Xcode sekali sebelum mengupdate CI.
Setelah proyek Xcode dibangun, sinkronisasi lagi:

Then follow the manual Xcode steps printed by the assistant. In most projects this means: Add

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 dengan 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 aplikasi Anda butuhkan, lalu 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 template __CAPGO_KEEP_0__ 8 iOS yang segar. Namun, Anda harus dengan hati-hati mengaplikasikan tanda tangan, hak akses, 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:

For a new app, Capacitor 8 uses SPM by default when adding iOS:

bunx cap add ios

Perbarui CI setelah migrasi

bunx cap add ios --packagemanager SPM

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

Hapus langkah-langkah yang menjalankan:

__CAPGO_KEEP_0__

pod install

Juga hapus cache untuk:

ios/App/Pods
ios/App/Podfile.lock
Gudang spesifikasi CocoaPods, jika workflow Anda hanya menyimpannya untuk aplikasi ini saja

Tetapkan langkah-langkah pembangunan web Anda secara normal dan Capacitor sinkronisasi. Langkah-langkah iOS biasanya akan 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 periksa migrasi

Sebelum migrasi:

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

Saat migrasi:

Jalankan bunx cap spm-migration-assistant atau re-scaffold 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:

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

Pengaturan Perbaikan

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 memiliki rilis yang lebih baru dengan dukungan SPM. Untuk plugin yang Anda kelola, migrasikan paket plugin terlebih dahulu dan kemudian kembali ke migrasi aplikasi.

Ketika aplikasi dibangun secara lokal tetapi CI gagal, periksa asumsi CocoaPods yang ketinggalan zaman. Penyebab umum adalah jalur pembangunan paksa, perintah .xcworkspace stale pod install 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 build CocoaPods yang dihasilkan, dan CI tidak lagi memerlukan pod install.

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

Sumber Daya

Teruskan dari Cara Migrasi Aplikasi Capacitor ke Manajer Paket Swift

Jika Anda menggunakan Cara Migrasi Aplikasi Capacitor ke Manajer Paket Swift untuk merencanakan migrasi dan operasional perusahaan, hubungkannya dengan Capgo Enterprise untuk alur kerja produk di Capgo Enterprise, Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic, Capgo Alternatif untuk alur kerja produk di Capgo Alternatif, Capgo Konsultasi untuk alur kerja produk di Capgo Konsultasi, dan Capgo Layanan Premium untuk alur kerja produk di Capgo Layanan Premium.

Bagaimana Migrasi Aplikasi Capacitor ke Swift Package Manager