Comment migrer votre application Capacitor vers le gestionnaire de packages Swift

Le gestionnaire de packages Swift est la direction par défaut pour les projets Capacitor iOS. Si votre application utilise toujours 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 l'application.

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

Quels changements dans l'application

Une application 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

Une application Capacitor basée sur SPM déplace la configuration des dépendances iOS dans le gestionnaire de packages Swift. Lors de la migration, Capacitor crée un package local nommé CapApp-SPM et utilise ce package pour relier la cible de l'application avec Capacitor et les dépendances natives installées.

La construction de l'application web fonctionne toujours de la même manière. Vous exécutez toujours une construction de l'application web, synchronisez Capacitor, ouvrez Xcode et archivez l'application. La principale différence est que CocoaPods ne possède plus le graphique de dépendances iOS.

Avant de migrer

Démarrez 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 communs à 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
paramètres de signature personnalisés .xcconfig fichiers
paramètres de signature, identifiant de l'application, ID d'équipe, et profils de provisionnement
extensions d'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 d'application SPM 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 de CocoaPods, crée le local CapApp-SPM package, 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.

Après sa fin, ouvrez le projet iOS :

npx cap open ios

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

Terminez les étapes Xcode

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

Confirmez CapApp-SPM est ajouté comme une dépendance de package locale.
Confirmez que la cible de l'application relie les produits de package générés.
Ajoutez le généré debug.xcconfig à la configuration du projet si l'assistant vous le demande.
Résolvez les avertissements de package dans Xcode.
Construisez l'application une fois à partir de Xcode.

Si Xcode ne peut pas résoudre les packages, utilisez Ouvrez le menu Fichier > Packages > Réinitialiser les caches de packagesEnsuite, résolvez à nouveau les packages.

Effectuez à nouveau la synchronisation et la construction

Après avoir configuré Xcode, revenez au terminal et synchronisez Capacitor :

npx cap sync ios

Construisez ensuite à nouveau depuis Xcode. N'oubliez pas que la migration n'est considérée comme terminée qu'une fois que la construction propre fonctionne depuis Xcode, car la signature de version de sortie, les autorisations, les extensions d'application et la résolution de packages sont validées là.

Si 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 option après avoir commit ou sauvegardé tous les fichiers natifs et les paramètres de signature que vous avez besoin :

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

Restaurez ensuite vos fichiers et paramètres natifs spécifiques à l'application. Cette option 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.

For les nouvelles Capacitor applications, 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 ait été construite, supprimez les hypothèses de CocoaPods restantes des scripts locaux et de CI.

Supprimez les étapes comme :

pod install

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

ios/App/Pods
ios/App/Podfile.lock
Les dépôts de spécifications CocoaPods
Les clés de cache CI basées sur le 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 se 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

Le conseiller avertit sur une dépendance incompatible

Mettez à jour la dépendance en premier et exécutez à nouveau le conseiller. 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

Réinitialisez les caches de packages dans Xcode, vérifiez que CapApp-SPM est présent sous forme de package local, et exécutez npx cap sync ios à nouveau.

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 qui pointent vers un fichier supprimé .xcworkspace.

Les signatures ou les autorisations ont changé

Comparez la cible Xcode migrée avec le projet avant migration. Restaurez 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 migration

Avant la migration :

Créer une branche.
Confirmer que l'application iOS actuelle se construit.
Commiter l'état de travail.
Inventorier les fichiers natifs personnalisés et les paramètres de signature.
Mettre à jour les dépendances natives qui ont déjà des versions plus récentes compatibles avec SPM.

Pendant la migration :

Exécuter npx cap spm-migration-assistant.
Ouvrir le projet avec npx cap open ios.
Ajouter CapApp-SPM dans Xcode si nécessaire.
Ajoutez debug.xcconfig dans 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 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 Compétences Capgo au lieu d'une invitation vide. Les compétences les plus utiles pour ce travail sont :

capacitor-best-practices de passer en revue la structure de l'application avant de la modifier ios/.
cocoapods-to-spm de planifier les étapes de migration de SPM et de Xcode.
capacitor-ci-cd et
debugging-capacitor de rechercher les problèmes spécifiques aux appareils après la migration. ios-android-logs Utilisez-les avant de modifier le projet iOS afin que l'agent audit les fichiers natifs, CI et compatibilité des dépendances au lieu de seulement exécuter la commande de migration.

Conclusion

Migrer une application __CAPGO_KEEP_0__ vers Swift Package Manager est principalement une modification de gestion de dépendances iOS. Le chemin le plus sûr est de commencer d'une branche vierge, de lancer

Migrating a Capacitor app to Swift Package Manager is mostly an iOS dependency-management change. The safest path is to start from a clean branch, run npx cap spm-migration-assistantSi votre projet iOS est fortement personnalisé, migrez en place. Si il est proche du modèle de base __CAPGO_KEEP_0__ , recréez

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