Bagaimana Migrasi Aplikasi Capacitor ke Pengelolaan Ketergantungan Swift Package Manager

Capacitor 8 membuat proyek iOS baru dengan Pengelola Paket Swift (SPM) secara default. Aplikasi yang sudah ada yang masih menggunakan CocoaPods bisa juga di migrasi, tapi jalur yang paling aman tergantung pada seberapa banyak customisasi iOS native aplikasi Anda.

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 akan bergerak ke truk baca-saja. Rencana saat ini adalah truk CocoaPods akan berhenti menerima podspecs baru pada Desember 2, 2026. Bangunan yang sudah ada harus tetap berfungsi, tetapi rilis baru dan pembaruan dependensi yang bergantung pada trunk tidak akan dipublikasikan di sana setelah perubahan.

SPM juga merupakan 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 yang berubah 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 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-SPMPaket ini menjadi tempat pusat di mana Capacitor mengacu pada dependensi plugin iOS native Anda. 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

Penolong migrasi juga menciptakan sebuah file yang dihasilkan debug.xcconfigFile ini membawa pengaturan pembangunan yang CocoaPods dahulu menyediakan melalui file xcconfig yang dihasilkannya

Setelah migrasi, Anda mungkin perlu menambahkan debug.xcconfig ke pengaturan konfigurasi Xcode project jika penolong 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 jika plugin tersebut belum mendukung SPM, update, ganti, atau migrasi plugin terlebih dahulu. Plugin Swift sederhana sering dapat dikonversi dengan capacitor-plugin-convertertetapi 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 project iOS. Kemudian daftar file native yang aplikasi Anda tergantung

File umum untuk menyimpan dari ios/App/ termasuk:

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

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

Opsi 1: Gunakan asisten migrasi Capacitor

Gunakan jalur ini ketika proyek iOS Anda memiliki edit asli native 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 Ketika selesai, buka proyek:

]}

bunx cap open ios

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

Tambahkan CapApp-SPM sebagai dependensi paket lokal.
Tambahkan yang dihasilkan debug.xcconfig ke konfigurasi aplikasi.
Selesaikan peringatan tentang plugin yang tidak dapat dikonversi ke SPM.
Bangun aplikasi dari Xcode sekali sebelum memperbarui CI.

Setelah proyek Xcode dibangun, sinkronisasi lagi:

bunx cap sync ios

Option 2: Re-scaffold proyek iOS dengan SPM

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

Add

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

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

bunx cap open ios

Pada umumnya, jalur ini lebih bersih daripada migrasi langsung karena memberikan Anda template iOS yang segar Capacitor 8. Namun, Anda harus berhati-hati dalam menerapkan kembali tanda tangan, hak istimewa, file Firebase, perubahan kode native, dan pengaturan Xcode yang disesuaikan.

Aplikasi Capacitor baru

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

bunx cap add ios

Jika Anda perlu menentukan secara eksplisit, Anda masih bisa melewati opsi manajer paket:

bunx cap add ios --packagemanager SPM

Perbarui CI setelah migrasi

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
Repositori spesifikasi CocoaPods, jika workflow Anda menyimpannya hanya untuk aplikasi ini

Keep your regular web build and Capacitor sync steps. A typical iOS job should install JavaScript dependencies, build the web assets, sync Capacitor, and then build with 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 terpasang mendukung SPM.
Catat file-file iOS yang diubah dan pengaturan tanda tangan.
Pastikan aplikasi dapat dibangun sebelum migrasi.

Pada saat 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:

Membangun dan menjalankan aplikasi di Xcode.
Menghapus file CocoaPods yang tersisa.
Menghapus pod install dari CI.
Memastikan 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 yang dipaksa, perintah yang ketinggalan zaman, atau cache dari pembangunan sebelumnya. .xcworkspace Kesimpulan pod install Migrasi aplikasi __CAPGO_KEEP_0__ ke Swift Package Manager sebagian besar tentang mengganti pengaturan ketergantungan iOS. Pods/ mengambil alih referensi ketergantungan

mengganti konfigurasi pembangunan CocoaPods yang dihasilkan, dan CI tidak lagi memerlukan

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM Untuk proyek yang dekat dengan template default, re-scaffold SPM yang bersih seringkali lebih cepat dan lebih mudah dipahami. debug.xcconfig Untuk proyek yang dekat dengan template default, re-scaffold SPM yang bersih seringkali lebih cepat dan lebih mudah dipahami. pod install.

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

Ressourcer

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 for the product workflow in Capgo Enterprise, untuk alur kerja produk di __CAPGO_KEEP_0__ Enterprise, dan Penggunaan Produk dalam Alur Kerja Alternatif Ionic Enterprise Plugin Capgo Alternatif Penggunaan Produk dalam Alur Kerja Alternatif Capgo Capgo Konsultasi Penggunaan Produk dalam Alur Kerja Capgo Konsultasi, dan Capgo Layanan Premium Penggunaan Produk dalam Alur Kerja Capgo Layanan Premium.

Bagaimana Migrasi Aplikasi Capacitor ke Pengelola Paket Swift