Bagaimana Migrasi Aplikasi Capacitor ke Pengelolaan Ketergantungan Swift Package Manager

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.

This guide walks through what changes, what to back up, and the two practical migration paths: using the Capacitor migration assistant or re-scaffolding the iOS project with SPM.

Mengapa Migrasi Sekarang

CocoaPods akan bergerak ke arah trunk baca-saja. Rencana saat ini adalah CocoaPods trunk akan berhenti menerima podspecs baru pada 2 Desember 2026. Bangunan yang sudah ada harus tetap berfungsi, tapi rilis baru dan pembaruan dependensi yang bergantung pada trunk tidak akan dipublikasikan di sana setelah perubahan.

SPM is also the direction Capacitor is moving. Capacitor has supported choosing CocoaPods or SPM since Capacitor 6, and Capacitor 8 now creates iOS SPM projects as the default template.

What changes in a Capacitor SPM project

Migrating from CocoaPods to SPM replaces the iOS dependency layer. The web app, Android project, and most Capacitor workflow commands stay the same.

CapApp-SPM Menggantikan Podfile

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

In aplikasi SPM, Capacitor membuat paket lokal bernama CapApp-SPMPaket ini menjadi tempat sentral di mana Capacitor mengacu ketergantungan plugin iOS native Anda. Capacitor CLI memperbarui CapApp-SPM ketika Anda sinkronisasi plugin, jadi lihatlah sebagai output yang dihasilkan dan hindari mengeditnya secara manual.

xcconfig debug menggantikan konfigurasi Pods

Bantuan migrasi juga membuat file yang dihasilkan debug.xcconfigFile 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 bantuan migrasi mengatakan Anda harus melakukannya.

Setiap plugin harus mendukung SPM

You cannot mix CocoaPods and SPM in the same Capacitor iOS project. Before migrating, check every Capacitor and Cordova plugin in package.json.

dan plugin Cordova di capacitor-plugin-converterJika plugin tidak mendukung SPM yet, update, ganti, atau migrasi plugin terlebih dahulu. Plugin Swift sederhana dapat seringkali dikonversi dengan Ionic’s , 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
File khusus .xcconfig file
Pengaturan tanda tangan, identifier paket, ID tim, dan pengaturan profil penyediaan

Juga pertahankan 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 khusus yang Anda tidak ingin kehilangan.

Jalankan asisten dari root project Capacitor Anda:

bunx cap spm-migration-assistant

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

Tambahkan __CAPGO_KEEP_1__ ke konfigurasi aplikasi. CapApp-SPM Penuhi peringatan tentang plugin yang tidak dapat dikonversi ke SPM.
Bangun aplikasi dari Xcode sekali sebelum mengupdate CI. debug.xcconfig Setelah proyek Xcode dibangun, sinkron ulang:
Setelah selesai, buka project:
Lalu ikuti langkah-langkah manual Xcode yang dicetak oleh asisten. Pada proyek kebanyakan ini berarti:

Tambahkan sebagai dependensi paket lokal.

bunx cap sync ios

Option 2: Re-scaffold project iOS dengan SPM

Pilih jalur ini ketika direktori Anda dekat dengan template __CAPGO_KEEP_0__ default 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 diperlukan aplikasi Anda, kemudian buka project:

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 __CAPGO_KEEP_0__ 8 iOS yang segar. Namun, Anda harus berhati-hati dalam menerapkan 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 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
CocoaPods repositori spesifikasi, jika aliran kerja Anda hanya menyimpannya untuk aplikasi ini

Tetapkan langkah-langkah build 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.
Pastikan setiap plugin yang terinstal mendukung SPM.
Rekam file-file iOS dan pengaturan tanda tangan khusus.
Konfirmasi aplikasi dapat dibangun sebelum migrasi.

Pada saat migrasi:

Jalankan bunx cap spm-migration-assistant Migrasikan ke SPM atau CocoaPods ios/.
Tambahkan CapApp-SPM Jika diperlukan, tambahkan di Xcode.
Tambahkan debug.xcconfig Jika diperlukan, tambahkan di Xcode.
Restor file native aplikasi khusus.
Jalankan bunx cap sync ios.

Setelah migrasi:

Bangun dan jalankan aplikasi di Xcode.
Hapus 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

context bunx cap sync ios Halaman/area: Support / halaman dukungan premium atau bagian dukungan di footer. Peran: Judul bagian atau halaman. Dilihat di: halaman support-policy.astro. Kunci pesan `support_policy_troubleshooting_title` (Judul Pengaturan Dukungan)

Jika Xcode tidak dapat menyelesaikan paket, reset cache paket dari Xcode dan jalankan

lagi. .xcworkspace 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. pod install Ketika aplikasi dibangun secara lokal tetapi CI gagal, periksa asumsi CocoaPods yang ketinggalan zaman. Penyebab umum adalah jalur pembangunan yang dipaksa, perintah yang ketinggalan zaman, atau caching dari bangunan sebelumnya. Pods/ Kesimpulan

Migrasi aplikasi __CAPGO_KEEP_0__ ke Pengelola Paket Swift sebagian besar tentang mengganti pengaturan ketergantungan iOS.

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