Comment migrer votre Capacitor application vers le gestionnaire de packages Swift ?

Le gestionnaire de packages Swift est la direction par défaut pour les projets iOS Capacitor. Si votre application utilise encore CocoaPods, vous pouvez migrer l'application elle-même vers SPM sans reconstruire votre projet JavaScript code, votre projet Android ou votre flux de publication de release depuis zéro.

Cette guide est destiné aux équipes d'applications. Il explique comment migrer une application iOS Capacitor de CocoaPods vers SPM, ce que change l'assistant de migration, ce que vous devez toujours vérifier dans Xcode et comment nettoyer la CI après que l'application a construit.

Quels changements dans l'application

Une application iOS Capacitor basée sur CocoaPods dépend de fichiers tels que :

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

An SPM-based Capacitor app moves iOS dependency wiring into Swift Package Manager. During migration, Capacitor creates a local package named CapApp-SPM and uses it to connect the app target with Capacitor and installed native dependencies.

The web build still works the same way. You still run a web build, sync Capacitor, open Xcode, and archive the app. The main difference is that CocoaPods no longer owns the iOS dependency graph.

Avant de migrer

Commencez d'une branche propre et assurez-vous que l'application fonctionne avant de modifier les gestionnaires de dépendances :

git status
npm run build
npx cap sync ios

Ensuite, commitez l'état fonctionnel. La migration touche les fichiers de projet iOS générés, il est donc important d'avoir un point de rebond propre.

Ensuite, passez en revue ce que votre application a personnalisé sous ios/App/Les fichiers et les paramètres courants à conserver incluent :

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si présent
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, si vous utilisez Firebase
des fichiers personnalisés .xcconfig des fichiers
paramètres de signature, identifiant de l'application, ID d'équipe et profils de provisionnement
extensions de l'application, fichiers Swift natifs, fichiers Objective-C ou frameworks intégrés

Vérifiez également vos dépendances Capacitor et Cordova installées. Une migration SPM d'une application peut être bloquée par une dépendance native qui n'a pas de chemin compatible SPM. Mettez à jour ces packages avant de migrer lorsque possible.

Utilisez l'assistant de migration

Pour la plupart des applications existantes, commencez par l'assistant de migration officiel Capacitor :

npx cap spm-migration-assistant

Exécutez-le depuis la racine de votre projet Capacitor . L'assistant supprime l'intégration CocoaPods, crée le package local, génère des références de package pour les dépendances natives installées et ajoute la configuration générée nécessaire par le projet iOS. CapApp-SPM Après qu'il ait terminé, ouvrez le projet iOS :

Lisez les résultats de l'assistant avant de fermer votre terminal. Si il vous demande de compléter des étapes manuelles dans Xcode, faites-les avant de synchroniser à nouveau.

npx cap open ios

Terminez les étapes Xcode

Dans Xcode, vérifiez la configuration du projet et de la cible de l'application :

Confirmez

Confirmez CapApp-SPM est ajouté comme une dépendance de package local.
Confirmez que les liens de cible de l'application se connectent aux produits de package générés.
Add the generated debug.xcconfig à la configuration du projet si l'assistant vous le demande.
Résolvez tout avertissement de package dans Xcode.
Effectuez une compilation de l'application une fois depuis Xcode.

Si Xcode ne peut pas résoudre les packages, utilisez Outils > Packages > Réinitialiser les caches de packages, puis résolvez à nouveau les packages.

Synchro et rebuild à nouveau

Après que Xcode est configuré, revenez au terminal et synchro Capacitor :

npx cap sync ios

Ensuite, effectuez une compilation à partir de Xcode. N'oubliez pas que la migration n'est considérée comme terminée qu'une fois que vous avez une compilation propre qui fonctionne à partir de Xcode, car la signature de version de sortie, les autorisations, les extensions de l'application et la résolution des packages sont validées là.

If l'application utilise des notifications push, des domaines associés, des modes de fond, des groupes d'application, Firebase ou toute configuration native SDK, exécutez ces flux sur un simulateur ou un appareil après que la construction réussisse.

Alternative : recréer iOS avec SPM

Si votre ios/ dossier est proche du modèle par défaut Capacitor, il peut être plus rapide de le recréer avec SPM au lieu de migrer en place.

Utilisez uniquement cette méthode après avoir commit ou sauvegardé chaque fichier et paramètre natif que vous avez besoin :

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Récupérez ensuite vos fichiers et paramètres natifs spécifiques à l'application. Cette méthode vous donne un projet SPM propre, mais il est plus facile de perdre des modifications Xcode personnalisées si vous n'avez pas inventorié les modifications avant.

Pour de nouvelles applications Capacitor, Capacitor 8 crée des projets iOS avec SPM par défaut :

