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 spécifications de pod sur le tronc de CocoaPods 2 décembre 2026Les builds existants devraient continuer à fonctionner, mais les nouvelles publications et les mises à jour de dépendances qui dépendent de la branche trunk ne seront plus publiées après le basculement.

SPM est également la direction vers laquelle se déplace Capacitor. 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 Capacitor SPM

La migration de CocoaPods vers SPM remplace la couche de dépendances iOS. L'application web, le projet Android et la plupart des commandes de flux de travail Capacitor restent les mêmes.

CapApp-SPM remplace le fichier Podfile

Dans une application CocoaPods, les dépendances iOS sont liées via ios/App/Podfile, Podfile.lock, Pods/et le fichier généré .xcworkspace.

Dans une application SPM, Capacitor crée un package local nommé CapApp-SPMCe package devient le point central où Capacitor référence vos dépendances de plugins iOS natifs. Les Capacitor CLI sont mis à jour CapApp-SPM lorsque vous synchronisez les plugins, il faut donc les traiter comme des sorties générées et éviter de les modifier manuellement.

debug.xcconfig remplace la configuration Pods

The assistant de migration crée également un fichier généré debug.xcconfigCe fichier contient les paramètres de build que CocoaPods utilisait à l'origine pour fournir à 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 suggère.

Tout 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-le à 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 nécessitent peut-être du travail manuel.

Qu'est-ce qu'il faut sauvegarder en premier

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

Fichiers courants à conserver de ios/App/ comprennent :

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

Conservez également tout fichier Swift natif, 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 ce chemin lorsque votre projet iOS a des éditions natives personnalisées que vous ne souhaitez pas perdre.

Exécutez l'assistant depuis la racine de votre projet Capacitor :

bunx cap spm-migration-assistant

L'assistant supprime l'infrastructure CocoaPods, crée le package local, 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. CapApp-SPM Lorsqu'il a terminé, ouvrez le projet :

bunx cap open ios

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

Ajouter CapApp-SPM en tant que dépendance de package local.
Ajoutez le généré debug.xcconfig à la configuration de l'application.
Résolvez les avertissements concernant les plugins qui ne peuvent pas être convertis en SPM.
Construire l'application à partir de Xcode une fois avant de mettre à jour CI.

Après que le projet Xcode ait été construit, synchronisez à nouveau :

bunx cap sync ios

Option 2 : Ré-structurer à nouveau le projet iOS avec SPM

Utilisez ce chemin lorsque votre ios/ répertoire est proche du modèle par défaut Capacitor et que vous pouvez sécuriser 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 toute 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 ouvrir le projet :

bunx cap open ios

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

Nouveaux Capacitor d'applications

Pour une nouvelle application, Capacitor 8 utilise par défaut SPM 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 afin qu'elle ne suppose plus que CocoaPods.

Supprimer les étapes qui s'exécutent :

pod install

Supprimer également les caches pour :

ios/App/Pods
ios/App/Podfile.lock
Les dépôts de spécifications CocoaPods, si votre flux de travail 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

Liste de vérification de la migration

Avant la migration :

Créer une nouvelle branche Git.
Valider les fichiers de travail actuels.
Vérifier que chaque plugin installé prend en charge SPM.
Enregistrer les fichiers iOS personnalisés et les paramètres de signature.
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 spécifiques à l'application.
Exécuter bunx cap sync ios.

Après migration :

Construire et exécuter l'application dans Xcode.
Supprimer les fichiers CocoaPods restants.
Supprimer pod install à partir de CI.
Vérifier que la signature de versionnalisation fonctionne toujours.
Exécuter l'application sur au moins un simulateur et un appareil réel avant la livraison.

Dépannage

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

Si la migration échoue en raison d'un plugin, vérifiez si le plugin a une mise à jour plus récente avec prise en charge de SPM. Pour les plugins que vous maintenez, migrez d'abord le package du plugin et revenez ensuite à la migration de l'application.

Lorsque l'application se construit localement mais que CI échoue, vérifiez les anciennes hypothèses de CocoaPods. Les causes courantes sont un chemin de construction forcé, une commande obsolète, ou un cache provenant de constructions précédentes. .xcworkspace Conclusion pod install La migration d'une application __CAPGO_KEEP_0__ vers Swift Package Manager est principalement axée sur la remplacement de la mise en relation des dépendances iOS. Pods/ SPM prend en charge les références de dépendances, remplace la configuration de construction CocoaPods générée, et CI n'a plus besoin de

Pour les projets iOS personnalisés, commencez par

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM Si la migration échoue en raison d'un plugin, vérifiez si le plugin a une mise à jour plus récente avec prise en charge de SPM. Pour les plugins que vous maintenez, migrez d'abord le package du plugin et revenez ensuite à la migration de l'application. debug.xcconfig Lorsque l'application se construit localement mais que CI échoue, vérifiez les anciennes hypothèses de CocoaPods. Les causes courantes sont un chemin de construction forcé, une commande obsolète, ou un cache provenant de constructions précédentes. pod install.

Conclusion bunx cap spm-migration-assistantLa migration d'une application __CAPGO_KEEP_0__ vers Swift Package Manager est principalement axée sur la remplacement de la mise en relation des dépendances iOS.

Ressources

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-le avec Capgo Enterprise pour le flux de travail du produit dans Capgo Enterprise, Alternatives de plugins d'entreprise Ionic Enterprise pour le flux de produit dans les alternatives Ionic Enterprise Plugin Capgo Alternatives pour le flux de produit dans Capgo Alternatives Capgo Consulting pour le flux de produit dans Capgo Consulting, et Capgo Premium Support for the product workflow in Capgo Premium Support.