Comment Migrer une Application Capacitor vers le Gestionnaire de Packages Swift

Capacitor 8 crée de nouveaux projets iOS avec Swift Package Manager (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 qu'il faut sauvegarder 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 que le tronc CocoaPods cesse d'accepter de nouvelles spécifications de pod le 2 décembre 2026. Les builds existantes devraient continuer à fonctionner, mais les nouvelles publications et les mises à jour de dépendances qui dépendent du tronc ne seront plus publiées après le basculement.

SPM est également la direction que Capacitor est en train de prendre. Capacitor a soutenu la sélection de 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

La migration de CocoaPods à 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 connecté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-SPM. Ce package devient le lieu central où Capacitor référence vos dépendances de plugin iOS natif. Le Capacitor CLI met à jour CapApp-SPM lorsque vous synchronisez les plugins, il est donc à considérer comme un résultat généré et éviter de le modifier manuellement.

debug.xcconfig remplace la configuration Pods

L'assistant de migration crée également un fichier généré debug.xcconfig. Ce 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-le à jour, le remplacez ou migrez le plugin en premier. Les plugins Swift simples peuvent souvent être convertis avec Ionic’s capacitor-plugin-converter, mais les plugins avec des layouts Objective-C et Swift plus complexes nécessiteront du travail manuel.

Quels fichiers sauvegarder en premier

Commencez 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 communs à conserver de ios/App/ include:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, si votre application en a un
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 comporte 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 les 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 est terminé, ouvrez le projet :

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

bunx cap open ios

Ajoutez

comme une dépendance de package local. CapApp-SPM Ajoutez le
à la configuration de l'application. debug.xcconfig Résolvez les avertissements concernant les plugins qui ne peuvent pas être convertis en SPM.
Construirez l'application à partir d'Xcode une fois avant de mettre à jour CI.
Après que le projet Xcode ait été construit, synchronisez à nouveau :

protectedTokens

bunx cap sync ios

Option 2 : Re-scaffoldez 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 restaurer en toute sécurité 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

Restaurez 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 modèle Capacitor 8 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.

Nouveaux projets Capacitor

Pour un nouveau projet, 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 s'exécutent :

pod install

Supprimez également les caches pour :

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

Conservez vos étapes de construction web régulières et Capacitor de synchronisation. Une tâche iOS typique devrait installer les dépendances JavaScript, construire les actifs web, synchroniser Capacitor, puis construire avec Xcode :

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Liste de vérification de migration

Avant la migration :

Créez une nouvelle branche Git.
Commitez l'application en cours de travail.
Vérifiez que chaque plugin installé prend en charge SPM.
Enregistrez les fichiers et les paramètres de signature iOS personnalisés.
Confirmez que l'application se construit avant la migration.

Pendant la migration :

Exécutez bunx cap spm-migration-assistant ou re-scaffolder ios/.
Ajouter CapApp-SPM Ajouter dans Xcode si nécessaire.
Ajouter debug.xcconfig Ajouter 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érifiez que la signature de la version fonctionne toujours.
Exécutez l'application sur au moins un simulateur et un appareil réel avant de la livrer.

Dépannage

Si Xcode ne peut pas résoudre les packages, réinitialisez les caches de packages à partir de Xcode et exécutez à nouveau. bunx cap sync ios Si la migration échoue en raison d'un plugin, vérifiez si le plugin a une nouvelle version 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 des caches provenant de précédentes constructions.

Conclusion .xcworkspace Migrer une application __CAPGO_KEEP_0__ vers Swift Package Manager est principalement question de remplacer la mise en relation des dépendances iOS. pod install Troubleshooting Pods/ If Xcode cannot resolve packages, reset package caches from Xcode and run again.

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.

Migrating a Capacitor app to Swift Package Manager is mostly about replacing the iOS dependency wiring. CapApp-SPM prend en charge les références de dépendances, debug.xcconfig remplace la configuration de build CocoaPods générée, et le CI n'a plus besoin de pod install.

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

Ressources

Continuez de la section 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 à Capgo Entreprise pour le flux de travail du produit dans Capgo Entreprise, Alternatives d'extension d'entreprise Ionic pour le flux de travail du produit dans Alternatives d'extension d'entreprise Ionic, Capgo Alternatives pour le flux de travail du produit dans Capgo Alternatives, Capgo Conseil pour le flux de travail du produit dans Capgo Conseil, et Capgo Support Premium pour le flux de travail du produit dans Capgo Support Premium.

Comment migrer une application Capacitor vers Swift Package Manager