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 menjelajahi perubahan apa saja, apa yang harus dibackup, dan dua jalur migrasi praktis: menggunakan asisten migrasi Capacitor atau merekonstruksi proyek iOS dengan SPM.

Mengapa migrasi sekarang

CocoaPods sedang bergerak menuju truk baca-saja. 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 sekarang membuat proyek iOS SPM sebagai template default.

Apa saja yang berubah dalam proyek SPM Capacitor

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

CapApp-SPM menggantikan Podfile

Dalam 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 ketergantungan 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 di 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 memerlukan pekerjaan manual.

Apa yang harus dibackup terlebih dahulu

Mulai dari cabang Git yang bersih dan komitkan keadaan 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 project Capacitor Anda:

bunx cap spm-migration-assistant

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

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, sinkron ulang:

protectedTokens

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 diperlukan aplikasi Anda, 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 Anda template iOS __CAPGO_KEEP_0__ yang segar. Namun, Anda harus dengan hati-hati mengaplikasikan tanda tangan, hak akses, file-file Firebase, perubahan kode sumber native, dan pengaturan Xcode kustom apa pun.

bunx cap open ios

Aplikasi Capacitor baru

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

Setelah aplikasi 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
Repositori spesifikasi CocoaPods, jika aliran kerja Anda hanya menyimpannya untuk aplikasi ini saja

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

Sebelum migrasi:

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

Selama 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.
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

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 yang dipaksakan, perintah yang ketinggalan zaman, atau caching .xcworkspace dari bangunan sebelumnya. pod install Kesimpulan Pods/ Migrasi aplikasi __CAPGO_KEEP_0__ ke Swift Package Manager sebagian besar tentang mengganti pengaturan dependensi iOS.

Troubleshooting

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM mengambil alih referensi dependensi, debug.xcconfig mengganti konfigurasi 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

Lanjutkan 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.

Cara Mengganti Capacitor Aplikasi ke Pengelola Paket Swift