SwiftUI デバッグ診断
この診断スキルを使用すべき時
以下の場合に使用します:
- 基本的なトラブルシューティングが失敗した —
axiom-swiftui-debuggingスキルのパターンを適用したが問題が続く - Self._printChanges() が予期しないパターンを示す — ビューが更新されるべきでない時に更新される、または更新されるべき時に更新されない
- 断続的な問題 — 動作したりしなかったりする(「ハイゼンバグ」)
- 複雑な依存関係チェーン — 複数のビュー/モデルを通じたデータフローを追跡する必要がある
- パフォーマンス調査 — ビューが頻繁に、または長時間かけて更新される
- プレビューの謎 — すぐには明らかでないクラッシュや障害
禁止行為
プレッシャーがかかると、問題を診断する代わりに隠すショートカットに誘惑されるでしょう。絶対にこれらを行わないでください:
❌ 無作為な @State/@Observable の変更による推測
- 「ここで @Observable を追加して、動くか試してみましょう」
- 「これを @StateObject に変えれば直るかもしれない」
❌ 強制更新のための .id(UUID()) の追加
- レンダリングのたびに新しいビュー識別子を作成
- 状態の保存を破壊
- 根本原因を隠蔽
❌ iOS 17+ で @Observable で十分な場合の ObservableObject の使用
- 不要な複雑さを追加
- 自動依存関係トラッキングを逃す
❌ 断続的な問題の無視(「動作したりしなかったりする」)
- 「とりあえずマージして、本番で起きないことを祈ろう」
- 断続的 = ランダムではなく、体系的なバグ
❌ 理解せずに出荷する
- 「修正は動いている、理由はわからない」
- 本番環境は試行錯誤には高すぎる
必須の最初のステップ
診断パターンに入る前に、ベースライン環境を確立します:
# 1. Instruments のセットアップを確認
xcodebuild -version # SwiftUI Instrument には Xcode 26+ が必要
# 2. プロファイリング用に Release モードでビルド
xcodebuild build -scheme YourScheme -configuration Release
# 3. プレビューの問題を調査する場合、派生データをクリア
rm -rf ~/Library/Developer/Xcode/DerivedData
所要時間: 5分 理由: 間違った Xcode バージョンや Debug モードは誤解を招くプロファイリングデータを生成します
診断決定木
基本的なトラブルシューティング後の SwiftUI ビューの問題?
│
├─ ビューが更新されない?
│ ├─ 基本チェック: 一時的に Self._printChanges() を追加
│ │ ├─ "@self changed" と表示 → ビューの値が変更された
│ │ │ └─ パターン D1: ビューの再作成を引き起こした原因を分析
│ │ ├─ 特定の状態プロパティが表示 → その状態が更新をトリガー
│ │ │ └─ 確認: その状態が更新をトリガーすべきか?
│ │ └─ 何もログに出力されない → body が呼び出されていない
│ │ └─ パターン D3: ビュー同一性調査
│ └─ 高度: SwiftUI Instrument を使用
│ └─ パターン D2: SwiftUI Instrument 調査
│
├─ ビューが頻繁に更新される?
│ ├─ パターン D1: Self._printChanges() 分析
│ │ └─ 不要な状態依存関係を特定
│ └─ パターン D2: SwiftUI Instrument → 原因と影響グラフ
│ └─ データフローを追跡し、広範な依存関係を見つける
│
├─ 断続的な問題(動作したりしなかったりする)?
│ ├─ パターン D3: ビュー同一性調査
│ │ └─ 確認: 同一性が予期せず変化するか?
│ ├─ パターン D4: 環境依存関係チェック
│ │ └─ 確認: 環境の値が頻繁に変化するか?
│ └─ プレビューで30回以上再現
│ └─ 再現できない場合: タイミング/競合状態の可能性
│
└─ プレビュークラッシュ(基本的な修正後)?
├─ パターン D5: プレビュー診断(Xcode 26)
│ └─ 診断ボタン、クラッシュログを確認
└─ それでも失敗する場合: パターン D2(プレビュービルドをプロファイル)
診断パターン
パターン D1: Self._printChanges() 分析
所要時間: 5分
症状: ビューの body が正確にどのような理由で実行されるかを理解する必要がある
使用すべき時:
- ビューが予想より頻繁に更新される
- ビューが更新されるべき時に更新されない
- リファクタリング後の依存関係の確認
手法:
struct MyView: View {
@State private var count = 0
@Environment(AppModel.self) private var model
var body: some View {
let _ = Self._printChanges() // 一時的に追加
VStack {
Text("Count: \(count)")
Text("Model value: \(model.value)")
}
}
}
出力の解釈:
# シナリオ 1: ビューパラメータが変更された
MyView: @self changed
→ 親が新しい MyView インスタンスを渡した
→ 親のコードを確認 - 何が再作成をトリガーしたか?
# シナリオ 2: 状態プロパティが変更された
MyView: count changed
→ ローカルの @State が更新をトリガー
→ count を変更した場合、予想通り
# シナリオ 3: 環境プロパティが変更された
MyView: @self changed # 環境は @self の一部
→ 環境の値が変更された(カラースキーム、ロケール、カスタム値)
→ パターン D4: 環境依存関係を確認
# シナリオ 4: 何もログに出力されない
→ body が呼び出されていない
→ パターン D3: ビュー同一性調査
よくある発見:
-
予期しない時に "@self changed" が表示される
- 親が不必要にビューを再作成している
- 親の状態管理を確認
-
変更していないプロパティが変更されたと表示される
- 間接的な依存関係(変更されたオブジェクトから読み取っている)
- パターン D2: Instruments を使用して追跡
-
複数のプロパティが一緒に変更される
- 広範な依存関係(例:1つだけ必要なのに配列全体を読み取っている)
- 修正:特定の依存関係を抽出
確認:
- コミット前に
Self._printChanges()呼び出しを削除 - このコードを本番環境に出荷しないでください
相互参照: 複雑なケースでは、パターン D2(SwiftUI Instrument)を使用
パターン D2: SwiftUI Instrument 調査
所要時間: 25分
症状: Self._printChanges() だけでは完全に説明できない複雑な更新パターン
使用すべき時:
- 複数のビューが、1つだけ更新されるべき時に更新される
- アプリを通じたデータフローを追跡する必要がある
- ビューが更新されているが、どのデータがトリガーしたかわからない
- ビュー body の更新が長い(パフォーマンス問題)
前提条件:
- Xcode 26+ がインストールされている
- デバイスが iOS 26+ / macOS Tahoe+ にアップデートされている
- Release モードでビルド
手順:
1. Instruments を起動(5分)
# Release ビルド
xcodebuild build -scheme YourScheme -configuration Release
# Instruments を起動
# Xcode で Command-I を押す
# 「SwiftUI」テンプレートを選択
2. トレースを記録(3分)
- Record ボタンをクリック
- 予期しない更新をトリガーするアクションを実行
- 記録を停止(10〜30秒のインタラクションで十分)
3. 長いビュー body の更新を分析(5分)
- Long View Body Updates レーンを確認
- オレンジまたは赤いバーがあるか? それらは高コストなビュー
- 長い更新をクリック → 詳細ペインにビュー名が表示
- 右クリック → 「Inspection Range and Zoom を設定」
- Time Profiler トラックに切り替え
- コールスタックでビューを見つける
- 高コストな操作(フォーマッタ作成、計算など)を特定
修正: 高コストな操作をモデル層に移動し、結果をキャッシュ
4. 不要な更新を分析(7分)
- ユーザーアクションの時間範囲をハイライト(例:お気に入りボタンをタップ)
- 詳細ペインで階層を展開
- 更新回数をカウント — 予想より多いか?
- ビューにホバー → 矢印をクリック → 「原因と影響グラフを表示」
5. 原因と影響グラフを解釈(5分)
グラフのノード:
[青いノード] = あなたのコード(ジェスチャー、状態変更、ビュー body)
[システムノード] = SwiftUI/システムのワーク
[「update」とラベル付けされた矢印] = この更新を引き起こした
[「creation」とラベル付けされた矢印] = ビューの表示を引き起こした
一般的なパターン:
# パターン A: 単一のビューのみ更新(GOOD)
[Gesture] → [State Change in ViewModelA] → [ViewA body]
# パターン B: すべてのビューが更新(BAD - 広範な依存関係)
[Gesture] → [Array change] → [All list item views update]
└─ 修正: アイテムごとに細かいビューモデルを使用
# パターン C: 環境を通じたカスケード(CHECK)
[State Change] → [Environment write] → [Many view bodies check]
└─ 環境の値が頻繁に変わる場合 → パターン D4 で修正
ノードをクリック:
- 状態変更ノード → 値が設定された場所のバックトレースを表示
- ビュー body ノード → 読み取ったプロパティ(依存関係)を表示
確認:
- 修正後に新しいトレースを記録
- 修正前後の更新回数を比較
- 赤/オレンジのバーが減少または排除されたことを確認
相互参照: 詳細な Instruments ワークフローについては axiom-swiftui-performance スキルを参照
パターン D3: ビュー同一性調査
所要時間: 15分
症状: @State の値が予期せずリセットされる、またはビューがアニメーションしない
使用すべき時:
- カウンターがリセットされるべきでない時に0にリセットされる
- アニメーションが機能しない(ビューがアニメーションではなくポップ表示される)
- ForEach のアイテムが飛び回る
- テキストフィールドのフォーカスが外れる
根本原因: ビューの同一性が予期せず変更された
調査手順:
1. 条件付き配置を確認(5分)
// ❌ 問題: 条件によって同一性が変わる
if showDetails {
CounterView() // showDetails がトグルされるたびに新しい同一性を得る
}
// ✅ 修正: .opacity() を使用
CounterView()
.opacity(showDetails ? 1 : 0) // 常に同じ同一性
検索: 状態を保持する if/else 内のビューをコードベースから探す
2. .id() モディファイアを確認(5分)
// ❌ 問題: データが変わると .id() も変わる
DetailView()
.id(item.id + "-\(isEditing)") // isEditing で ID が変わる
// ✅ 修正: 安定した ID
DetailView()
.id(item.id) // 安定した ID
検索: コードベースで .id( を検索 — ID 値が変化するか確認
3. ForEach の識別子を確認(5分)
// ❌ 間違い: インデックスベースの ID
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
Text(item.name)
}
// ❌ 間違い: 一意でない ID
ForEach(items, id: \.category) { item in // カテゴリごとに複数のアイテム
Text(item.name)
}
// ✅ 正しい: 一意で安定した ID
ForEach(items, id: \.id) { item in
Text(item.name)
}
検索: ForEach を検索 — 一意で安定した ID を確認
修正パターン:
| 問題 | 修正 |
|---|---|
| 条件内のビュー | 代わりに .opacity() を使用 |
| .id() が頻繁に変わる | 安定した識別子を使用 |
| ForEach が飛び回る | 一意で安定した ID を使用(UUID またはサーバー ID) |
| ナビゲーションで状態がリセットされる | NavigationStack のパス管理を確認 |
確認:
- Self._printChanges() を追加 — "@self changed" が繰り返し表示されるべきではない
- アニメーションがスムーズに動作するようになるはず
- @State の値が維持されるはず
パターン D4: 環境依存関係チェック
所要時間: 10分
症状: 無関係なデータが変更されたときに多くのビューが更新される
使用すべき時:
- 原因と影響グラフで「Environment」ノードが多くの更新をトリガーしている
- スクロールやアニメーションのパフォーマンスが遅い
- 予期しないカスケード更新
根本原因: 頻繁に変化する値が環境にある、またはあまりに多くのビューが環境を読み取っている
調査手順:
1. 環境への書き込みを探す(3分)
# 現在のプロジェクトで環境モディファイアを検索
grep -r "\.environment(" --include="*.swift" .
確認すべきもの:
// ❌ 悪い例: 頻繁に変化する値
.environment(\.scrollOffset, scrollOffset) // 毎秒60回以上更新
.environment(model) // モデルが頻繁に更新される場合
// ✅ 良い例: 安定した値
.environment(\.colorScheme, .dark)
.environment(appModel) // appModel の変更が稀な場合
2. 環境にあるものを確認(3分)
パターン D2(Instruments)を使用して、原因と影響グラフを確認:
- 「Environment」ノードをクリック
- どのプロパティが変更されたか確認
- 更新をチェックしたビューの数をカウント
質問:
- この値はスクロール/アニメーションのフレームごとに変化していますか?
- これらすべてのビューが実際にこの値を必要としていますか?
3. 修正を適用(4分)
修正 A: 環境から削除(頻繁に変化する場合):
// ❌ 修正前: 環境
.environment(\.scrollOffset, scrollOffset)
// ✅ 修正後: 直接パラメータ
ChildView(scrollOffset: scrollOffset)
修正 B: @Observable モデルを使用(多くのビューで必要な場合):
// 環境にプリミティブを保存する代わりに:
@Observable class ScrollViewModel {
var offset: CGFloat = 0
}
// ビューは特定のプロパティに依存:
@Environment(ScrollViewModel.self) private var viewModel
var body: some View {
Text("\(viewModel.offset)") // offset が変更された時のみ更新
}
確認:
- Instruments で新しいトレースを記録
- 原因と影響グラフを確認 — 更新されるビューが減少しているはず
- パフォーマンスが向上しているはず(スクロール/アニメーションがよりスムーズに)
パターン D5: プレビュー診断(Xcode 26)
所要時間: 10分
症状: プレビューが読み込まれない、または不明瞭なエラーでクラッシュする
使用すべき時:
- 基本的な修正(swiftui-debugging スキル)後もプレビューが失敗する
- エラーメッセージが不明瞭または一般的
- プレビューが以前は動作していたが、突然停止した
調査手順:
1. プレビュー診断ボタンを使用(2分)
場所: Editor メニュー → Canvas → Diagnostics
表示されるもの:
- 詳細なエラーメッセージ
- 不足している依存関係
- 状態の初期化の問題
- プレビュー固有の問題
2. クラッシュログを確認(3分)
# クラッシュログディレクトリを開く
open ~/Library/Logs/DiagnosticReports/
# 「Preview」を含む最近の .crash ファイルを探す
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i preview | head -5
確認すべきもの:
- 致命的なエラー(配列の範囲外、強制アンラップ nil)
- 不足しているモジュールのインポート
- フレームワークの初期化失敗
3. 問題を分離する(5分)
最小限のプレビューを作成:
// 空のプレビューから開始
#Preview {
Text("Test")
}
// これが動作する場合、徐々に追加:
#Preview {
MyView() // 実際のビュー、ただしモックデータを使用
.environment(MockModel()) // すべての依存関係を提供
}
// どの依存関係がクラッシュを引き起こすか特定
よくある問題:
| エラー | 原因 | 修正 |
|---|---|---|
| "Cannot find in scope" | 依存関係の不足 | プレビューに追加(下記の例参照) |
| "Fatal error: Unexpectedly found nil" | オプショナルのアンラップ失敗 | プレビューで非 nil の値を提供 |
| "No such module" | インポート不足 | import 文を追加 |
| サイレントクラッシュ(エラーなし) | 無効な値での状態初期化 | 安全なデフォルトを使用 |
修正パターン:
// @Environment の不足
#Preview {
ContentView()
.environment(AppModel()) // 依存関係を提供
}
// @EnvironmentObject の不足(iOS 17 未満)
#Preview {
ContentView()
.environmentObject(AppModel())
}
// ModelContainer の不足(SwiftData)
#Preview {
let config = ModelConfiguration(isStoredInMemoryOnly: true)
let container = try! ModelContainer(for: Item.self, configurations: config)
ContentView()
.modelContainer(container)
}
確認:
- プレビューがロードされ、インタラクティブになる
- クラッシュログに新しいエントリがない
- 同じ問題が発生した場合、パターン D2 に進む