SwiftUI ナビゲーション診断
概要
基本原理 ナビゲーション問題の85%は、パス状態管理のエラー、ビューIDの問題、または配置ミスに起因します。SwiftUI自体の欠陥ではありません。
SwiftUIのナビゲーションシステムは、何百万ものアプリで使用され、複雑なナビゲーションパターンを確実に処理しています。ナビゲーションが機能しない、応答しない、または予期しない動作をする場合、その原因はほとんどの場合、フレームワーク自体ではなく、ナビゲーション状態の管理方法にあります。
このスキルは、原因を数時間ではなく数分で特定するための系統的な診断を提供します。
レッドフラグ — ナビゲーション問題の疑い
次のいずれかが見られた場合、フレームワークの破損ではなくコードの問題を疑ってください:
-
ナビゲーションタップが何も反応しない(リンクは存在するがプッシュされない)
-
戻るボタンが間違った画面またはルートにポップする
-
ディープリンクでアプリが開くが、間違った画面が表示される
-
タブ切り替え時にナビゲーション状態が失われる
-
アプリがバックグラウンドになったときにナビゲーション状態が失われる
-
同じNavigationLinkが2回プッシュされる
-
ナビゲーションアニメーションがスタックまたはカクつく
-
navigationDestinationがスタックトレースに含まれるクラッシュ -
❌ 禁止 「SwiftUIのナビゲーションは壊れている。UINavigationControllerでラップしよう」
- NavigationStackはApple自身のアプリでも使用されている
- UIKitでラップすると複雑さが増し、SwiftUIの状態管理の利点が失われる
- UIKit相互運用には独自のエッジケースがあり、発見に数週間を費やすことになる
- 問題はほぼ間違いなくパス管理であり、フレームワークの欠陥ではない
重要な区別 NavigationStackの動作は決定論的です。動作しない場合、状態を誤って変更しているか、ビューIDの問題があるか、navigationDestinationの配置が間違っています。
必須の最初のステップ
常に最初にこれらのチェックを実行してください(コードを変更する前に):
// 1. NavigationPathのログを追加
NavigationStack(path: $path) {
RootView()
.onChange(of: path.count) { oldCount, newCount in
print("📍 パス変更: \(oldCount) → \(newCount)")
// これが決して発火しない場合、リンクがパスを変更していない
// 予期せず発火する場合、他の何かがパスを変更している
}
}
// 2. navigationDestinationが見えているか確認
// デスティネーションクロージャに一時的なprintを配置
.navigationDestination(for: Recipe.self) { recipe in
let _ = print("🔗 Recipeのデスティネーション: \(recipe.name)")
RecipeDetail(recipe: recipe)
}
// これが決して出力されない場合、デスティネーションが評価されていない
// 3. NavigationLinkがNavigationStackの内部にあるか確認
// 視覚的検査: NavigationLinkからビュー階層をさかのぼる
// 最初に他のコンテナではなくNavigationStackに到達する必要がある
// 4. パス状態の場所を確認
// @Stateは安定したビューにある必要がある(レンダリングごとに再作成されない)
// ローカル変数ではなく、@State、@StateObject、または@Observableである必要がある
// 5. 単体で基本的なケースをテスト
// 最小限の再現コードを作成
NavigationStack {
NavigationLink("テスト", value: "test")
.navigationDestination(for: String.self) { str in
Text("プッシュされました: \(str)")
}
}
// これが機能する場合、問題は特定の設定にある
これが示す内容
| 観察結果 | 診断 | 次のステップ |
|---|---|---|
| onChangeがタップで発火しない | NavigationLinkがNavigationStack階層にない | パターン1a |
| onChangeが発火するがビューがプッシュされない | navigationDestinationが見つからない/読み込まれていない | パターン1b |
| onChangeが発火し、ビューがプッシュされ、すぐにポップする | ビューIDの問題またはパス変更 | パターン2a |
| パスが予期せず変更される(タップ以外から) | 外部コードがパスを変更している | パターン2b |
| ディープリンク path.append() がナビゲートしない | タイミングの問題または間違ったスレッド | パターン3b |
| タブ切り替えで状態が失われる | NavigationStackがタブ間で共有されている | パターン4a |
| 初回は機能するが、戻ると失敗する | ビューの再作成の問題 | パターン5a |
必須の解釈
コードを変更する前に、次のうち1つを特定してください:
- リンクタップが何も起こらず、onChangeも発火しない → リンクがNavigationStackの外にある(階層を確認)
- onChangeが発火するが何もプッシュされない → navigationDestinationがスコープ内にない(配置を確認)
- プッシュされた直後にポップする → ビューIDの変更またはパスのリセット(@Stateの場所を確認)
- ディープリンクが失敗する → タイミングまたはMainActorの問題(スレッドを確認)
- クラッシュする → パスデコード時の強制アンラップまたは欠落した型登録
診断結果が矛盾している、または不明瞭な場合
- 停止してください。パターンに進まないでください
- すべてのパス変更ポイントにprint文を追加
- 最小限の再現ケースを作成
- 最初にString値でテストする(最も単純なケース)
判定ツリー
2分で正しい診断パターンに到達するために使用します:
ナビゲーション問題?
├─ ナビゲーションタップが何も反応しない?
│ ├─ NavigationLinkがNavigationStackの内部にある?
│ │ ├─ いいえ → パターン1a(リンクがスタックの外)
│ │ └─ はい → navigationDestinationを確認
│ │
│ ├─ navigationDestinationが登録されている?
│ │ ├─ 遅延コンテナの内部? → パターン1b(遅延読み込み)
│ │ ├─ 型の不一致? → パターン1c(型登録)
│ │ └─ シート/ポップオーバーでブロックされている? → パターン1d(モーダルブロッキング)
│ │
│ └─ ビューベースのリンクを使用している?
│ └─ → パターン1e(非推奨API)
│
├─ 予期しないポップバック?
│ ├─ プッシュ直後のポップ?
│ │ ├─ ビューボディがパスを再作成している? → パターン2a(パスの再作成)
│ │ ├─ @Stateが間違ったビューにある? → パターン2a(状態の場所)
│ │ └─ ForEachのidが変更されている? → パターン2c(識別子の変更)
│ │
│ ├─ ポップすべきでないときにポップする?
│ │ ├─ 外部コードがremoveLastを呼び出している? → パターン2b(予期しない変更)
│ │ ├─ タスクがキャンセルされた? → パターン2b(非同期キャンセル)
│ │ └─ MainActorの問題? → パターン2d(スレッド)
│ │
│ └─ 戻るボタンの動作が間違っている?
│ └─ → パターン2e(スタック破損)
│
├─ ディープリンクが機能しない?
│ ├─ URLを受信していない?
│ │ ├─ onOpenURLが呼び出されていない? → Info.plistのURLスキームを確認
│ │ └─ Universal Linksの問題? → apple-app-site-associationを確認
│ │
│ ├─ URLを受信したが、パスが更新されない?
│ │ ├─ path.appendがMainActor上でない? → パターン3a(スレッド)
│ │ ├─ タイミングの問題(アプリ準備完了前)? → パターン3b(初期化)
│ │ └─ NavigationStackがまだ作成されていない? → パターン3b(ライフサイクル)
│ │
│ └─ パスが更新されたが、間違った画面が表示される?
│ ├─ パスの順序が間違っている? → パターン3c(パス構築)
│ ├─ 間違った型が追加された? → パターン3c(型不一致)
│ └─ アイテムが見つからない? → パターン3d(データ解決)
│
├─ 状態が失われる?
│ ├─ タブ切り替えで失われる?
│ │ ├─ NavigationStackが共有されている? → パターン4a(共有状態)
│ │ └─ タブが再作成される? → パターン4a(タブ識別子)
│ │
│ ├─ バックグラウンド/フォアグラウンドで失われる?
│ │ ├─ SceneStorageがない? → パターン4b(永続化なし)
│ │ └─ デコードに失敗する? → パターン4c(デコードエラー)
│ │
│ └─ 回転/サイズ変更で失われる?
│ └─ → パターン4d(レイアウト再作成)
│
├─ NavigationSplitViewの問題?
│ ├─ iPadでサイドバーが表示されない?
│ │ ├─ columnVisibilityが設定されていない? → パターン6a(カラム可視性)
│ │ └─ コンパクトサイズクラス? → パターン6a(自動適応)
│ │
│ ├─ iPadで詳細が空白で表示される?
│ │ ├─ デフォルトの詳細ビューがない? → パターン6b(詳細欠落)
│ │ └─ 選択バインディングがnil? → パターン6b(選択状態)
│ │
│ └─ iPhoneでは機能するが、iPadで壊れている?
│ └─ → パターン6c(プラットフォーム適応)
│
└─ クラッシュする?
├─ EXC_BAD_ACCESSがナビゲーションコード内で発生?
│ └─ → パターン5a(メモリ問題)
│
├─ fatal error: 型が登録されていない?
│ └─ → パターン5b(欠落したデスティネーション)
│
└─ 復元時のデコード失敗?
└─ → パターン5c(復元クラッシュ)
パターン選択ルール(必須)
パターンに進む前に:
- ナビゲーションタップが何も反応しない → まずonChangeログを追加し、次にパターン1
- 予期しないポップ → 何がパスを変更しているか特定する(ログ)、次にパターン2
- ディープリンクが失敗する → URLが受信されたか確認する(onOpenURL内のprint)、次にパターン3
- 状態が失われる → いつ失われるか特定する(タブ切り替えかバックグラウンドか)、次にパターン4
- クラッシュする → 完全なスタックトレースを取得し、次にパターン5
一度に1つのパターンを適用
- 1つのパターンから修正を実装
- 徹底的にテスト
- 問題が続く場合のみ、次のパターンを試す
- 複数のパターンを同時に適用しないでください(原因を分離できません)
禁止
- 診断なしに解決策を推測すること
- 複数のことを同時に変更すること
- 「SwiftUIは壊れている」という理由でUINavigationControllerでラップすること
- 理由を理解せずに遅延やDispatchQueue.main.asyncを追加すること
- 「パスの問題を避ける」ためにビューベースのNavigationLinkに切り替えること
診断パターン
パターン1a: NavigationLinkがNavigationStackの外にある
時間コスト 5〜10分
症状
- NavigationLinkをタップしても何も起こらない
- ナビゲーションは発生せず、エラーもない
- onChange(of: path)が発火しない
診断
// ビュー階層を確認 — NavigationLinkはNavigationStackの**内部**にある必要がある
// ❌ 間違い — リンクがスタックの外
struct ContentView: View {
var body: some View {
VStack {
NavigationLink("Go", value: "test") // スタックの外!
NavigationStack {
Text("Root")
}
}
}
}
// 確認: NavigationStackに背景色を追加
NavigationStack {
Color.red // リンクが赤い上にある場合、内部にある
}
修正
// ✅ 正しい — リンクがスタックの内部
struct ContentView: View {
var body: some View {
NavigationStack {
VStack {
NavigationLink("Go", value: "test") // スタックの内部
Text("Root")
}
.navigationDestination(for: String.self) { str in
Text("Pushed: \(str)")
}
}
}
}
確認
- リンクをタップ、ナビゲーションが発生する
- タップ時にonChange(of: path)が発火する
パターン1b: 遅延コンテナ内のnavigationDestination
時間コスト 10〜15分
症状
- NavigationLinkのタップが何も反応しない、または断続的に機能する
- onChangeが発火する(パスが更新される)がビューがプッシュされない
- コンソールに「A navigationDestination for [Type] was not found」と表示される場合がある
診断
// ❌ 間違い — デスティネーションが遅延コンテナ内にある(読み込まれない可能性がある)
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // 評価されない可能性がある!
}
}
}
}
修正
// ✅ 正しい — デスティネーションを遅延コンテナの外に
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
}
}
}
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // 常に利用可能
}
確認
- デスティネーションクロージャにprintを追加 — ナビゲーション時に常に出力されるべき
- スクロール位置に関係なく機能する
パターン1c: 型登録の不一致
時間コスト 10分
症状
- ナビゲーションタップが何も反応しない
- 値の型に一致するnavigationDestinationがない
- 一部のリンクは機能するが、他のリンクは機能しない場合がある
診断
// 確認: 値の型はデスティネーションの型と**正確に**一致する必要がある
// リンクはRecipeを使用
NavigationLink(recipe.name, value: recipe) // valueはRecipe
// デスティネーションは... Recipe.IDで登録されている?
.navigationDestination(for: Recipe.ID.self) { id in // ❌ 間違った型!
RecipeDetail(id: id)
}
修正
// 型を正確に一致させる
NavigationLink(recipe.name, value: recipe) // Recipe
.navigationDestination(for: Recipe.self) { recipe in // ✅ Recipe
RecipeDetail(recipe: recipe)
}
// または、リンクをIDを使用するように変更
NavigationLink(recipe.name, value: recipe.id) // Recipe.ID
.navigationDestination(for: Recipe.ID.self) { id in // ✅ Recipe.ID
RecipeDetail(id: id)
}
確認
- デスティネーション内で型を出力:
print(type(of: value)) - 型は正確に一致する必要がある(継承は不可)
パターン2a: レンダリングごとにNavigationPathが再作成される
時間コスト 15〜20分
症状
- ナビゲーションがプッシュされた直後にポップバックする
- デスティネーションビューが「フラッシュ」するように見える
- 初回は機能するが、その後失敗する、または即座に失敗する
診断
// ❌ 間違い — ビューボディでパスを作成(レンダリングごとにリセット)
struct ContentView: View {
var body: some View {
let path = NavigationPath() // 毎回再作成される!
NavigationStack(path: .constant(path)) {
// ...
}
}
}
// ❌ 間違い — 再作成される子ビュー内の@State
struct ParentView: View {
@State var showChild = true
var body: some View {
if showChild {
ChildView() // showChildが切り替わると再作成される
}
}
}
struct ChildView: View {
@State var path = NavigationPath() // ChildViewが再作成されると失われる
// ...
}
修正
// ✅ 正しい — 安定したレベルで@State
struct ContentView: View {
@State private var path = NavigationPath() // レンダリング間で永続化
var body: some View {
NavigationStack(path: $path) {
RootView()
}
}
}
// ✅ 正しい — ObservableObjectに@StateObject
struct ContentView: View {
@StateObject private var navModel = NavigationModel()
var body: some View {
NavigationStack(path: $navModel.path) {
RootView()
}
}
}
確認
- onChangeログを追加 — パスが予期せずリセットされないこと
- ナビゲートして待機、path.countが安定していること
パターン2d: MainActor以外でパスが変更される
時間コスト 10〜15分
症状
- ナビゲーションは機能する場合としない場合がある
- Swift 6のMainActor分離に関する警告
- 予期しないポップまたは状態破損
診断
// ❌ 間違い — バックグラウンドタスクからパスを変更
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ⚠️ MainActor上ではない!
}
// 確認: @MainActorコンテキスト外でのpath.append、path.removeLastを検索
修正
// ✅ 正しい — MainActorを保証
@MainActor
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ✅ MainActorで分離
}
// または明示的にディスパッチ
func loadAndNavigate() async {
let recipe = await fetchRecipe()
await MainActor.run {
path.append(recipe)
}
}
// ✅ 最良 — @Observableを @MainActor クラスと併用
確認
- バックグラウンドタスクからナビゲートしても常に機能する
- Swift 6の警告がナビゲーションコードに表示されない
パターン4a: タブ間で共有されるNavigationStack
時間コスト 15〜20分
症状
- タブを切り替えるとナビゲーション状態が失われる
- タブに戻るとルートビューが表示される
- タブが再作成される
診断
// ❌ 間違い — すべてのタブで同じパスまたはNavigationStackを共有
TabView {
NavigationStack(path: $path) { // すべてのタブで同じ$path
HomeView()
}
.tabItem { Label("Home", systemImage: "house") }
NavigationStack(path: $path) { // 同じパス!
SettingsView()
}
.tabItem { Label("Settings", systemImage: "gear") }
}
修正
// ✅ 正しい — 各タブに独自のパス
TabView {
NavigationStack {
HomeView()
}
.tabItem { Label("Home", systemImage: "house") }
NavigationStack {
SettingsView()
}
.tabItem { Label("Settings", systemImage: "gear") }
}
確認
- タブ切り替え後も各タブのナビゲーションスタックが維持される
- タブを切り替えて戻ってもルートビューにリセットされない
パターン5a: ナビゲーションメモリの問題(EXC_BAD_ACCESS)
時間コスト 20〜30分
症状
EXC_BAD_ACCESSがナビゲーションコード内で発生- ランダムなクラッシュ、再現が困難
- 強参照サイクルまたは解放されたオブジェクトへのアクセス
診断
// 確認: NavigationStack内のクロージャ内の弱参照または所有されていない参照
// 循環参照の可能性
// ❌ 疑わしいパターン
class NavigationModel: ObservableObject {
@Published var path = NavigationPath()
// 循環参照を引き起こす可能性のある何かへの参照
}
struct ContentView: View {
@StateObject private var model = NavigationModel()
// modelがContentViewを強参照する場合...
}
修正
// ✅ 正しい — 循環を避けるため、[weak self]を使用
class NavigationModel: ObservableObject {
@Published var path = NavigationPath()
func navigate(to item: Item) {
// 循環がないことを確認
path.append(item)
}
}
// ZAPI ガイドに従ってNavigationStackを使用
確認
- 長時間のナビゲーションセッション後にクラッシュしない
- Instrumentsのリークチェッカーがナビゲーション関連のリークを報告しない
パターン5b: 欠落したデスティネーション(fatal error: type not registered)
時間コスト 10〜15分
症状
fatal error: A navigationDestination for [Type] was not found- 特定の型へのナビゲーションがクラッシュする
navigationDestination修飾子がない
診断
// 確認: プッシュする値の型ごとにnavigationDestinationがある
NavigationLink("レシピを表示", value: Recipe(id: 1, name: "シチュー"))
// Recipe型のnavigationDestinationが必要
// ❌ 欠落
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
修正
// ✅ 正しい — 必要なすべての型を登録
NavigationStack {
HomeView()
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
.navigationDestination(for: String.self) { str in
Text(str)
}
.navigationDestination(for: Int.self) { int in
Text("\(int)")
}
}
確認
- リンクで使用されるすべての型が、対応するnavigationDestinationを持っている
- 型はリンクの値と正確に一致する
パターン5c: 復元クラッシュ(デコード失敗)
時間コスト 15〜20分
症状
- アプリがバックグラウンドから戻ったときにクラッシュ
NavigationStackの復元中にクラッシュDecodableまたはEncodableの実装に関連するエラー
診断
// 確認: ナビゲーションパス内の値はCodableに準拠している必要がある
struct Recipe: Hashable, Codable {
let id: Int
let name: String
}
// ❌ 欠落している準拠
struct Recipe: Hashable {
let id: Int
let name: String // Codableではない
}
修正
// ✅ 正しい — すべてのパス値がCodableに準拠していることを確認
struct Recipe: Hashable, Codable {
let id: Int
let name: String
}
// カスタムデコードが必要な場合
enum CodingKeys: String, CodingKey {
case id
case name
}
確認
- アプリがバックグラウンドに入り、戻ってくる
- ナビゲーション状態が正しく復元される
- クラッシュしない
まとめ
重要な原則
- パス状態の管理 — @Stateは安定していることを確認
- ビューID — ForEachで安定したidを使用
- 配置 — navigationDestinationを遅延コンテナの外部に配置
- スレッド — 常にMainActor上でパスを変更
- 型 — リンクの値とデスティネーションの型を正確に一致
生産環境の防御
SceneStorageを使用してナビゲーション状態を永続化Codable準拠値をNavigationPathで使用onChangeログを無効化してデバッグビルドのみで出力assertionFailure()を予期しない状態に配置