SwiftUI Preview funktioniert nicht: 2026 Remote-Mac-Leitfaden

Seit Xcode 14 dokumentiert Apple einen eigenen Diagnoseweg für Preview-Probleme über den Canvas, statt Entwickler ausschließlich auf allgemeine Build-Logs zu verweisen (Xcode-14-Release-Notes mit dem Preview-Diagnosezugang). Wenn die SwiftUI Preview nicht funktioniert, löschen Sie deshalb nicht sofort den gesamten Cache und installieren Sie Xcode nicht vorschnell neu: Erstellen Sie zuerst einen Previews Diagnostics Report und trennen Sie anschließend Code, Abhängigkeiten, Simulator-Laufzeit und Systemumgebung. Bei einem Remote-Mac gehören zusätzlich die grafische Sitzung sowie die Eigentümer von Projekt- und DerivedData-Verzeichnissen zur ersten Diagnose.

Diese Anleitung richtet sich an unabhängige Entwickler, die SwiftUI zur Oberflächenentwicklung verwenden und deren Canvas nicht startet oder nicht aktualisiert. Sie ist ebenso für iOS- und macOS-Entwickler gedacht, bei denen der Simulator die App ausführt, aber Xcode Previews fehlschlagen, sowie für kleine Teams, die eine dauerhaft erreichbare Entwicklungsumgebung über VNC oder einen anderen Remote-Desktop betreiben.

Der Diagnosebericht entscheidet über den nächsten Schritt

Eine Preview ist nicht einfach eine verkleinerte Ansicht des zuletzt erfolgreichen App-Builds. Xcode muss die betreffende View, ihre Preview-Daten, deren Abhängigkeiten und die passende Ausführungsumgebung separat laden. Apple beschreibt die Arbeitsweise von Previews und die Canvas-Steuerung in der offiziellen Dokumentation zu SwiftUI Previews in Xcode. Ein erfolgreicher Build oder ein laufender Simulator beweist daher nicht, dass dieselbe View in der Preview-Umgebung funktioniert.

Beginnen Sie mit einer unveränderten Fehleraufnahme:

1. Notieren Sie Target, aktives Scheme, ausgewählte Plattform und Simulator beziehungsweise Gerät.
2. Schreiben Sie die genaue Fehlermeldung, den Zeitpunkt und die zuletzt geänderte Datei auf.
3. Speichern Sie die betroffene View als minimales, anonymisiertes Reproduktionsbeispiel.
4. Öffnen Sie im Canvas den Diagnosebereich und exportieren Sie den Previews-Diagnosebericht.
5. Ordnen Sie den ersten aussagekräftigen Fehler einer Kategorie zu: Kompilierung, Initialisierung, Laufzeit, Linker, Ressource, Berechtigung oder Simulator.

Verwenden Sie in einem Bericht keine echten Kundendaten, privaten API-Schlüssel, Benutzernamen oder internen Pfade. Für eine spätere Meldung an Apple beschreibt die offizielle Übersicht zu Swift-Logs und Feedback-Profilen, welche Protokolle und Diagnoseinformationen sinnvoll sind.

Cannot preview in this file: erst Makro und Datei prüfen

Die Meldung „Cannot preview in this file“ bedeutet nicht automatisch, dass der Mac oder Xcode beschädigt ist. Prüfen Sie zunächst, ob die Datei tatsächlich eine gültige Preview-Deklaration enthält und ob sie dem erwarteten SwiftUI-Target zugeordnet ist. Verwenden Sie das in der jeweiligen Xcode-Version unterstützte Preview-Makro und kontrollieren Sie, ob die Datei versehentlich nur in einem Test-, Bibliotheks- oder nicht ausgewählten Target liegt.

Danach entfernen Sie aus der Preview-Erstellung alles, was nicht für die Darstellung der View notwendig ist. Ein problematischer Initialisierer kann bereits beim Aufbau der Vorschau Netzwerkzugriffe, Datenbankverbindungen, Dateizugriffe oder eine Produktionskonfiguration auslösen. Die Hauptanwendung kann dabei weiterhin starten, weil sie eine andere Startreihenfolge und einen anderen Zustand verwendet.

Reduzieren Sie die View deshalb auf eine statische Darstellung:

#Preview {
    ProductCard(
        title: "Beispieldatensatz",
        imageName: "sample-image"
    )
}

Die Namen dienen hier nur als Platzhalter. Ersetzen Sie keine echten Modul-, Projekt- oder Kundennamen in veröffentlichten Diagnosebeispielen. Wenn diese vereinfachte View funktioniert, fügen Sie Environment-Werte, Observable-Zustände und Testdaten einzeln wieder hinzu. Der erste Wiederholungsfehler ist wertvoller als ein pauschales „Preview funktioniert nicht“.

Pakete, Targets und Ressourcen nicht mit Cache-Löschung verwechseln