npx cap add ios

Vous pouvez toujours être explicite :

npx cap add ios --packagemanager SPM

Nettoyez les résidus de CocoaPods

Après que l'application SPM se soit construite, supprimez les hypothèses de CocoaPods restantes des scripts locaux et CI.

Supprimez les étapes comme :

pod install

Supprimez également les caches qui n'existaient que pour CocoaPods :

ios/App/Pods
ios/App/Podfile.lock
CocoaPods dépôts de spécifications
Clés de cache CI basées sur le fichier Podfile

Un flux CI de base après migration devrait installer les dépendances JavaScript, construire l'application web, synchroniser Capacitor et construire avec Xcode :

npm ci
npm run build
npx cap sync ios

Si votre CI construit toujours App.xcworkspace, mettez à jour vers le chemin du projet ou du dossier de travail qui existe après la migration. N'entretenez pas les chemins CocoaPods obsolètes juste parce que l'ancien job les utilisait.

Résolution des problèmes

context : Page/zone : Support / page de support premium ou section de support du pied de page. Rôle : Titre de section ou de page. Vu dans : page support-policy.astro. Clé de message `support_policy_troubleshooting_title` (Titre de la politique de support pour la résolution des problèmes).

Le conseiller alerte sur une dépendance incompatible

Mettez à jour la dépendance en premier et exécutez le conseiller à nouveau. Si aucune version compatible avec SPM n'existe, maintenez l'application sur CocoaPods jusqu'à ce que vous remplacez cette dépendance ou que le mainteneur ajoute le support SPM.

Xcode ne peut pas résoudre les packages CapApp-SPM Réinitialisez les caches de packages dans Xcode, vérifiez que npx cap sync ios est présent en tant que package local, et exécutez :

L'application se construit localement mais la CI échoue

Recherchez les anciennes hypothèses CocoaPods : pod install, Pods/ caches, Podfile.lock clés de cache ou des commandes de construction pointant vers un fichier supprimé .xcworkspace.

La signature ou les autorisations ont changé

Comparez la cible Xcode migrée avec le projet avant migration. Rétablissez l'identifiant de l'application, l'équipe, le profil de provisionnement, le fichier d'autorisations, les capacités et les paramètres d'extension.

Liste de vérification de la migration

Avant la migration :

Créez une branche.
Confirmez que l'application iOS actuelle se construit.
Commitez l'état fonctionnel.
Inventoriez les fichiers natifs personnalisés et les paramètres de signature.
Mettez à jour les dépendances natives qui disposent déjà de versions plus récentes compatibles avec SPM.

Pendant la migration :

Exécutez npx cap spm-migration-assistant.
Ouvrez le projet avec npx cap open ios.
Ajoutez CapApp-SPM en Xcode si nécessaire.
Ajoutez debug.xcconfig en Xcode si nécessaire.
Résolvez les avertissements de package.
Exécutez npx cap sync ios.

Après la migration :

Construirez l'application à partir de Xcode.
Testez les capacités natives sur un simulateur ou un appareil.
Supprimez les commandes CocoaPods de la CI.
Supprimez les caches CocoaPods uniquement.
Vérifiez la signature d'archive et de publication.

Utilisez Capgo Compétences pour la migration.

Si vous utilisez des agents AI pour gérer la migration, commencez par __CAPGO_KEEP_0__ Compétences Capgo Skills de passer en revue la structure de l'application avant de la modifier.

capacitor-best-practices de planifier les étapes de migration SPM et les étapes suivantes de Xcode. ios/.
cocoapods-to-spm de supprimer les hypothèses CocoaPods des pipelines de construction.
capacitor-ci-cd et
debugging-capacitor context : Page/zone : Site web de marketing Capgo. Rôle : Étiquette de navigation ou élément UI court. Vu dans : page trust.astro. Clé de message `et` (Et). ios-android-logs investiguer les problèmes de périphérique uniquement après la migration.

Utilisez-les avant de modifier le projet iOS afin que l'agent audit les fichiers natifs, CI et compatibilité de dépendance au lieu de seulement exécuter la commande de migration.

Conclusion

Migrer une application Capacitor vers le gestionnaire de packages Swift est principalement une modification de gestion de dépendances iOS. Le chemin le plus sûr est de commencer d'une branche propre, exécuter npx cap spm-migration-assistantterminer les étapes manuelles Xcode, synchroniser à nouveau et supprimer CocoaPods de CI uniquement après que l'application s'exécute.

Si votre projet iOS est fortement personnalisé, migrez en place. Si il est proche du modèle de base Capacitor , recréer ios/ avec npx cap add ios --packagemanager SPM ressources

Comment migrer votre application Capacitor vers le gestionnaire de packages Swift