Configuration xcconfig multi-environnements : tutoriel de compilation iOS à distance 2026

Votre Release locale fonctionne, mais l’Archive distante pointe encore vers l’API de test.

La solution la plus rapide consiste à versionner une base xcconfig publique, injecter les secrets hors dépôt, puis contrôler les valeurs réellement présentes dans l’Archive finale.

Cette méthode convient aux indépendants qui maintiennent des environnements de développement, de test et de production et veulent réduire les écarts dans les Xcode Build Settings. Elle s’adresse aussi aux petites équipes qui déplacent leur projet vers un Mac distant, ainsi qu’à celles qui automatisent l’Archive sans vouloir exposer leurs clés ni leurs certificats.

Une base partagée vaut mieux que plusieurs Targets presque identiques

Le premier réflexe consiste souvent à créer un Target pour chaque environnement. Cette organisation semble lisible au début, mais elle duplique progressivement les Bundle ID, les droits, les réglages de compilation et les phases de copie. Une correction appliquée au Target de production peut alors manquer celui de test, tandis qu’un réglage utile au développement reste invisible dans l’environnement distant.

Pour une application unique, séparez plutôt les responsabilités :

• le Scheme choisit une combinaison de configuration et d’actions, comme Run, Test ou Archive ;
• le Build Configuration représente une variante de compilation, par exemple Debug, Staging ou Release ;
• le Target décrit ce qui est effectivement construit et livré ;
• le fichier xcconfig regroupe des valeurs de Build Settings lisibles et réutilisables ;
• le fichier Info.plist reçoit certaines valeurs après expansion, mais ne remplace pas la logique de sélection d’environnement ;
• la configuration d’exécution décide éventuellement d’un comportement après le lancement de l’application.

Apple décrit le fichier de configuration comme un fichier texte destiné à enregistrer et combiner des réglages de compilation. Il ne constitue ni un coffre-fort, ni un système autonome de bascule d’API. Vous pouvez vérifier ce rôle dans la documentation Apple sur l’ajout d’un fichier Build Configuration.

Adoptez une séparation en couches :

1. Base partagée : version minimale de Swift, réglages communs, options de compilation et valeurs nécessaires à tous les Targets.
2. Différences publiques : URL non sensibles, identifiants de bundle non secrets, nom d’environnement visible, indicateurs de fonctionnalités.
3. Entrées externes : clés privées, mots de passe, jetons d’envoi, chemins propres à la machine et paramètres fournis par le serveur de compilation.

Cette répartition évite de copier les réglages par environnement. Elle vous oblige aussi à déterminer si une valeur appartient au projet, au Target, au Scheme ou au processus d’exécution.

Attention. La présence d’une ligne dans un fichier xcconfig ne prouve pas qu’elle est active. Un réglage peut être remplacé par le projet, le Target, un autre fichier de configuration ou un paramètre transmis à la compilation. Contrôlez toujours la valeur calculée par Xcode.

Pour chaque valeur critique, utilisez l’inspecteur de Build Settings et recherchez la colonne indiquant la source effective. La référence Apple des Build Settings rappelle que les réglages peuvent provenir de plusieurs niveaux et que leur valeur finale dépend de cette combinaison.

Projet simple : Debug et Release sans recopier Xcode

Si votre application ne possède que Debug et Release, commencez par extraire uniquement ce que vous maîtrisez. Ne copiez pas toute la liste affichée par Xcode dans le fichier xcconfig. Une telle copie fige des valeurs par défaut et rend les mises à jour de Xcode plus difficiles à analyser.

Dans la base partagée, conservez par exemple :

• les options de compilation réellement choisies par le projet ;
• les indicateurs communs à toutes les variantes ;
• les paramètres non sensibles nécessaires à la génération d’Info.plist ;
• les conventions de nommage utilisées par les scripts.

Dans le fichier propre à Release, placez seulement les différences de production. L’adresse d’une API publique peut y figurer si elle ne contient ni identifiant secret ni information permettant d’accéder à un service protégé. En revanche, une clé d’API, un jeton d’écriture ou un mot de passe de signature doit rester hors du dépôt.

Les API et les adresses de serveur doivent-elles figurer dans xcconfig ?

Une adresse de serveur non confidentielle peut être déclarée dans xcconfig comme différence d’environnement. Une API Key ne doit pas être considérée comme protégée parce qu’elle se trouve dans un fichier texte moins visible dans Xcode : si elle est nécessaire à l’application, elle peut souvent être extraite du paquet ou des journaux.

Pour une clé utilisée uniquement pendant la compilation, injectez-la depuis l’environnement contrôlé du Mac distant ou depuis un fichier local non suivi par Git. Pour une clé utilisée à l’exécution, examinez plutôt un service intermédiaire, une configuration distribuée selon votre modèle de menace ou une fonctionnalité côté serveur. xcconfig ne fournit aucune sécurité automatique pour ces usages.

Validez ensuite séparément :