In Mehr-Target-Projekten oder bei Swift Package Manager entstehen viele Fehler an der Grenze zwischen erfolgreicher Auflösung, erfolgreicher Kompilierung und erfolgreichem Preview-Start. Eine App kann ein Paket kompilieren, während das Preview-Target das benötigte Produkt nicht verlinkt oder eine Ressource nicht in seinem eigenen Bundle findet.

Prüfen Sie in dieser Reihenfolge:

1. Gehört die Preview-Datei zum Target, das im aktiven Scheme tatsächlich verwendet wird?
2. Ist das benötigte Package-Produkt an dieses Target gebunden?
3. Sind die unterstützte Plattform und die Architektur für das Preview-Ziel kompatibel?
4. Ist die Ressource im korrekten Target Membership enthalten?
5. Enthält der Diagnosebericht einen ersten Linker-, Symbol- oder Ladefehler?

Bei „Runtime Linking Failure“ sollten Sie genau diesen ersten Link- oder Ladefehler untersuchen. Spätere Meldungen sind häufig nur Folgefehler. Die Apple-Dokumentation zur Konfiguration eines neuen Targets erklärt die Target-Grenzen; für konkrete Linker- und Produktzuordnungen ist die Übersicht zu Build Phases und Target-Verknüpfungen die bessere Referenz.

Löschen Sie Package.resolved nicht als Routine. Dadurch wird die aufgelöste Paketversion verändert und ein reproduzierbarer Zustand kann verloren gehen. Sichern Sie die Datei zuerst und ändern Sie sie nur, wenn die Diagnose tatsächlich auf eine fehlerhafte Auflösung oder eine bewusst notwendige Aktualisierung deutet.

Löscht das Entfernen von DerivedData die SwiftUI Preview?

Das Löschen von DerivedData kann helfen, wenn abgeleitete Build-Artefakte oder ein inkonsistenter Zwischenzustand beschädigt sind. Es repariert jedoch keinen fehlenden Preview-Makro-Kontext, keine falsche Target-Mitgliedschaft, keine nicht verfügbare Simulator-Laufzeit und keine fehlerhafte Dateninitialisierung. Die richtige Antwort lautet daher: nur als begrenzter Test, nicht als erste Universalmaßnahme.

Sichern Sie vor einer Bereinigung zunächst den Diagnosebericht und notieren Sie den aktuell verwendeten Projektzustand. Beenden Sie Xcode kontrolliert, entfernen Sie ausschließlich den betroffenen abgeleiteten Projektordner und öffnen Sie das Projekt anschließend erneut. Verwenden Sie keinen rekursiven Löschbefehl mit einer unklaren Variable oder einem allgemeinen Entwicklerverzeichnis. Ein falscher Pfad kann nicht nur Cache-Dateien, sondern Quelltext, lokale Daten oder andere Arbeitsbereiche betreffen.

Bewerten Sie danach, ob sich genau derselbe Fehler reproduzieren lässt. Wenn ja, kehren Sie zur Diagnosekategorie zurück, anstatt die Bereinigung mehrfach zu wiederholen.

Entscheidungslogik für Entwickler und Umgebungsverantwortliche

Die folgende Verzweigung verhindert, dass alle Fehler mit derselben Maßnahme behandelt werden:

• Wenn ein minimales neues SwiftUI-Projekt im selben Benutzerkonto funktioniert, wählen Sie eine projektspezifische Reparatur: Preview-Code, Dateninitialisierung, Target, Paketprodukt oder Ressource prüfen. Andernfalls untersuchen Sie die Mac-Umgebung.
• Wenn die statische Preview funktioniert, aber die interaktive Vorschau nicht, wählen Sie eine Zustands- und Lebenszyklusdiagnose. Andernfalls beginnen Sie bei Kompilierung, Initialisierung oder Linker.
• Wenn der Diagnosebericht einen konkreten fehlenden Symbol- oder Ladefehler nennt, wählen Sie Build Phases, Package-Produkt und Bundle-Zuordnung. Andernfalls prüfen Sie Sitzung, Runtime und Pfade.
• Wenn der Simulator die App startet, aber Canvas und minimales Projekt beide scheitern, wählen Sie die getrennte Preview- und Remote-Umgebungsprüfung statt einer Änderung am Anwendungscode.
• Wenn ein Neustart von Xcode den Fehler nur einmalig beseitigt, wählen Sie eine Stabilitätsprüfung der Sitzung, temporären Verzeichnisse und Runtime. Andernfalls gilt die Ursache nicht als behoben.

Für einen Standortwechsel können Sie auch die regional passende Remote-Mac-Verfügbarkeit in den USA prüfen. Die Region ersetzt keine Diagnose, kann aber relevant sein, wenn Sitzungsstabilität, Zugriffsweg oder die organisatorische Trennung von Entwicklungsarbeitsplätzen eine Rolle spielen.