Ce guide aide les développeurs indépendants à diagnostiquer un Canvas SwiftUI qui ne démarre pas, se recharge sans fin ou affiche un résultat incohérent. Nous séparons les problèmes de code, de données, de dépendances, de runtime et de session graphique, puis proposons une procédure de validation adaptée à un Mac distant.
Ce guide aide les développeurs indépendants à diagnostiquer un Canvas SwiftUI qui ne démarre pas, se recharge sans fin ou affiche un résultat incohérent. Nous séparons les problèmes de code, de données, de dépendances, de runtime et de session graphique, puis proposons une procédure de validation adaptée à un Mac distant.
Le Canvas reste vide, affiche une erreur de prévisualisation ou recommence son actualisation sans fin, alors que l’application fonctionne parfois dans le simulateur.
Solution la plus rapide : ne supprimez pas tout le cache et ne réinstallez pas Xcode en premier. Générez d’abord le rapport Previews Diagnostics, puis classez l’échec entre code de vue, dépendance, runtime du simulateur et environnement macOS ; sur un Mac distant, vérifiez aussi la session graphique et les droits des dossiers.
Ce guide s’adresse aux développeurs indépendants qui utilisent SwiftUI Preview pour itérer sur une interface iOS ou macOS, mais dont le Canvas ne démarre plus ou ne se met plus à jour.
Il concerne également les projets dont l’application s’exécute dans le simulateur alors que Xcode Previews échoue, ainsi que les petites équipes qui maintiennent un environnement de développement accessible par VNC ou bureau distant.
Le premier piège consiste à considérer Preview comme une simple représentation graphique du Build. En réalité, le Build classique, l’exécution sur un appareil simulé et le processus de prévisualisation doivent être vérifiés séparément. La documentation Apple décrit le rôle de Previews dans Xcode et la manière dont une vue est rendue dans le Canvas ; elle ne permet pas de conclure qu’un Build réussi garantit une Preview fonctionnelle. Consultez la documentation Apple sur les prévisualisations SwiftUI dans Xcode avant de comparer les résultats.
| Résultat observé | Ce que cela prouve | Ce que cela ne prouve pas |
|---|---|---|
| Le projet se compile | Le compilateur et une partie des dépendances ont accepté le code | Que l’initialisation de Preview, le chargement des ressources et les liens d’exécution fonctionnent |
| L’application s’ouvre dans le simulateur | Le Scheme, le runtime choisi et le lancement simulé sont utilisables | Que Canvas peut créer ses données et isoler ses dépendances |
| La vue s’affiche dans Canvas | Le chemin de prévisualisation testé fonctionne dans cet état | Que l’interaction, le redémarrage de Xcode ou un autre Target seront stables |
| Le rapport contient une erreur de permission | Un accès précis est refusé dans le contexte diagnostiqué | Que l’accès complet au disque est nécessaire ou souhaitable partout |
Commencez donc par noter le fichier concerné, le Target, le Scheme actif, la destination choisie, l’heure de l’échec et la dernière modification connue. Dans Canvas, utilisez l’entrée de diagnostic prévue par Xcode pour exporter le rapport. Les notes de version d’Apple documentent l’apparition de l’outil de diagnostic Preview ; le guide Apple consacré aux rapports Previews Diagnostics constitue le point de référence pour son usage.
Le rapport doit devenir la pièce centrale de l’enquête. Une ligne de compilation, un crash pendant l’initialisation, un module non chargé ou un chemin inaccessible ne demandent pas la même correction. Un nouveau projet minimal utilisant une vue très simple fournit ensuite un test de séparation : si cette vue fonctionne, le Mac n’est probablement pas la première cause à traiter ; si elle échoue également, l’environnement mérite une vérification prioritaire.
Dans un projet à Target unique, vérifiez que le fichier contient bien une déclaration de prévisualisation valide et qu’elle correspond à l’API utilisée par la version de SwiftUI installée. Ne changez pas plusieurs éléments à la fois : l’objectif est de savoir quelle dépendance provoque le premier échec.
Remplacez temporairement la vue complexe par un composant qui reçoit uniquement des valeurs fixes. Retirez, dans cet ordre logique, les appels réseau, l’accès au disque, la base de données, l’authentification et les singletons de production. Réintroduisez ensuite les éléments un par un. Le premier ajout qui fait disparaître la Preview du Canvas est plus instructif qu’une longue série de suppressions de caches.
Une application principale qui démarre n’est pas une preuve suffisante. Preview peut créer la vue dans un contexte différent, avec des données absentes, un cycle de vie plus court ou une initialisation qui n’est jamais exécutée de la même façon au lancement classique. Le résultat à conserver est donc le message d’erreur, le composant minimal et la dépendance réintroduite au moment précis de la régression.
Point de vigilance : une prévisualisation destinée à l’interface ne devrait pas dépendre directement d’un compte de production, d’un service distant obligatoire ou d’un fichier local dont l’emplacement varie selon la machine. Ces dépendances rendent l’échec difficile à reproduire et compliquent la migration vers un environnement distant.
Les écrans alimentés par SwiftData, une API distante ou un état de connexion demandent une isolation plus stricte. Préparez un conteneur en mémoire pour la Preview, des objets d’exemple déterministes et un protocole ou une couche injectable pour remplacer le service réel. L’objectif n’est pas de masquer une erreur, mais de distinguer trois situations : l’objet ne peut pas être créé, la collection de données est vide ou la vue échoue après avoir reçu ses données.
Une Preview robuste doit pouvoir être lancée sans session utilisateur active, sans réseau et sans base de données de production. Utilisez des identifiants et des dates fixes dans les données d’exemple, afin qu’une actualisation successive ne produise pas un état différent. Si l’écran dépend d’un chargement asynchrone, prévoyez aussi un état explicite « chargement », « vide » et « erreur ». Vous pourrez alors tester le rendu sans attendre un serveur.
Ne transformez toutefois pas une observation de communauté en règle générale. Les discussions du forum Apple peuvent signaler un comportement lié à un projet ou à une version particulière, mais elles ne constituent pas une confirmation que tous les projets SwiftData sont affectés. La discussion Apple Developer Forums sur les diagnostics de Preview doit être utilisée comme piste de comparaison, non comme preuve universelle.
Pour les projets audio, vidéo ou de design, cette séparation est encore plus utile : les vignettes, fichiers sonores, polices et aperçus vidéo peuvent être remplacés par des ressources de test légères et présentes dans le bundle. Vous vérifiez ainsi le layout et les états d’interface sans rendre le Canvas dépendant d’un volume externe ou d’un catalogue multimédia privé.
Dès qu’un projet possède plusieurs Targets ou Swift Package, la cause peut se situer à la frontière entre compilation et exécution. Contrôlez le Target auquel appartient le fichier, le Scheme actif, la plateforme visée et le produit réellement associé au package. La documentation Apple sur la création d’un nouveau Target rappelle les éléments qui déterminent cette association.
Une erreur Runtime Linking Failure doit être lue depuis sa première ligne utile. Cherchez un symbole introuvable, un module absent, une ressource non copiée ou un chemin de bundle incorrect. Le message final peut seulement être la conséquence de l’échec initial. Vérifiez ensuite les phases de compilation du Target, les produits liés et les ressources copiées ; les informations Apple sur les Build Phases et la configuration des liens servent de référence pour cette vérification.
| Symptôme dans le diagnostic | Vérification ciblée | Action prudente |
|---|---|---|
| Module introuvable | Produit du package, Target et plateforme | Corriger l’association du produit, puis reconstruire la vue minimale |
| Symbole absent au chargement | Phase de liaison et dépendance réellement embarquée | Comparer le Target de l’application et celui utilisé par Preview |
| Ressource introuvable | Bundle, nom exact et phase de copie | Ajouter la ressource au bon Target, sans déplacer tout le catalogue |
| Package résolu mais Preview inutilisable | Différence entre résolution, compilation et chargement | Conserver Package.resolved, puis isoler le produit fautif |
| Canvas bloqué sans erreur de code claire | Session graphique, runtime et droits de chemin | Tester un projet minimal dans un dossier de travail ordinaire |
Évitez de supprimer systématiquement Package.resolved. Cette action peut modifier l’état des dépendances et faire disparaître temporairement un symptôme sans révéler la liaison incorrecte. Conservez une copie du fichier et du rapport avant toute modification. La résolution réussie d’un package ne signifie pas automatiquement que son produit est chargeable par le processus de Preview.
Un Mac distant ajoute une couche que l’utilisation locale masque souvent : Xcode peut être ouvert dans une session graphique non persistante, déconnectée ou différente de celle qui possède les fichiers. Vérifiez qu’un utilisateur est réellement connecté à l’interface graphique, que la session n’est pas seulement une connexion SSH et que Xcode peut afficher le Canvas dans cette session.
Inspectez ensuite la propriété et les droits du dossier du projet, de DerivedData, des données du simulateur et des répertoires temporaires utilisés par Xcode. Comparez un projet placé dans un dossier de travail ordinaire avec le même test dans un emplacement protégé ou synchronisé. Cette comparaison aide à distinguer un refus d’accès d’un défaut de code.
Ne considérez pas l’autorisation d’accès complet au disque comme une réparation universelle. Elle élargit fortement les droits et doit être évaluée selon le chemin réellement refusé, le compte utilisé et la politique de sécurité de l’équipe. Commencez par corriger la propriété ou le choix du dossier lorsque cela suffit, puis vérifiez le runtime de la plateforme : il doit être installé et capable de démarrer correctement dans la session graphique.
Pour préparer une machine destinée au développement continu, notre guide de configuration d’un Mac distant pour Xcode peut servir de grille de contrôle sur la session, les accès et le projet réel. La question n’est pas seulement de pouvoir ouvrir Xcode, mais de relancer Preview après une déconnexion, un redémarrage et une nouvelle ouverture du projet.
Utilisez les branches suivantes plutôt qu’une procédure identique pour chaque panne :
La suppression de DerivedData appartient donc à une branche précise, pas au début de chaque diagnostic. Elle peut reconstruire des artefacts, mais elle ne répare pas un code de Preview invalide, une ressource absente ou une session graphique mal établie.
Relevez d’abord le Target et le Scheme, puis générez le diagnostic. Vérifiez la macro de prévisualisation et testez la vue dans un projet minimal. Si l’erreur disparaît, réintroduisez les dépendances progressivement ; si elle demeure, comparez le runtime et les droits du dossier sur la machine utilisée.
Ces deux chemins peuvent diverger au moment de créer les données, de charger les modules ou d’initialiser les ressources. Un lancement réussi dans le simulateur ne valide donc pas le Canvas. La comparaison utile porte sur les journaux Preview, le Target de la vue et les dépendances créées au démarrage, pas seulement sur le fait que l’application s’ouvre.
Commencez par la première erreur de symbole ou de module, puis inspectez la liaison du Target et les produits du package. Contrôlez aussi les ressources copiées dans le bundle. Une résolution de package réussie et une compilation réussie peuvent coexister avec un chargement Preview défaillant ; le diagnostic doit guider la correction la plus locale possible.
Une session graphique active est indispensable pour évaluer ce comportement. Contrôlez l’utilisateur de la session, les chemins de projet et de DerivedData, les droits de lecture-écriture et le runtime simulé. Faites ensuite un essai avec une vue minimale et un dossier ordinaire. Si seul l’environnement distant échoue, migrez après avoir sauvegardé les journaux et défini un test de reprise.
La suppression ciblée peut être pertinente lorsque le rapport suggère des artefacts de compilation incohérents. Elle doit être précédée d’une sauvegarde et suivie d’un test reproductible. Si la cause se trouve dans SwiftData, un package, une permission ou une macro de Preview, vider DerivedData ne fait que retarder l’identification du problème.
Une réparation crédible comporte plusieurs contrôles distincts. Vérifiez d’abord une vue statique avec des valeurs fixes, puis une vue interactive, une vue alimentée par des données de test et une vue utilisant les dépendances réellement nécessaires au produit. Fermez et rouvrez ensuite Xcode pour vérifier que le résultat ne dépend pas d’un état conservé en mémoire.
Pour une équipe, conservez un relevé désensibilisé comprenant l’environnement Xcode et macOS, le runtime sélectionné, le Target, le chemin du projet, le symptôme initial, la première erreur du diagnostic et l’action corrective. Cette trace transforme une panne subjective en comparaison exploitable lors d’une mise à niveau ou d’une migration.
Pour les utilisateurs qui testent aussi l’interface sur appareil simulé à distance, notre guide d’accès distant au simulateur iOS aide à séparer les problèmes d’affichage de session des problèmes propres à Preview. Il est également préférable de préparer une procédure de migration et de reprise d’un environnement Xcode avant qu’une machine de développement ne devienne indispensable à une livraison.
Si un projet minimal fonctionne sur une machine locale mais reste instable dans l’environnement actuel, le problème n’est pas nécessairement SwiftUI. Une session graphique non persistante, des chemins appartenant à un autre utilisateur, un runtime incomplet ou une politique de permissions trop restrictive peuvent rendre les tests intermittents. Dans ce cas, évaluez un environnement où les droits, la session et le système peuvent être contrôlés indépendamment du poste principal.
Le poste actuel conserve toutefois des avantages : il convient mieux à un usage quotidien avec interfaces audio, périphériques physiques, capture vidéo locale ou besoin permanent d’accès direct au matériel. À l’inverse, un environnement distant est moins adapté si le projet exige une connexion physique particulière ou une charge lourde et stable pendant une longue période, car la qualité dépend aussi de la connexion et de la gestion de session.
Pour un indépendant, maintenir une machine dédiée uniquement à Xcode peut aussi immobiliser du budget, multiplier les tâches de mise à jour et laisser un poste inutilisé entre deux cycles de publication. La location d’un Mac auprès de VNCMac devient alors une option à tester lorsque le besoin principal est un environnement macOS accessible à distance, avec un vrai projet SwiftUI, un runtime simulé et une session graphique réinitialisable. Nous recommandons de valider d’abord le Canvas, le simulateur, la signature et la reprise après redémarrage avant d’en faire l’espace de travail principal.