Comment migrer une application Capacitor vers le gestionnaire de packages Swift

Capacitor 8 crée de nouveaux projets iOS avec le gestionnaire de packages Swift (SPM) par défaut. Les applications existantes qui utilisent encore CocoaPods peuvent migrer également, mais la voie la plus sûre dépend de la quantité de personnalisation native iOS que votre application a.

Cette guide passe en revue les changements, ce qui doit être sauvegardé et les deux chemins de migration pratiques : utiliser l'assistant de migration Capacitor ou restructurer le projet iOS avec SPM.

Pourquoi migrer maintenant

CocoaPods se tourne vers un tronc en lecture seule. Le plan actuel est de faire cesser l'acceptation de nouvelles podspecs sur le tronc de CocoaPods le 2 décembre 2026Les builds existants devraient continuer à fonctionner, mais les nouvelles versions et les mises à jour de dépendances qui dépendent de la branche principale ne seront plus publiées après le changement.

SPM est également la direction que Capacitor est en train de prendre. Capacitor a soutenu la possibilité de choisir CocoaPods ou SPM depuis Capacitor 6, et Capacitor 8 crée désormais des projets iOS SPM par défaut.

Quels changements dans un projet SPM Capacitor

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 remplace le fichier Podfile

Dans une application CocoaPods, les dépendances iOS sont connectées par ios/App/Podfile, Podfile.lock, Pods/CapApp-SPM remplace le fichier Podfile .xcworkspace.

Dans une application SPM, Capacitor crée un package local nommé CapApp-SPM. This package becomes the central place where Capacitor references your native iOS plugin dependencies. The Capacitor CLI updates CapApp-SPM lorsque vous synchronisez les plugins, traitez-le donc comme un résultat généré et évitez de le modifier à la main.

debug.xcconfig remplace la configuration Pods

L'assistant de migration crée également un debug.xcconfigCe fichier contient les paramètres de construction que CocoaPods fournissait précédemment à travers ses fichiers xcconfig générés.

Après la migration, vous devrez peut-être ajouter debug.xcconfig à la configuration du projet Xcode si l'assistant vous le demande.

Chaque plugin doit supporter SPM

Vous ne pouvez pas mélanger CocoaPods et SPM dans le même projet iOS Capacitor. Avant de migrer, vérifiez chaque Capacitor et plugin Cordova dans package.json.

Si un plugin ne supporte pas encore SPM, mettez-l’à jour, le remplacez ou migrez le plugin en premier. Les plugins Swift simples peuvent souvent être convertis avec Ionic’s capacitor-plugin-convertermais les plugins avec des layouts Objective-C et Swift plus complexes peuvent nécessiter du travail manuel.

Qu'est-ce à sauvegarder en premier

Commencez d'une branche Git propre et commitez votre état actuel avant de toucher le projet iOS. Ensuite, listez les fichiers natifs dont votre application a besoin.

Fichiers courants à conserver de ios/App/ incluent :

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swiftle fichier __CAPGO_KEEP_1__ si votre application en a un
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistSi vous utilisez Firebase
Personnalisé .xcconfig fichiers
Paramètres de signature, identifiant de bundle, ID d'équipe, et paramètres de profil de provisionnement

Conservez également tout fichier natif Swift, Objective-C, framework, extension ou SDK que vous avez ajouté en dehors du modèle standard Capacitor.

Option 1 : Utilisez l'assistant de migration Capacitor

Utilisez cette option lorsque votre projet iOS comporte des éditions natives personnalisées que vous ne souhaitez pas perdre.

Lancez l'assistant depuis la racine de votre projet Capacitor :

bunx cap spm-migration-assistant

L'assistant supprime l'infrastructure CocoaPods, crée l'infrastructure locale CapApp-SPM package, génère des références de package à partir de vos plugins installés, et crée les fichiers de configuration SPM générés.

Lorsqu'il est terminé, ouvrez le projet :

bunx cap open ios

Suivez ensuite les étapes manuelles d'Xcode imprimées par l'assistant. Dans la plupart des projets, cela signifie :

ajoutez CapApp-SPM en tant que dépendance de package local.
ajoutez le générateur debug.xcconfig à la configuration de l'application.
Résolvez tout avertissement concernant des plugins qui ne pouvaient pas être convertis en SPM.
Build the app from Xcode once before updating CI.