• Build Debug : l’application utilise l’environnement de développement et ses identifiants de test ;
• Archive Release : le paquet adopte la configuration de production et ses droits de distribution ;
• Info.plist développé : les variables remplacées correspondent réellement à la variante construite.

Ne concluez pas qu’un Build réussi prouve que l’Archive est correcte. Un Build local peut utiliser une valeur conservée dans votre environnement, alors qu’un nouveau Mac ne dispose pas de cette variable.

Plusieurs environnements : Scheme explicite, valeurs héritées contrôlées

Dès que vous avez développement, test et production, créez des Build Configurations distinctes et associez-les à des Schemes nommés sans ambiguïté. Par exemple, un Scheme de test doit sélectionner la configuration de test pour Run, Test et Archive si cette action est autorisée. Le Scheme de production doit rendre l’Archive de production difficile à lancer par erreur, tout en restant exploitable par l’automatisation.

Comment distinguer proprement développement, test et production avec xcconfig ?

Déclarez les valeurs communes dans un fichier de base, puis utilisez un fichier par environnement pour les différences publiques. Faites hériter chaque configuration de la base et vérifiez les clés homonymes : une valeur redéfinie au niveau du Target ou du projet peut masquer celle du fichier attendu.

Contrôlez notamment :

• l’adresse de service injectée dans Info.plist ;
• le nom d’environnement affiché dans l’application ;
• le Bundle ID final ;
• les droits associés à ce Bundle ID ;
• les paramètres de signature attendus ;
• les variables consommées par les scripts d’Archive.

La documentation Apple sur la personnalisation des Build Schemes explique où associer les actions et les configurations. Servez-vous-en pour inspecter Run, Test, Profile, Analyze et Archive, plutôt que de supposer qu’un Scheme porte automatiquement le fichier xcconfig voulu.

Ajoutez aussi une barrière de sécurité dans le processus de publication. Si une Archive de production contient une URL de test, un nom de variante non attendu ou un identifiant de bundle incohérent, le processus doit s’arrêter. Cette règle est plus fiable qu’une consigne demandant au développeur de « vérifier avant d’envoyer ».

Plusieurs Targets : partager les réglages, isoler les droits

Un Widget, une extension Share, une extension de notification ou une cible macOS ne doit pas être traité comme une simple copie de l’application principale. Le projet peut partager une base de compilation, mais chaque Target doit posséder les réglages qui lui sont propres.

Faut-il créer plusieurs Targets ou plusieurs Build Configurations ?

Utilisez plusieurs Build Configurations lorsque le produit reste le même et que seules l’environnement, certaines options ou les services associés changent. Utilisez plusieurs Targets lorsque les paquets livrés diffèrent réellement : Bundle ID, ressources, capacités, extensions ou comportement de distribution.

Si deux Targets ne se distinguent que par l’URL de service, dupliquez probablement trop de structure. Si une extension possède ses propres entitlements, son App Group ou son identifiant, elle doit conserver une frontière explicite.

La documentation Apple consacrée à la construction de plusieurs Targets constitue la référence pour cette organisation. Après chaque modification de la base xcconfig, examinez séparément les valeurs calculées de tous les Targets inclus dans le paquet :

• Bundle ID de l’application et des extensions ;
• App Group ;
• entitlements ;
• version minimale du système ;
• ressources et fichiers Info.plist ;
• paramètres spécifiques aux plateformes ou aux architectures.

Un Archive réussi pour l’application principale ne valide donc pas automatiquement un Widget ou une extension de notification. Une extension peut compiler avec une valeur héritée incorrecte et ne révéler le problème qu’au moment de l’installation ou de l’exécution.

Expérience de maintenance. Si le même réglage apparaît dans la base, le fichier d’environnement, le projet et le Target, ne cherchez pas d’abord à mémoriser la priorité. Supprimez les duplications, puis conservez une seule source intentionnelle. Une hiérarchie courte est plus facile à auditer sur une machine distante.

Mac distant : restaurer les entrées publiques sans transporter les secrets

Sur un Mac distant, le problème n’est pas seulement de lancer la compilation. Il faut reconstruire un environnement qui ne dépend ni d’un fichier oublié dans votre dossier personnel, ni d’un chemin absolu, ni d’une variable définie uniquement dans votre session interactive.

Pourquoi xcconfig fonctionne-t-il localement mais pas sur un Mac distant ?

Les causes les plus fréquentes sont l’absence du fichier référencé dans le dépôt, un chemin relatif incorrect, une variable non injectée, un Scheme non partagé ou une valeur remplacée par un paramètre de ligne de commande. Le projet peut donc s’ouvrir correctement tout en produisant une Archive différente.

Procédez dans cet ordre :

