SwiftUI-Debugging-Diagnose
Wann diese Diagnose-Skill verwenden
Verwenden Sie diese Skill, wenn:
- Grundlegende Fehlerbehebung fehlgeschlagen ist – Die Muster aus der
axiom-swiftui-debugging-Skill wurden angewendet, aber das Problem besteht weiterhin - Self._printChanges() zeigt unerwartete Muster – View aktualisiert, wenn es nicht sollte, oder aktualisiert nicht, wenn es sollte
- Intermittierende Probleme – Funktioniert manchmal, manchmal nicht („Heisenbug“)
- Komplexe Abhängigkeitsketten – Datenfluss muss durch mehrere Views/Modelle verfolgt werden
- Performance-Untersuchung – Views aktualisieren zu oft oder dauern zu lange
- Preview-Rätsel – Abstürze oder Fehler, die nicht sofort offensichtlich sind
VERBOTENE Aktionen
Unter Druck werden Sie versucht sein, Abkürzungen zu nehmen, die Probleme verstecken anstatt sie zu diagnostizieren. Tun Sie das NIEMALS:
❌ Raten mit zufälligen @State/@Observable-Änderungen
- „Lass mich mal @Observable hier hinzufügen und sehen, ob es funktioniert“
- „Vielleicht behebt es das Problem, wenn ich das in @StateObject ändere“
❌ Hinzufügen von .id(UUID()), um Updates zu erzwingen
- Erstellt bei jedem Rendern eine neue View-Identität
- Zerstört die Zustandserhaltung
- Überdeckt die Ursache
❌ Verwenden von ObservableObject, wenn @Observable funktionieren würde (iOS 17+)
- Fügt unnötige Komplexität hinzu
- Verpasst automatische Abhängigkeitsverfolgung
❌ Ignorieren von intermittierenden Problemen („funktioniert manchmal“)
- „Ich merge einfach und hoffe, dass es in Produktion nicht passiert“
- Intermittierend = systematischer Fehler, kein Zufall
❌ Ausliefern ohne Verständnis
- „Der Fix funktioniert, ich weiß nicht warum“
- Produktion ist zu teuer für Trial-and-Error
Obligatorische erste Schritte
Bevor Sie mit Diagnosemustern beginnen, richten Sie die Basisumgebung ein:
# 1. Instruments-Einrichtung überprüfen
xcodebuild -version # Muss Xcode 26+ für das SwiftUI-Instrument sein
# 2. Im Release-Modus für Profiling bauen
xcodebuild build -scheme YourScheme -configuration Release
# 3. Abgeleitete Daten löschen, wenn Preview-Probleme untersucht werden
rm -rf ~/Library/Developer/Xcode/DerivedData
Zeitaufwand: 5 Minuten Warum: Eine falsche Xcode-Version oder der Debug-Modus liefern irreführende Profiling-Daten
Diagnose-Entscheidungsbaum
SwiftUI-View-Problem nach grundlegender Fehlerbehebung?
│
├─ View aktualisiert nicht?
│ ├─ Grundlegende Prüfung: Self._printChanges() temporär hinzufügen
│ │ ├─ Zeigt "@self changed" → View-Wert geändert
│ │ │ └─ Muster D1: Analysieren, was die View-Neuerstellung verursacht hat
│ │ ├─ Zeigt spezifische Zustandseigenschaft → Dieser Zustand hat das Update ausgelöst
│ │ │ └─ Prüfen: Soll dieser Zustand das Update auslösen?
│ │ └─ Nichts protokolliert → Body wird überhaupt nicht aufgerufen
│ │ └─ Muster D3: Untersuchung der View-Identität
│ └─ Fortgeschritten: SwiftUI-Instrument verwenden
│ └─ Muster D2: Untersuchung mit dem SwiftUI-Instrument
│
├─ View aktualisiert zu oft?
│ ├─ Muster D1: Self._printChanges()-Analyse
│ │ └─ Unnötige Zustandsabhängigkeiten identifizieren
│ └─ Muster D2: SwiftUI-Instrument → Ursache-Wirkungs-Graph
│ └─ Datenfluss verfolgen, breite Abhängigkeiten finden
│
├─ Intermittierende Probleme (funktioniert manchmal)?
│ ├─ Muster D3: Untersuchung der View-Identität
│ │ └─ Prüfen: Ändert sich die Identität unerwartet?
│ ├─ Muster D4: Prüfung der Umgebungsabhängigkeiten
│ │ └─ Prüfen: Ändern sich Umgebungswerte häufig?
│ └─ 30+ Mal in der Vorschau reproduzieren
│ └─ Wenn nicht reproduzierbar: Wahrscheinlich Timing/Race-Condition
│
└─ Preview-Abstürze (nach grundlegenden Fixes)?
├─ Muster D5: Preview-Diagnose (Xcode 26)
│ └─ Diagnose-Button, Absturzprotokolle prüfen
└─ Wenn weiterhin fehlschlägt: Muster D2 (Preview-Build profilieren)
Diagnosemuster
Muster D1: Self._printChanges()-Analyse
Zeitaufwand: 5 Minuten
Symptom: Genau verstehen, warum der View-Body ausgeführt wird
Wann verwenden:
- View aktualisiert häufiger als erwartet
- View aktualisiert nicht, wenn es sollte
- Abhängigkeiten nach Refactoring überprüfen
Technik:
struct MyView: View {
@State private var count = 0
@Environment(AppModel.self) private var model
var body: some View {
let _ = Self._printChanges() // Temporär hinzufügen
VStack {
Text("Count: \(count)")
Text("Model value: \(model.value)")
}
}
}
Ausgabe-Interpretation:
# Szenario 1: View-Parameter geändert
MyView: @self changed
→ Übergeordnete Ansicht hat neue MyView-Instanz übergeben
→ Übergeordneten Code prüfen – was hat die Neuerstellung ausgelöst?
# Szenario 2: Zustandseigenschaft geändert
MyView: count changed
→ Lokaler @State hat Update ausgelöst
→ Erwartet, wenn Sie count geändert haben
# Szenario 3: Umgebungseigenschaft geändert
MyView: @self changed # Umgebung ist Teil von @self
→ Umgebungswert geändert (Farbschema, Gebietsschema, benutzerdefinierter Wert)
→ Muster D4: Umgebungsabhängigkeiten prüfen
# Szenario 4: Nichts protokolliert
→ Body wird nicht aufgerufen
→ Muster D3: Untersuchung der View-Identität
Häufige Entdeckungen:
-
"@self changed" wenn nicht erwartet
- Übergeordnete Ansicht erstellt View unnötig neu
- Zustandsverwaltung der übergeordneten Ansicht prüfen
-
Eigenschaft zeigt sich als geändert, aber Sie haben sie nicht geändert
- Indirekte Abhängigkeit (Lesen aus einem Objekt, das sich geändert hat)
- Muster D2: Instruments verwenden, um dies zu verfolgen
-
Mehrere Eigenschaften ändern sich gleichzeitig
- Breite Abhängigkeit (z. B. gesamtes Array lesen, obwohl nur ein Element benötigt wird)
- Behebung: Spezifische Abhängigkeit extrahieren
Überprüfung:
Self._printChanges()-Aufruf vor dem Commit entfernen- Niemals mit diesem Code in Produktion gehen
Querverweis: Bei komplexen Fällen Muster D2 (SwiftUI-Instrument) verwenden
Muster D2: Untersuchung mit dem SwiftUI-Instrument
Zeitaufwand: 25 Minuten
Symptom: Komplexe Update-Muster, die Self._printChanges() nicht vollständig erklären kann
Wann verwenden:
- Mehrere Views aktualisieren, obwohl nur eine es sollte
- Datenfluss durch die App muss verfolgt werden
- Views aktualisieren, aber es ist unbekannt, welche Daten dies ausgelöst haben
- Lange View-Body-Updates (Performance-Problem)
Voraussetzungen:
- Xcode 26+ installiert
- Gerät auf iOS 26+ / macOS Tahoe+ aktualisiert
- Im Release-Modus bauen
Schritte:
1. Instruments starten (5 Min)
# Release bauen
xcodebuild build -scheme YourScheme -configuration Release
# Instruments starten
# Command-I in Xcode drücken
# „SwiftUI“-Vorlage wählen
2. Trace aufzeichnen (3 Min)
- Auf Aufnahme-Button klicken
- Aktion ausführen, die unerwartete Updates auslöst
- Aufnahme stoppen (10-30 Sekunden Interaktion reichen)
3. Lange View-Body-Updates analysieren (5 Min)
- Nach Langen View-Body-Updates-Spur suchen
- Orange/rote Balken vorhanden? Das sind teure Views
- Auf langes Update klicken → Detailbereich zeigt View-Namen
- Rechtsklick → „Inspection Range setzen und zoomen“
- Zur Time Profiler-Spur wechseln
- View im Aufrufstapel finden
- Teure Operation identifizieren (Formatter-Erstellung, Berechnung usw.)
Behebung: Teure Operation in die Model-Ebene verschieben, Ergebnis zwischenspeichern
4. Unnötige Updates analysieren (7 Min)
- Zeitbereich der Benutzeraktion hervorheben (z. B. Tippen auf Favoriten-Button)
- Hierarchie im Detailbereich erweitern
- Updates zählen – mehr als erwartet?
- Über View schweben → Pfeil klicken → „Ursache-Wirkungs-Graph anzeigen“
5. Ursache-Wirkungs-Graph interpretieren (5 Min)
Graph-Knoten:
[Blauer Knoten] = Ihr Code (Geste, Zustandsänderung, View-Body)
[System-Knoten] = SwiftUI-/Systemarbeit
[Pfeil mit "update"] = Hat dieses Update verursacht
[Pfeil mit "creation"] = Hat View erscheinen lassen
Häufige Muster:
# Muster A: Einzelne View aktualisiert (GUT)
[Geste] → [Zustandsänderung in ViewModelA] → [ViewA Body]
# Muster B: Alle Views aktualisieren (SCHLECHT – breite Abhängigkeit)
[Geste] → [Array-Änderung] → [Alle Listenelement-Views aktualisieren]
└─ Behebung: Granulare View-Modelle verwenden, eines pro Element
# Muster C: Kaskade durch Umgebung (PRÜFEN)
[Zustandsänderung] → [Umgebung schreiben] → [Viele View-Bodies prüfen]
└─ Wenn sich der Umgebungswert häufig ändert → Muster D4-Behebung
Auf Knoten klicken:
- Zustandsänderungsknoten → Backtrace sehen, wo der Wert gesetzt wurde
- View-Body-Knoten → Sehen, welche Eigenschaften gelesen wurden (Abhängigkeiten)
Überprüfung:
- Nach der Behebung neuen Trace aufzeichnen
- Update-Zahlen vorher/nachher vergleichen
- Überprüfen, ob rote/orange Balken reduziert oder beseitigt wurden
Querverweis: Skill axiom-swiftui-performance für detaillierte Instruments-Workflows
Muster D3: Untersuchung der View-Identität
Zeitaufwand: 15 Minuten
Symptom: @State-Werte werden unerwartet zurückgesetzt, oder Views animieren nicht
Wann verwenden:
- Zähler wird auf 0 zurückgesetzt, obwohl er es nicht sollte
- Animationen funktionieren nicht (View erscheint statt zu animieren)
- ForEach-Elemente springen umher
- Textfeld verliert Fokus
Ursache: View-Identität hat sich unerwartet geändert
Untersuchungsschritte:
1. Auf bedingte Platzierung prüfen (5 Min)
// ❌ PROBLEM: Identität ändert sich mit Bedingung
if showDetails {
CounterView() // Erhält jedes Mal eine neue Identität, wenn showDetails umgeschaltet wird
}
// ✅ BEHEBUNG: .opacity() verwenden
CounterView()
.opacity(showDetails ? 1 : 0) // Immer gleiche Identität
Finden: Codebasis nach Views in if/else durchsuchen, die Zustand halten
2. .id()-Modifikatoren prüfen (5 Min)
// ❌ PROBLEM: .id() ändert sich, wenn sich Daten ändern
DetailView()
.id(item.id + "-\(isEditing)") // ID ändert sich mit isEditing
// ✅ BEHEBUNG: Stabile ID
DetailView()
.id(item.id) // Stabile ID
Finden: Codebasis nach .id( durchsuchen – prüfen, ob sich ID-Werte ändern
3. ForEach-Identifikatoren prüfen (5 Min)
// ❌ FALSCH: Indexbasierte ID
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
Text(item.name)
}
// ❌ FALSCH: Nicht eindeutige ID
ForEach(items, id: \.category) { item in // Mehrere Elemente pro Kategorie
Text(item.name)
}
// ✅ RICHTIG: Eindeutige, stabile ID
ForEach(items, id: \.id) { item in
Text(item.name)
}
Finden: Nach ForEach suchen – eindeutige, stabile IDs überprüfen
Behebungsmuster:
| Problem | Behebung |
|---|---|
| View in Bedingung | Stattdessen .opacity() verwenden |
| .id() ändert sich zu oft | Stabiles Identifier verwenden |
| ForEach springt | Eindeutige, stabile IDs (UUID oder Server-ID) verwenden |
| Zustand wird bei Navigation zurückgesetzt | NavigationStack-Pfadverwaltung prüfen |
Überprüfung:
- Self._printChanges() hinzufügen – sollte NICHT wiederholt "@self changed" anzeigen
- Animationen sollten jetzt reibungslos funktionieren
- @State-Werte sollten bestehen bleiben
Muster D4: Prüfung der Umgebungsabhängigkeiten
Zeitaufwand: 10 Minuten
Symptom: Viele Views aktualisieren, wenn sich nicht verwandte Daten ändern
Wann verwenden:
- Ursache-Wirkungs-Graph zeigt „Umgebungs“-Knoten, der viele Updates auslöst
- Langsames Scrollen oder Animationsperformance
- Unerwartete kaskadierende Updates
Ursache: Häufig wechselnder Wert in der Umgebung ODER zu viele Views lesen aus der Umgebung
Untersuchungsschritte:
1. Umgebungsschreibvorgänge finden (3 Min)
# Nach Umgebungs-Modifikatoren im aktuellen Projekt suchen
bash
grep -r "\.environment(" --include="*.swift" .
Achten auf:
// ❌ SCHLECHT: Häufig wechselnde Werte
.environment(\.scrollOffset, scrollOffset) // Aktualisiert 60+ Mal/Sekunde
.environment(model) // Wenn model sich häufig aktualisiert
// ✅ GUT: Stabile Werte
.environment(\.colorScheme, .dark)
.environment(appModel) // Wenn appModel sich selten ändert
2. Prüfen, was in der Umgebung ist (3 Min)
Mit Muster D2 (Instruments) den Ursache-Wirkungs-Graph prüfen:
- Auf „Umgebungs“-Knoten klicken
- Sehen, welche Eigenschaften sich geändert haben
- Zählen, wie viele Views auf Updates geprüft haben
Fragen:
- Ändert sich dieser Wert bei jedem Scroll-/Animationsframe?
- Brauchen alle diese Views diesen Wert tatsächlich?
3. Behebung anwenden (4 Min)
Behebung A: Aus Umgebung entfernen (wenn häufig wechselnd):
// ❌ Vorher: Umgebung
.environment(\.scrollOffset, scrollOffset)
// ✅ Nachher: Direkter Parameter
ChildView(scrollOffset: scrollOffset)
Behebung B: @Observable-Modell verwenden (wenn von vielen Views benötigt):
// Statt eines primitiven Werts in der Umgebung:
@Observable class ScrollViewModel {
var offset: CGFloat = 0
}
// Views hängen von spezifischen Eigenschaften ab:
@Environment(ScrollViewModel.self) private var viewModel
var body: some View {
Text("\(viewModel.offset)") // Aktualisiert nur, wenn sich offset ändert
}
Überprüfung:
- Neuen Trace in Instruments aufzeichnen
- Ursache-Wirkungs-Graph prüfen – weniger Views sollten aktualisieren
- Performance sollte sich verbessern (flüssigeres Scrollen/Animationen)
Muster D5: Preview-Diagnose (Xcode 26)
Zeitaufwand: 10 Minuten
Symptom: Preview lädt nicht oder stürzt mit unklarem Fehler ab
Wann verwenden:
- Preview schlägt nach grundlegenden Fixes fehl (swiftui-debugging-Skill)
- Fehlermeldung unklar oder allgemein
- Preview hat vorher funktioniert, hört plötzlich auf
Untersuchungsschritte:
1. Preview-Diagnose-Button verwenden (2 Min)
Ort: Menü „Editor“ → „Canvas“ → „Diagnose“
Was es anzeigt:
- Detaillierte Fehlermeldungen
- Fehlende Abhängigkeiten
- Probleme mit der Zustandsinitialisierung
- Previewspezifische Probleme
2. Absturzprotokolle prüfen (3 Min)
# Absturzprotokollverzeichnis öffnen
open ~/Library/Logs/DiagnosticReports/
# Nach aktuellen .crash-Dateien mit „Preview" suchen
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5
Worauf achten:
- Fatale Fehler (Array außerhalb der Grenzen, Force-Unwrap von nil)
- Fehlende Modulimporte
- Framework-Initialisierungsfehler
3. Problem isolieren (5 Min)
Minimale Preview erstellen:
// Mit leerer Preview beginnen
#Preview {
Text("Test")
}
// Wenn das funktioniert, schrittweise hinzufügen:
#Preview {
MyView() // Ihre tatsächliche View, aber mit Mock-Daten
.environment(MockModel()) // Alle Abhängigkeiten bereitstellen
}
// Finden, welche Abhängigkeit den Absturz verursacht
Häufige Probleme:
| Fehler | Ursache | Behebung |
|---|---|---|
| „Cannot find in scope" | Fehlende Abhängigkeit | Zur Preview hinzufügen (siehe Beispiel unten) |
| "Fatal error: Unexpectedly found nil" | Optional-Unwrap fehlgeschlagen | Nicht-nil-Wert in der Preview bereitstellen |
| "No such module" | Import fehlt | Import-Anweisung hinzufügen |
| Stiller Absturz (kein Fehler) | Zustandsinit mit ungültigem Wert | Sichere Standardwerte verwenden |
Behebungsmuster:
// Fehlendes @Environment
#Preview {
ContentView()
.environment(AppModel()) // Abhängigkeit bereitstellen
}
// Fehlendes @EnvironmentObject (vor iOS 17)
#Preview {
ContentView()
.environmentObject(AppModel())
}
// Fehlender ModelContainer (SwiftData)
#Preview {
let config = ModelConfiguration(isStoredInMemoryOnly: true)
let container = try! ModelContainer(for: Item.self, configurations: config)
ContentView()
.modelContainer(container)
}
Überprüfung:
- Preview sollte jetzt laden
- Während der interaktiven Entwicklung Preview offen lassen
- Bei erneuten Problemen: Schritt 1-2 wiederholen
Nächste Schritte
Wenn alle Diagnosemuster das Problem nicht lösen:
axiom-swiftui-performanceprüfen – Detaillierte Instruments-Workflows für Performance- Probleme in ein minimales reproduzierbares Beispiel isolieren – In neuem Xcode-Projekt reproduzieren
- Swift Evolution Forum durchsuchen – Nach bekannten SwiftUI-Fehlern suchen
- In Schichten debuggen:
- Ist es ein Datenproblem? → Datenebene prüfen (Modelle, ViewModels)
- Ist es ein Layoutproblem? → Layout-Diagnose (Zeit zum Parsen der View-Hierarchie)
- Ist es ein Animationsproblem? → Animations-Diagnose (Dauer)
Denken Sie daran: SwiftUI ist deklarativ. Fragen Sie nicht „Wie mache ich X?", sondern „Was soll der Endzustand sein?" und lassen Sie SwiftUI den Weg finden.