Après la construction du projet Xcode, synchronisez à nouveau :

bunx cap sync ios

Option 2 : Re-scaffold le projet iOS avec SPM

Utilisez cette voie lorsque votre ios/ dossier est proche du modèle par défaut Capacitor et que vous pouvez restaurer les fichiers personnalisés ultérieurement.

Tout d'abord, assurez-vous que les fichiers listés dans la section de sauvegarde sont commités ou copiés quelque part en sécurité. Ensuite, supprimez et recréez le projet iOS avec SPM :

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

Restaurer les fichiers natifs dont votre application a besoin, puis ouvrez le projet :

bunx cap open ios

Cette méthode est souvent plus propre qu'une migration en place car elle vous donne un Capacitor 8 modèl’iOS frais. Le compromis est que vous devez réappliquer soigneusement la signature, les autorisations, les fichiers Firebase, les modifications de source native et les paramètres Xcode personnalisés.

Capacitor applications nouvelles

Pour une nouvelle application, Capacitor 8 utilise SPM par défaut lors de l'ajout d'iOS :

bunx cap add ios

Si vous devez être explicite, vous pouvez toujours passer l'option de gestionnaire de package :

bunx cap add ios --packagemanager SPM

Mettre à jour CI après la migration

Une fois l'application construite localement, mettez à jour CI/CD pour qu'elle ne suppose plus CocoaPods.

Supprimer les étapes qui exécutent :

pod install

Supprimer également les caches pour :

ios/App/Pods
ios/App/Podfile.lock
Les référentiels de spécifications CocoaPods, si votre workflow les a stockés uniquement pour cette application

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

Guide de migration

Avant la migration :

Créer une nouvelle branch Git.
Valider les modifications actuelles de l'application.
Vérifier que chaque plugin installé prend en charge SPM.
Record custom iOS files and signing settings.
Confirmer que l'application se construit avant la migration.

Pendant la migration :

Exécuter bunx cap spm-migration-assistant ou restructurer ios/.
Ajouter CapApp-SPM dans Xcode si nécessaire.
Ajouter debug.xcconfig dans Xcode si nécessaire.
Restaurer les fichiers natifs de l'application.
Exécuter bunx cap sync ios.

Après la migration :

Construire et exécuter l'application dans Xcode.
Supprimer les fichiers CocoaPods restants.
Supprimer pod install de la CI.
Verify release signing still works.
Exécuter l'application sur au moins un simulateur et un appareil réel avant de le livrer.

Troubleshooting

Si Xcode ne peut pas résoudre les packages, réinitialiser les caches de packages depuis Xcode et exécuter bunx cap sync ios à nouveau.

If the migration fails because of a plugin, check whether the plugin has a newer release with SPM support. For plugins you maintain, migrate the plugin package first and then return to the app migration.

Lorsque l'application se construit localement mais que la CI échoue, vérifiez les anciennes hypothèses de CocoaPods. .xcworkspace chemin de build, un obsolète pod install commande, ou mise en cache Pods/ de précédentes constructions.

Conclusion

Migrer une application Capacitor vers le gestionnaire de packages Swift consiste principalement à remplacer la configuration des dépendances iOS. CapApp-SPM prend en charge les références de dépendances. debug.xcconfig replaces la configuration de build CocoaPods générée, et le CI n'a plus besoin pod install.

Pour les projets iOS personnalisés, commencez par bunx cap spm-migration-assistantPour les projets proches du modèle par défaut, une restructuration SPM propre est souvent plus rapide et plus facile à comprendre.

context

Continuez à partir de Comment migrer une application Capacitor vers le gestionnaire de packages Swift

Si vous utilisez Comment migrer une application Capacitor vers le gestionnaire de packages Swift pour planifier la migration et les opérations d'entreprise, connectez-l’à Capgo Entreprise pour le flux de travail du produit dans Capgo Enterprise, Alternatives de plugins Ionic Enterprise pour le flux de travail du produit dans les alternatives Ionic Enterprise Plugin Alternatives de Capgo pour le flux de travail du produit dans Capgo Alternatives Consultation de Capgo pour le flux de travail du produit dans Capgo Consulting, et Support Premium de Capgo Pour le flux de travail du produit dans Capgo Support Premium.