SwiftUIデバッグ
概要
SwiftUIのデバッグは、3つのカテゴリに分類され、それぞれ異なる診断アプローチが必要です:
- ビューが更新されない – 何かを変更したのにビューが再描画されません。構造体の直接変更、バインディングの同一性喪失、誤ったビューの再作成、オブザーバーパターンの欠落を特定するための決断ツリー。
- プレビュークラッシュ – プレビューがコンパイルできないか、即座にクラッシュします。依存関係の欠落、状態初期化の失敗、Xcodeキャッシュの破損を区別するための決断ツリー。
- レイアウト問題 – ビューが間違った位置、間違ったサイズで表示されたり、予期せず重なったりします。一般的なシナリオのためのクイックリファレンスパターン。
基本原則: 観察可能な症状から始め、体系的にテストし、原因を一つずつ排除する。推測はしない。
必要条件: Xcode 26+、iOS 17+(iOS 14-16のパターンも有効、注釈参照)
関連スキル: axiom-xcode-debugging(キャッシュ破損診断)、axiom-swift-concurrency(オブザーバーパターン)、axiom-swiftui-performance(Instrumentsを使用したプロファイリング)、axiom-swiftui-layout(適応型レイアウトパターン)
使用例(プロンプト)
以下は、開発者が実際に尋ねる質問と、このスキルがどのように回答を導くかを示した例です:
1. 「リスト項目をお気に入りボタンでタップしても更新されません。データは変わったのに」
→ スキルは構造体の直接変更、バインディングの同一性喪失、オブザーバーパターンの欠落を特定する決断ツリーを提供します。
2. 「プレビューが'Cannot find AppModel in scope'でクラッシュしますが、コンパイルは通ります」
→ スキルは、.environment()または.environmentObject()を使用して欠落している依存関係を提供する方法を示します。
3. 「ブール値をトグルするたびにカウンターが0にリセットされるのはなぜですか?」
→ スキルは条件文による誤ったビューの再作成を特定し、.opacity()による修正を示します。
4. 「@Observableを使用していますが、プロパティを変更してもビューが更新されません」
→ スキルは、@Stateと@Observableオブジェクトのプレーンプロパティをいつ使用すべきかを説明します。
5. 「テキストフィールドが入力を開始するとフォーカスを失います。とてもイライラします」
→ スキルはForEachの同一性問題を特定し、安定したIDを使用する方法を示します。
SwiftUIデバッグを使用すべき時
このスキルを使うべき場合
- ✅ ビューが期待通りに更新されない
- ✅ プレビューがクラッシュする、または読み込めない
- ✅ 特定のデバイスでレイアウトが正しく表示されない
- ✅ どこにでも@ObservedObjectを付けて応急処置をしたくなる
代わりにaxiom-xcode-debuggingを使うべき場合
- アプリがランタイムでクラッシュする(プレビュー以外)
- ビルドが完全に失敗する
- 環境診断が必要
代わりにaxiom-swift-concurrencyを使うべき場合
- async/awaitやMainActorに関する質問
- データ競合の警告
デバッグツール
Self._printChanges()
SwiftUIは、ビューのbodyが呼び出された理由を理解するためのデバッグ専用メソッドを提供します。
LLDBでの使用法:
// ビューのbodyにブレークポイントを設定
// LLDBコンソールで:
(lldb) expression Self._printChanges()
コードへの一時的な挿入(リリース前に削除すること):
var body: some View {
let _ = Self._printChanges() // デバッグ専用
Text("Hello")
}
出力の解釈:
MyView: @self changed
- ビュー自体の値が変更された(ビューに渡されたパラメータ)
MyView: count changed
- @Stateプロパティ「count」が更新をトリガーした
MyView: (no output)
- Bodyが呼び出されていない。ビューがまったく更新されていない
⚠️ 重要:
- アンダースコアプレフィックス → 将来のリリースで削除される可能性あり
- 絶対にApp Storeに提出しない _printChanges呼び出しを含めないこと
- パフォーマンスへの影響 → デバッグ中のみ使用すること
使用すべき時:
- ビュー更新の正確なトリガーを理解する必要がある
- 予期しない更新を調査している
- リファクタリング後の依存関係を確認する
相互参照: 複雑な更新パターンについては、SwiftUI Instrumentを使用 → axiom-swiftui-performanceスキルを参照
ビューが更新されない場合の決断ツリー
最もよくあるフラストレーション: @Stateを変更したのにビューが再描画されない。根本原因は常に4つのうちのいずれかです。
ステップ1: 最小限のプレビューで再現できますか?
#Preview {
YourView()
}
はい → 問題はコード内にあります。ステップ2に進んでください。
いいえ → Xcodeの状態またはキャッシュの破損が原因の可能性があります。「プレビュークラッシュ」セクションに進んでください。
ステップ2: 根本原因を診断する
根本原因1: 構造体の直接変更
症状: @State値を直接変更したが、ビューが更新されない。
なぜ起こるか: SwiftUIは構造体への直接変更を認識しません。値を丸ごと再代入する必要があります。
// ❌ 間違い: 直接変更は更新をトリガーしない
@State var items: [String] = []
func addItem(_ item: String) {
items.append(item) // SwiftUIはこの変更を認識しない
}
// ✅ 正しい: 再代入が更新をトリガーする
@State var items: [String] = []
func addItem(_ item: String) {
var newItems = items
newItems.append(item)
self.items = newItems // 完全な再代入
}
// ✅ こちらも正しい: バインディングを使用する
@State var items: [String] = []
var itemsBinding: Binding<[String]> {
Binding(
get: { items },
set: { items = $0 }
)
}
修正方法: 構造体の一部ではなく、値を丸ごと再代入する。
根本原因2: バインディングの同一性喪失
症状: 子ビューにバインディングを渡したが、子ビューでの変更が親ビューに反映されない。
なぜ起こるか: .constant()を渡しているか、毎回新しいバインディングを作成しているため、双方向の接続が切れています。
// ❌ 間違い: 定数バインディングは読み取り専用
@State var isOn = false
ToggleChild(value: .constant(isOn)) // 変更は無視される
// ❌ 間違い: レンダリングごとに新しいバインディングを作成
@State var name = ""
TextField("Name", text: Binding(
get: { name },
set: { name = $0 }
)) // 親がレンダリングされるたびに新しいバインディングオブジェクトが作成される
// ✅ 正しい: 実際のバインディングを渡す
@State var isOn = false
ToggleChild(value: $isOn)
// ✅ 正しい (iOS 17+): @Observableオブジェクトには@Bindableを使用
@Observable class Book {
var title = "Sample"
var isAvailable = true
}
struct EditView: View {
@Bindable var book: Book // $book.title構文を可能にする
var body: some View {
TextField("Title", text: $book.title)
Toggle("Available", isOn: $book.isAvailable)
}
}
// ✅ こちらも正しい (iOS 17+): @Bindableをローカル変数として使用
struct ListView: View {
@State private var books = [Book(), Book()]
var body: some View {
List(books) { book in
@Bindable var book = book // インラインバインディング
TextField("Title", text: $book.title)
}
}
}
// ✅ 正しい (iOS 17未満): バインディングはbody内ではなく、一度だけ作成する
@State var name = ""
@State var nameBinding: Binding<String>?
var body: some View {
if nameBinding == nil {
nameBinding = Binding(
get: { name },
set: { name = $0 }
)
}
return TextField("Name", text: nameBinding!)
}
修正方法: 可能な場合は$stateを直接渡す。@Observableオブジェクト(iOS 17+)の場合は@Bindableを使用する。カスタムバインディングを作成する場合(iOS 17未満)は、init内で作成するかキャッシュし、body内では作成しない。
根本原因3: 誤ったビューの再作成
症状: ビューは更新されるが、@State値が初期状態にリセットされる。初期値が一瞬表示される。
なぜ起こるか: ビューが新しいIDを取得した(条件文から削除された、コンテナ内で移動された、またはコンテナ自体が再作成された)ため、SwiftUIが新しいビューとして扱います。
// ❌ 間違い: 条件が切り替わるとビューのIDが変わる
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter() // showCounterが変わるたびに新しいIDを取得
}
Button("Toggle") {
showCounter.toggle()
}
}
}
// Counterが再作成され、@State countが0にリセットされる
// ✅ 正しい: opacityまたはhiddenでIDを維持する
@State var count = 0
var body: some View {
VStack {
Counter()
.opacity(showCounter ? 1 : 0)
Button("Toggle") {
showCounter.toggle()
}
}
}
// ✅ こちらも正しい: どうしても条件付きで表示する場合はid()を使用
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter()
.id("counter") // 安定したID
}
Button("Toggle") {
showCounter.toggle()
}
}
}
修正方法: 条件文の代わりに.opacity()を使用するか、.id()に安定した識別子を指定してビューのIDを維持する。
根本原因4: オブザーバーパターンの欠落
症状: オブジェクトが変更されたが、それを監視しているビューが更新されない。
なぜ起こるか: SwiftUIがオブジェクトの変更を監視する方法を知らないため。
// ❌ 間違い: プロパティの変更が更新をトリガーしない
class Model {
var count = 0 // 監視可能ではない
}
struct ContentView: View {
let model = Model() // レンダリングごとに新しいインスタンス、監視不可
var body: some View {
Text("\(model.count)")
Button("Increment") {
model.count += 1 // ビューは更新されない
}
}
}
// ✅ 正しい (iOS 17+): @Stateとともに@Observableを使用
@Observable class Model {
var count = 0 // @Publishedは不要
}
struct ContentView: View {
@State private var model = Model() // @StateObjectではなく@State
var body: some View {
Text("\(model.count)")
Button("Increment") {
model.count += 1 // ビューが更新される
}
}
}
// ✅ 正しい (iOS 17+): 注入された@Observableオブジェクト
struct ContentView: View {
var model: Model // 単なるプレーンプロパティ
var body: some View {
Text("\(model.count)") // countが変わるとビューが更新される
}
}
// ✅ 正しい (iOS 17+): @Observableと環境
@Observable class AppModel {
var count = 0
}
@main
struct MyApp: App {
@State private var model = AppModel()
var body: some Scene {
WindowGroup {
ContentView()
.environment(model) // 環境に追加
}
}
}
struct ContentView: View {
@Environment(AppModel.self) private var model // 環境から読み取り
var body: some View {
Text("\(model.count)")
}
}
// ✅ 正しい (iOS 17未満): @StateObject/ObservableObjectを使用
class Model: ObservableObject {
@Published var count = 0
}
struct ContentView: View {
@StateObject var model = Model() // 所有するインスタンスの場合
var body: some View {
Text("\(model.count)")
Button("Increment") {
model.count += 1 // ビューが更新される
}
}
}
// ✅ 正しい (iOS 17未満): 注入されたインスタンスには@ObservedObjectを使用
struct ContentView: View {
@ObservedObject var model: Model // 親から渡される
var body: some View {
Text("\(model.count)")
}
}
修正方法 (iOS 17+): クラスに@Observableマクロを使用し、@Stateで保存する。ビューは自動的に読み取ったプロパティへの依存関係を追跡します。
修正方法 (iOS 17未満): オブジェクトを所有している場合は@StateObject、注入されている場合は@ObservedObject、ツリー全体で共有されている場合は@EnvironmentObjectを使用します。
@Observableの方が優れている理由 (iOS 17+):
- 自動依存関係追跡(読み取りのみが更新をトリガーする)
@Publishedラッパーが不要@StateObjectの代わりに@Stateで動作@ObservedObjectの代わりにプレーンプロパティとして渡せる
関連項目: Managing model data in your app
決断ツリーのまとめ
digraph view_not_updating {
start [label="View not updating?" shape=diamond];
reproduce [label="Can reproduce in preview?" shape=diamond];
cause [label="What changed?" shape=diamond];
start -> reproduce;
reproduce -> cause [label="yes: bug in code"];
reproduce -> "Cache/Xcode state → Preview Crashes" [label="no"];
cause -> "Struct Mutation" [label="modified struct directly"];
cause -> "Lost Binding Identity" [label="passed binding to child"];
cause -> "Accidental Recreation" [label="view inside conditional"];
cause -> "Missing Observer" [label="object changed, view didn't"];
}
プレビュークラッシュの決断ツリー
プレビューが読み込めない、または即座にクラッシュする場合、3つの根本原因は明確に区別できます。
ステップ1: エラーは何ですか?
エラータイプ1: "Cannot find in scope" または "No such module"
根本原因: プレビューに必要な依存関係(@EnvironmentObject、@Environment、インポートされたモジュール)が不足しています。
// ❌ 間違い: ContentViewはモデルを必要とするが、プレビューはそれを提供しない
struct ContentView: View {
@EnvironmentObject var model: AppModel
var body: some View {
Text(model.title)
}
}
#Preview {
ContentView() // クラッシュ: modelが見つからない
}
// ✅ 正しい: 依存関係を提供する
#Preview {
ContentView()
.environmentObject(AppModel())
}
// ✅ こちらも正しい: 不足しているインポートがないか確認
// カスタムタイプを使用している場合、プレビューファイルにインポートされていることを確認
#Preview {
MyCustomView() // MyCustomViewが定義されているか、インポートされていることを確認
}
修正方法: エラーを追跡し、何が不足しているかを見つけ、プレビューに提供する。
エラータイプ2: 致命的エラーまたはサイレントクラッシュ(エラーメッセージなし)
根本原因: 状態の初期化がランタイムで失敗しました。ビューが存在しないデータにアクセスしようとしました。
// ❌ 間違い: ランタイムでインデックス範囲外
struct ListView: View {
@State var selectedIndex = 10
let items = ["a", "b", "c"]
var body: some View {
Text(items[selectedIndex]) // クラッシュ: インデックス10は存在しない
}
}
// ❌ 間違い: オプショナルの強制アンラップに失敗
struct DetailView: View {
@State var data: Data?
var body: some View {
Text(data!.title) // dataがnilの場合クラッシュ
}
}
// ✅ 正しい: 安全なデフォルト値
struct ListView: View {
@State var selectedIndex = 0 // 有効なインデックス
let items = ["a", "b", "c"]
var body: some View {
if selectedIndex < items.count {
Text(items[selectedIndex])
}
}
}
// ✅ 正しい: オプショナルを適切に処理
struct DetailView: View {
@State var data: Data?
var body: some View {
if let data = data {
Text(data.title)
} else {
Text("No data") // 安全な代替表示
}
}
}
修正方法: 状態に安全な初期値を設定するか、オプショナルバインディングを使用してクラッシュを防ぐ。
エラータイプ3: Xcodeキャッシュの破損
根本原因: 派生データが壊れている、または古くなっている。
症状:
- コードを変更していないのにプレビューがコンパイルに失敗する
- ビルドは成功するがプレビューがクラッシュする
- プロジェクトをクリーンしても問題が解決しない
診断手順:
# ステップ1: 派生データをクリア
# Xcodeメニュー → Settings → Locations → Derived Dataの矢印をクリック → フォルダを削除
# ステップ2: Xcodeを完全に終了
# Cmd+QでXcodeを終了し、アクティビティモニタでXcodeプロセスが残っていないことを確認
# ステップ3: キャッシュを手動でクリア(必要な場合)
rm -rf ~/Library/Caches/com.apple.dt.Xcode
# ステップ4: Xcodeを再起動し、Product → Clean Build Folder (Cmd+Shift+K)
# 次にCmd+Bで再ビルド
さらに進んだ診断:
~Library/Developer/Xcode/DerivedData/を確認し、重複または破損したフォルダを手動で削除- SwiftUIプレビューコンパイラは通常のビルドコンパイラとは別のキャッシュを使用しているため、完全なクリーンが必要な場合がある
参考: 詳しい診断については、axiom-xcode-debuggingスキルを参照。
プレビュークラッシュの決断ツリーのまとめ
digraph preview_crashes {
start [label="Preview crashes?" shape=diamond];
error [label="Error type?" shape=diamond];
cache [label="Cache corruption?" shape=diamond];
start -> error;
error -> "Missing Dependencies" [label="cannot find in scope"];
error -> "State Init Failure" [label="fatal error or silent crash"];
error -> "Xcode Cache Corruption" [label="no error or intermittent"];
"Xcode Cache Corruption" -> cache [label="try clean build"];
cache -> "Derived Data" [label="clear derived data"];
cache -> "Xcode Restart" [label="full Xcode restart"];
}
レイアウト問題の診断
ビューのサイズ、位置、重なりに関する問題は通常、3つの根本原因のいずれかに分類されます。
根本原因1: ジオメトリの競合
症状: ビューが間違った位置に配置される、間違ったサイズになる、または予期せずクリップされる。
なぜ起こるか: 以下のいずれか:
- 競合する
frame修飾子(例:.infinityと具体的な値) - 親ビューが要求を満たせない
idealWidth/idealHeight - 間違った
alignment引数がスタックに渡された
// ❌ 間違い: 競合するフレーム制約
struct MyView: View {
var body: some View {
HStack(spacing: 0) {
Text("Left")
.frame(maxWidth: .infinity) // 可能な限り広く
.frame(width: 100) // しかし幅は100に固定
Text("Right")
.frame(maxWidth: .infinity)
}
}
}
// ✅ 正しい: 一貫したフレーム制約
struct MyView: View {
var body: some View {
HStack(spacing: 0) {
Text("Left")
.frame(width: 100) // 固定幅
Text("Right")
.frame(maxWidth: .infinity) // 残りのスペースを埋める
}
}
}
修正方法: フレーム制約の一貫性を確保する。frame修飾子を削除してデフォルトのサイズ動作に頼ることも検討する。
根本原因2: レイアウトの優先順位の問題
症状: 一部のビューが他のビューよりも多くのスペースを占めている。
// ❌ 間違い: 低優先度のビューが縮められる
struct MyView: View {
var body: some View {
HStack {
Text("Short")
Text("Very long text that will be truncated or cause layout issues")
.lineLimit(1) // 縮められる
}
}
}
// ✅ 正しい: レイアウト優先度を使用
struct MyView: View {
var body: some View {
HStack {
Text("Short")
.layoutPriority(1) // Shortは最小幅を維持
Text("Very long text that will be truncated or cause layout issues")
.lineLimit(1)
}
}
}
修正方法: .layoutPriority()を使用して、どのビューが余分なスペースを取得すべきかを指定する(0 = デフォルト、1 = 高い優先度、2 = さらに高い)。
根本原因3: 安全領域の無視
症状: ビューがDynamic Island、ホームインジケーター、ノッチの下に隠れる。
// ❌ 間違い: 安全領域を無視した結果、クリップされる
struct MyView: View {
var body: some View {
VStack {
Text("Top")
.frame(maxWidth: .infinity)
.background(Color.blue)
.ignoresSafeArea(.all) // すべての安全領域を無視
}
}
}
// ✅ 正しい: 安全領域は上端のみ無視
struct MyView: View {
var body: some View {
VStack {
Text("Top")
.frame(maxWidth: .infinity)
.background(Color.blue)
.ignoresSafeArea(.keyboard, edges: .top) // キーボードのみ上部を無視
}
}
}
修正方法: .ignoresSafeArea()は慎重に使用する。通常はデフォルトの安全領域の動作で十分。根本的な原因が安全領域にある場合は、最小限の方法で無視する(例:単一のエッジのみ)。
レイアウト問題の診断まとめ
digraph layout_issues {
start [label="Layout issue?" shape=diamond];
cause [label="Symptom type?" shape=diamond];
start -> cause;
cause -> "Geometry Conflict" [label="wrong size/position"];
cause -> "Layout Priority" [label="one view dominates"];
cause -> "Safe Area" [label="clipped at edges"];
}
付録: クイックリファレンス
よくある問題と解決策
| 問題 | 最も可能性の高い原因 | 解決策 |
|---|---|---|
| @Stateを変更してもビューが更新されない | 構造体の直接変更 | 値全体を再代入する |
| 子ビューで変更した内容が親に反映されない | バインディングの同一性喪失 | $stateを直接渡す |
| @Stateがリセットされる | 誤ったビューの再作成 | .opacity()または.id()を使用 |
| @Observableオブジェクトが更新をトリガーしない | オブザーバーパターンの欠落 | @Stateとともに@Observableを使用 |
| プレビューが"Cannot find in scope"でクラッシュ | 依存関係の欠落 | .environmentObject()または.environment()で提供 |
| プレビューがサイレントクラッシュ | 状態初期化の失敗 | nilまたは範囲外に安全なデフォルト値を設定 |
| プレビューが断続的にクラッシュ | Xcodeキャッシュの破損 | 派生データをクリア |
| ビューが間違った位置やサイズになる | ジオメトリの競合 | frame制約に一貫性を持たせる |
| 一部のビューが他のビューよりも多くのスペースを占める | レイアウトの優先順位 | .layoutPriority()を使用 |
| ビューが端でクリップされる | 安全領域の無視 | .ignoresSafeArea()は最小限に使用 |
iOSバージョン別の推奨パターン
| パターン | iOS 14-16 | iOS 17+ |
|---|---|---|
| 監視可能な状態 | @StateObject/ObservableObject | @Observableマクロ |
| 状態オブジェクトの所有 | @StateObject | @State private var |
| 状態オブジェクトの注入 | @ObservedObject | プレーンプロパティ |
| 環境状態 | @EnvironmentObject | @Environment(Model.self) |
| バインディングの作成 | initで作成、キャッシュ | @Bindableまたは$構文 |
| ビューのID維持 | @Stateフラグ + opacity | .id()タグ + opacity |
関連スキル
axiom-xcode-debugging: Xcode環境の問題、ビルドの失敗、キャッシュの破損の診断axiom-swift-concurrency: async/await、MainActor、データ競合のデバッグaxiom-swiftui-performance: InstrumentsによるSwiftUIのプロファイリング、更新の最小化axiom-swiftui-layout: 適応型レイアウトパターン、動的タイプ、サイズクラス