1. Nettoyez le dépôt : confirmez que les fichiers xcconfig publics, les projets Xcode, les Schemes partagés et les scripts nécessaires sont suivis par le contrôle de version.
2. Éliminez les chemins locaux : remplacez les références propres à votre ordinateur par des chemins relatifs ou des variables explicitement fournies.
3. Définissez les entrées externes : préparez dans le Mac distant ou son orchestrateur les valeurs qui ne doivent pas entrer dans Git.
4. Vérifiez l’association des fichiers : ouvrez le projet et contrôlez la configuration assignée au projet et à chaque Target.
5. Lancez un Build non interactif : utilisez le Scheme attendu et conservez les journaux de résolution des réglages.
6. Redémarrez puis recommencez : une session propre doit retrouver la même configuration sans dépendre d’un état conservé.
7. Produisez une Archive Release : inspectez son contenu et ses métadonnées, pas seulement le code de retour de la commande.

Ces étapes ne constituent pas une recette complète de CI. Elles servent à prouver que la configuration du dépôt est portable. Pour un premier déploiement, vous pouvez consulter notre guide sur la préparation et la vérification d’un environnement iOS sur Mac distant. Si votre chaîne doit rester accessible pendant les compilations, comparez aussi les options de nœuds de calcul Mac M4, sans confondre disponibilité de la machine et validité de votre projet.

Séparez clairement les éléments suivants :

• les paramètres de compilation publics ;
• les valeurs d’exécution de l’application ;
• les certificats et profils de provisioning ;
• les mots de passe associés à la signature ;
• les identifiants et jetons d’envoi vers App Store Connect.

La création d’un profil de provisioning doit suivre le compte Apple Developer et le type de distribution requis, comme l’indique la procédure officielle de création d’un App Store Provisioning Profile. Ne transformez pas les profils ou les certificats en variables xcconfig simplement parce qu’ils sont nécessaires à l’Archive.

Archive finale : passer d’une compilation réussie à une décision publiable

L’Archive est le point de contrôle où vous devez abandonner les suppositions. Apple décrit la création d’un App Archive dans son aide Xcode dédiée à l’archivage, puis propose une procédure distincte pour valider une App Archive.

Avant de transmettre le paquet, contrôlez la configuration réellement utilisée, le Bundle ID, l’environnement de service, les entitlements et les symboles nécessaires. Ajoutez un test négatif : recherchez les adresses, noms ou marqueurs propres au test et faites échouer l’Archive si l’un d’eux apparaît dans une production.

Comment confirmer qu’une Archive utilise le bon xcconfig ?

Ne vous contentez pas de voir le fichier dans le navigateur du projet. Vérifiez la valeur finale dans Xcode, reproduisez l’Archive sur un dépôt fraîchement récupéré, puis inspectez le produit généré. Si le projet est automatisé, imprimez uniquement les métadonnées non sensibles nécessaires au diagnostic ; ne versez jamais les secrets dans les journaux.

Utilisez ensuite cette décision :

• Si chaque valeur publique est versionnée, les secrets sont injectés séparément, le Scheme est partagé et l’Archive distante reproduit la configuration attendue, alors conservez l’organisation actuelle et documentez ses points de contrôle.
• Si l’Archive fonctionne seulement sur votre poste, alors revenez à la dépendance manquante : fichier non suivi, variable externe, chemin absolu ou réglage local.
• Si les valeurs changent entre Build et Archive, alors inspectez l’action Archive du Scheme et les paramètres transmis à la compilation avant de modifier les Targets.
• Si plusieurs Targets héritent de droits ou d’identifiants incorrects, alors conservez la base commune, mais déplacez les réglages spécifiques au niveau du Target concerné.
• Si vous ne pouvez pas reproduire l’Archive après redémarrage, alors l’environnement n’est pas encore prêt pour une publication automatisée.

Voici une grille de choix pour éviter de déplacer un projet fragile sur un Mac distant :

Le tableau suivant vous aide à attribuer chaque élément au bon emplacement, plutôt qu’à l’ajouter indistinctement au fichier xcconfig :

La limite de cette méthode est importante : elle ne rend pas automatiquement vos secrets sûrs, ne remplace pas la gestion des certificats et ne garantit pas la cohérence d’une configuration d’exécution. Elle fournit une organisation vérifiable des Build Settings, à condition que vous contrôliez la valeur finale et le produit réellement archivé.

Si vous compilez encore sur votre ordinateur principal, vous conservez souvent trois défauts : l’environnement dépend de fichiers locaux invisibles, la machine n’est pas forcément disponible pour une Archive répétée et les erreurs de configuration apparaissent tard lorsque vous changez de poste. Un Mac distant ne supprime pas ces risques par magie, mais il vous donne un environnement séparé, accessible pour les validations et réinitialisable lorsque le dépôt doit être testé proprement. Pour une machine temporaire ou une série d’Archives de contrôle, louer un Mac auprès de MacDate peut donc être plus cohérent que maintenir un ordinateur personnel allumé en permanence ; vous gardez toutefois intérêt à acheter votre propre Mac si la charge est quotidienne, durable ou dépend d’interfaces physiques locales.

Commencez par récupérer le dépôt sur un environnement propre, injectez uniquement les valeurs nécessaires, puis exigez une Archive Release vérifiée après redémarrage. Si cette validation passe, vous disposez d’une base fiable pour automatiser davantage ; si elle échoue, corrigez la hiérarchie xcconfig avant de multiplier les Targets ou de changer de service.