Communitygithub.com

SwiftUI 導航診斷工具

用於調試導航無響應、意外彈窗、深層連結顯示錯誤畫面、切換分頁或背景執行時狀態遺失、navigationDestination 崩潰,或任何 SwiftUI 導航故障的系統性診斷工具,並提供生產環境危機防禦機制。

SwiftUI 導航診斷工具 是什麼?

這是一個專為 SwiftUI 開發者設計的系統性導航診斷技能,幫助快速定位並解決常見的導航問題,例如 NavigationLink 無反應、意外返回上層、深層連結失敗、分頁切換狀態遺失、背景執行恢復問題,以及 navigationDestination 崩潰。其核心原則是:85% 的導航問題源於路徑狀態管理錯誤、視圖識別問題或放置錯誤,而非 SwiftUI 框架本身的缺陷。 此工具支援所有使用 SwiftUI 的 Apple 平台(iOS、iPadOS、macOS、tvOS、watchOS),並要求使用者熟悉 NavigationStack 和 NavigationSplitView。它提供強制性的初始診斷步驟、決策樹和一系列有時間估算的修正模式(Pattern 1a 至 6c)。運作方式基於嚴格的「先診斷,再修正」原則:透過加入 `onChange(of: path.count)` 日誌和檢查 `navigationDestination` 是否被執行,來區分問題根本原因,再套用對應的單一模式進行修正。這些模式涵蓋了從連結位置錯誤、惰性容器、型別不符,到執行緒問題、狀態重建、路徑解碼失敗等所有常見情境。 對於開發及生產環境均適用,特別是在處理複雜的多層導航、深層連結或分頁架構時。強烈禁止使用者未經診斷就猜測解決方案、同時套用多個模式,或繞道使用 UINavigationController 來規避問題。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-nav-diag

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

SwiftUI 導航診斷工具 是做什麼的?

概述

核心原則 85% 的導航問題來自於路徑狀態管理錯誤、視圖識別問題或放置位置錯誤,而不是 SwiftUI 本身的缺陷。

SwiftUI 的導航系統已被數百萬個應用程式使用,並能可靠地處理複雜的導航模式。如果你的導航失敗、無反應或行為異常,問題幾乎總是出在你管理導航狀態的方式,而不是框架本身。

此技能提供系統性的診斷方法,讓你能在幾分鐘內(而非幾小時內)找出根本原因。

紅旗標誌 — 懷疑是導航問題

如果你看到任何以下情況,請懷疑是程式碼問題,而非框架故障:

  • 點擊導航無反應(連結存在但不會推入)

  • 返回按鈕彈出到錯誤畫面或根畫面

  • 深層連結開啟應用程式但顯示錯誤畫面

  • 切換分頁時導航狀態遺失

  • 應用程式背景化時導航狀態遺失

  • 同一個 NavigationLink 推入兩次

  • 導航動畫卡住或不平順

  • 在 navigationDestination 的堆疊追蹤中發生崩潰

  • ❌ 禁止「SwiftUI 導航壞了,我們用 UINavigationController 包起來吧」

    • NavigationStack 被 Apple 自家的應用程式使用
    • 包裝 UIKit 會增加複雜度,並失去 SwiftUI 的狀態管理優勢
    • UIKit 互通性有其自己的邊界情況,你會花上數週來發現
    • 你的問題幾乎肯定是路徑管理,而非框架缺陷

關鍵區別 NavigationStack 的行為是確定性的。如果它不工作,代表你修改狀態的方式不正確、有視圖識別問題,或是 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 觸發、視圖推入、然後立即彈出視圖識別問題或路徑修改模式 2a
路徑意外變更(非來自點擊)外部程式碼修改路徑模式 2b
深層連結 path.append() 不導航時序問題或執行緒錯誤模式 3b
切換分頁時狀態遺失NavigationStack 在多個分頁間共用模式 4a
第一次運作,返回後失敗視圖重建問題模式 5a

強制性解讀

在修改任何程式碼之前,請識別以下其中一項:

  1. 如果點擊連結沒有任何反應 且 onChange 無回應 → 連結在 NavigationStack 外部(檢查層級結構)
  2. 如果 onChange 觸發但沒有推入任何東西 → navigationDestination 不在範圍內(檢查放置位置)
  3. 如果推入後立即彈出 → 視圖識別變更或路徑重設(檢查 @State 的位置)
  4. 如果深層連結失敗 → 時序問題或 MainActor 問題(檢查執行緒)
  5. 如果崩潰 → 路徑解碼時的強制解包或缺少型別註冊

如果診斷結果矛盾或不明確

  • 停止。請勿繼續至模式步驟
  • 在每個路徑修改點加入 print 陳述式
  • 建立最小重現案例
  • 先使用 String 值進行測試(最簡單的案例)

決策樹

使用以下決策樹在 2 分鐘內找到正確的診斷模式:

導航問題?
├─ 點擊導航無反應?
│  ├─ NavigationLink 在 NavigationStack 內部?
│  │  ├─ 否 → 模式 1a(連結在堆疊外)
│  │  └─ 是 → 檢查 navigationDestination
│  │
│  ├─ navigationDestination 已註冊?
│  │  ├─ 在惰性容器內部? → 模式 1b(惰性載入)
│  │  ├─ 型別不符? → 模式 1c(型別註冊)
│  │  └─ 被 sheet/popover 阻擋? → 模式 1d(模態阻擋)
│  │
│  └─ 使用基於視圖的連結?
│     └─ → 模式 1e(棄用 API)
│
├─ 意外彈回?
│  ├─ 推入後立即彈出?
│  │  ├─ 視圖 body 重建路徑? → 模式 2a(路徑重建)
│  │  ├─ @State 在錯誤的視圖中? → 模式 2a(狀態位置)
│  │  └─ ForEach id 變更? → 模式 2c(識別變更)
│  │
│  ├─ 在不該彈出的時候彈出?
│  │  ├─ 外部程式碼呼叫 removeLast? → 模式 2b(非預期修改)
│  │  ├─ Task 被取消? → 模式 2b(非同步取消)
│  │  └─ MainActor 問題? → 模式 2d(執行緒問題)
│  │
│  └─ 返回按鈕行為錯誤?
│     └─ → 模式 2e(堆疊損毀)
│
├─ 深層連結無法運作?
│  ├─ URL 未被接收?
│  │  ├─ onOpenURL 未被呼叫? → 檢查 Info.plist 中的 URL scheme
│  │  └─ 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(缺少詳細頁)
│  │  └─ Selection 綁定為 nil? → 模式 6b(選取狀態)
│  │
│  └─ 在 iPhone 上正常,在 iPad 上損壞?
│     └─ → 模式 6c(平台適應)
│
└─ 崩潰?
   ├─ 導航程式碼中發生 EXC_BAD_ACCESS?
   │  └─ → 模式 5a(記憶體問題)
   │
   ├─ 致命錯誤:型別未註冊?
   │  └─ → 模式 5b(缺少目標)
   │
   └─ 恢復時解碼失敗?
      └─ → 模式 5c(恢復崩潰)

模式選擇規則(強制性)

在進行到一個模式之前:

  1. 點擊導航無反應 → 先加入 onChange 記錄,然後再進入模式 1
  2. 意外彈出 → 找出是什麼在修改路徑(記錄),然後再進入模式 2
  3. 深層連結失敗 → 驗證 URL 已被接收(在 onOpenURL 中 print),然後再進入模式 3
  4. 狀態遺失 → 識別何時遺失(分頁切換 vs 背景執行),然後再進入模式 4
  5. 崩潰 → 取得完整堆疊追蹤,然後再進入模式 5

一次只套用一個模式

  • 實作一個模式的修正
  • 徹底測試
  • 只有在問題仍然存在時,才嘗試下一個模式
  • 請勿同時套用多個模式(無法隔離原因)

禁止

  • 未經診斷就猜測解決方案
  • 一次改變多個東西
  • 因為「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("前往", value: "test")  // 在堆疊外部!
            NavigationStack {
                Text("根視圖")
            }
        }
    }
}

// 檢查:為 NavigationStack 加入背景顏色
NavigationStack {
    Color.red  // 如果連結在紅色上,代表它在內部
}

修正

// ✅ 正確 — 連結在堆疊內部
struct ContentView: View {
    var body: some View {
        NavigationStack {
            VStack {
                NavigationLink("前往", value: "test")  // 在堆疊內部
                Text("根視圖")
            }
            .navigationDestination(for: String.self) { str in
                Text("推入: \(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 分鐘

症狀

  • 導航推入後立即彈回
  • 看起來像目標檢視「閃爍」了一下
  • 第一次運作,然後失敗,或立即失敗

診斷

// ❌ 錯誤 — 路徑在視圖 body 中建立(每次渲染都重置)
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()
        }
    }
}

// ✅ 正確 — @StateObject 用於 ObservableObject
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
@MainActor
@Observable
class NavigationModel {
    var path = NavigationPath()
    
    func navigateAfterFetch() async {
        let recipe = await fetchRecipe()
        path.append(recipe)  // ✅ 自動在 MainActor 上
    }
}

驗證

  • 新增執行緒檢查:dispatchPrecondition(condition: .onQueue(.main))
  • 所有路徑修改都在主佇列上進行

模式 2e: NavigationSplitView 與 NavigationStack 搭配錯誤

時間成本 15-20 分鐘

症狀

  • 在 NavigationSplitView 內部使用 NavigationStack 時導航損壞
  • 側邊欄導航與詳細頁導航衝突
  • 返回按鈕行為異常

診斷

// ❌ 錯誤 — NavigationStack 放在 NavigationSplitView 外部
NavigationStack {
    NavigationSplitView {
        SidebarView()
    } content: {
        ContentListView()
    } detail: {
        DetailView()
    }
}
// 這會導致 NavigationStack 的導航與 SplitView 的導航衝突

// ❌ 錯誤 — NavigationStack 與 NavigationSplitView 的 selection 綁定混合
NavigationSplitView {
    SidebarView()
} content: {
    ContentListView()
        .navigationDestination(for: Item.self) { item in
            ItemDetail(item: item)  // 在錯誤的層級!
        }
} detail: {
    DetailView()
}

修正

// ✅ 正確 — 在第 3 欄(詳細頁)使用 NavigationStack
NavigationSplitView {
    SidebarView()
} content: {
    ContentListView()
} detail: {
    NavigationStack(path: $detailPath) {
        DetailView()
            .navigationDestination(for: Item.self) { item in
                ItemDetail(item: item)
            }
    }
}

// ✅ 正確 — 為每欄使用獨立的 NavigationStack
NavigationSplitView {
    NavigationStack(path: $sidebarPath) {
        SidebarView()
            .navigationDestination(for: Category.self) { category in
                CategoryView(category: category)
            }
    }
} content: {
    NavigationStack(path: $contentPath) {
        ContentListView()
            .navigationDestination(for: Item.self) { item in
                ItemDetail(item: item)
            }
    }
} detail: {
    NavigationStack(path: $detailPath) {
        DetailView()
            .navigationDestination(for: Item.self) { item in
                ItemDetail(item: item)
            }
    }
}

驗證

  • 每欄的導航獨立運作
  • 返回按鈕只會彈出到該欄內的上一個畫面
  • 側邊欄選取不會意外觸發導航

模式 3a: 深層連結時序問題

時間成本 10-15 分鐘

症狀

  • 應用程式從深層連結開啟時顯示錯誤畫面或空白畫面
  • 連結已接收,但導航未執行
  • 間歇性發生,特別是在應用程式冷啟動時

診斷

// 檢查 onOpenURL 是否在 NavigationStack 準備好之前被呼叫
struct ContentView: View {
    @State private var path = NavigationPath()
    @State private var pendingDeepLink: URL? = nil

    var body: some View {
        NavigationStack(path: $path) {
            RootView()
                .onOpenURL { url in
                    // 這裡可能在 NavigationStack 準備好之前被呼叫
                    handleDeepLink(url)
                }
        }
    }
    
    func handleDeepLink(_ url: URL) {
        // ⚠️ 如果 NavigationStack 尚未綁定,path.append 可能無效
        path.append(url.lastPathComponent)
    }
}

修正

// ✅ 正確 — 在 onAppear 或 NavigationStack 準備好後再處理深層連結
struct ContentView: View {
    @State private var path = NavigationPath()
    @State private var pendingDeepLink: URL? = nil

    var body: some View {
        NavigationStack(path: $path) {
            RootView()
                .onAppear {
                    // 現在 NavigationStack 已準備好
                    if let url = pendingDeepLink {
                        handleDeepLink(url)
                        pendingDeepLink = nil
                    }
                }
                .onOpenURL { url in
                    if path.count == 0 {
                        // NavigationStack 可能尚未準備好
                        pendingDeepLink = url
                    } else {
                        handleDeepLink(url)
                    }
                }
        }
    }
    
    func handleDeepLink(_ url: URL) {
        // 解析 URL 並導航
        DispatchQueue.main.async {
            path.append(url.lastPathComponent)
        }
    }
}

// ✅ 更穩健的做法 — 使用 process 旗標
struct ContentView: View {
    @State private var path = NavigationPath()
    @State private var isNavigationReady = false
    @State private var pendingDeepLink: URL? = nil

    var body: some View {
        NavigationStack(path: $path) {
            RootView()
                .onAppear {
                    // NavigationStack 現在可以用
                    isNavigationReady = true
                    processPendingLink()
                }
                .onOpenURL { url in
                    pendingDeepLink = url
                    processPendingLink()
                }
        }
    }
    
    func processPendingLink() {
        guard isNavigationReady, let url = pendingDeepLink else { return }
        handleDeepLink(url)
        pendingDeepLink = nil
    }
    
    func handleDeepLink(_ url: URL) {
        // 解析 URL 並推入路徑
        let pathComponent = DeepLinkParser.parse(url)
        path.append(pathComponent)
    }
}

驗證

  • 在 onOpenURL 和 path.append 加入 print — 確認順序正確
  • 冷啟動和熱啟動都測試
  • 使用 Thread.isMainThread 檢查主執行緒

模式 3b: 深層連結型別不符

時間成本 10-15 分鐘

症狀

  • 深層連結接收 URL 並嘗試導航,但顯示錯誤畫面
  • 路徑已更新,但 navigationDestination 未觸發
  • 控制台顯示 "No matching navigationDestination" 錯誤

診斷

// 檢查深層連結處理中附加的型別

// 假設你有以下目標
.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

// 深層連結處理
func handleDeepLink(_ url: URL) {
    // 從 URL 解析出字串
    let recipeID = url.lastPathComponent  // 字串
    
    // ❌ 錯誤 — 附加了 String,但目標註冊的是 Recipe
    path.append(recipeID)
}

修正

// ✅ 正確 — 透過 ID 查找正確型別並附加
func handleDeepLink(_ url: URL) {
    guard let recipeID = url.lastPathComponent else { return }
    
    // 查找對應的 Recipe 物件
    if let recipe = recipeRepository.findById(recipeID) {
        path.append(recipe)  // ✅ 型別一致
    }
}

// ✅ 或 — 統一型別(全部使用 String)
.navigationDestination(for: String.self) { id in
    RecipeDetailView(recipeID: id)
}

func handleDeepLink(_ url: URL) {
    let recipeID = url.lastPathComponent
    path.append(recipeID)  // ✅ 型別一致
}

驗證

  • 在 path.append 前印出 type(of: value)
  • 型別必須與 navigationDestination 註冊的型別完全一致

模式 4a: 分頁間共用 NavigationStack 狀態

時間成本 15-20 分鐘

症狀

  • 切換分頁時導航路徑遺失
  • 分頁 A 的導航影響分頁 B
  • 狀態在使用者返回分頁時重置

診斷

// ❌ 錯誤 — 在多個分頁間共用同一個 NavigationStack 和路徑
struct TabbedView: View {
    @State private var path = NavigationPath()  // 共用狀態

    var body: some View {
        TabView {
            NavigationStack(path: $path) {  // 共用路徑
                TabA()
            }
            .tabItem { Label("A", systemImage: "a.circle") }
            
            NavigationStack(path: $path) {  // 又是同一個路徑!
                TabB()
            }
            .tabItem { Label("B", systemImage: "b.circle") }
        }
    }
}

修正

// ✅ 正確 — 每個分頁有獨立的 NavigationStack 和路徑
struct TabbedView: View {
    @State private var tabAPath = NavigationPath()
    @State private var tabBPath = NavigationPath()

    var body: some View {
        TabView {
            NavigationStack(path: $tabAPath) {
                TabA()
            }
            .tabItem { Label("A", systemImage: "a.circle") }
            
            NavigationStack(path: $tabBPath) {
                TabB()
            }
            .tabItem { Label("B", systemImage: "b.circle") }
        }
    }
}

驗證

  • 切換分頁時,原有導航路徑保持不變
  • 分頁之間的導航互相獨立
  • 可以在一個分頁內進行多層導航,切到另一個分頁再回來,仍然保持

模式 5a: 路徑解碼崩潰

時間成本 15-20 分鐘

症狀

  • 應用程式從背景恢復時崩潰
  • 崩潰發生在 NavigationStack 恢復路徑時
  • 控制台出現 "Fatal error: Unexpectedly found nil" 或 "Decode failure"
  • 在 SceneStorage 或 StateRestoration 啟用時發生

診斷

// ❌ 錯誤 — 路徑中使用無法解碼的型別

// NavigationPath 會自動嘗試解碼其內容
// 如果你的型別沒有實作 Codable,恢復時會崩潰

struct Recipe: Identifiable, Hashable {
    let id: Int
    let name: String
    // ❌ 沒有 Codable
}

struct ContentView: View {
    @State private var path = NavigationPath()
    @State private var scenePath: NavigationPath?
    
    var body: some View {
        NavigationStack(path: $path) {
            RootView()
        }
        .sceneStorage("navPath") {  // ⚠️ 嘗試持久化
            // 如果 path 中的型別不能解碼,這裡會崩潰
        }
    }
}

修正

// ✅ 正確 — 確認型別實作 Codable
struct Recipe: Identifiable, Hashable, Codable {
    let id: Int
    let name: String
}

// ✅ 或 — 使用可以編碼的替代方案(如 String 或 Int)
struct ContentView: View {
    @SceneStorage("navPathData") private var navPathData: Data = Data()
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            RootView()
        }
        .onAppear {
            // 從 Data 恢復路徑
            if let decodedPath = try? JSONDecoder().decode(
                [String].self, from: navPathData
            ) {
                path = NavigationPath(decodedPath)
            }
        }
        .onChange(of: path) { _ in
            // 將路徑編碼為可儲存的資料
            // 注意:需要自訂封裝
        }
    }
}

驗证

  • 在解碼路徑時使用 do { try } catch { print("恢復崩潰") } 包裹
  • 所有加入路徑的型別都必須是 Codable
  • 測試應用程式從背景恢復多次

模式 6a: NavigationSplitView 欄位可見性問題

時間成本 10-15 分鐘

症狀

  • 在 iPad 上側邊欄預設隱藏
  • 使用者無法找到側邊欄
  • NavigationSplitView 在 iPhone 上顯示為單欄,但在 iPad 上顯示為多欄時側邊欄消失

診斷

// ❌ 錯誤 — 未設定 columnVisibility
NavigationSplitView {
    SidebarView()
} content: {
    ContentListView()
} detail: {
    DetailView()
}
// 在 iPad 上,側邊欄可能隱藏在 split view 控制項後面

修正

// ✅ 正確 — 使用 @State 控制 columnVisibility
struct ContentView: View {
    @State private var columnVisibility = NavigationSplitViewVisibility.all
    
    var body: some View {
        NavigationSplitView(columnVisibility: $columnVisibility) {
            SidebarView()
        } content: {
            ContentListView()
        } detail: {
            DetailView()
        }
        .onChange(of: columnVisibility) { oldValue, newValue in
            print("欄位可見性變更: \(oldValue) → \(newValue)")
        }
    }
}

驗證

  • 側邊欄預設可見
  • 使用者可以透過拖動或點擊切換側邊欄
  • 在 iPhone 上自動收合為單欄

模式 6b: NavigationSplitView 缺少預設詳細頁

時間成本 10-15 分鐘

症狀

  • 在 iPad 上啟動時顯示空白詳細頁
  • 側邊欄項目選取後才顯示內容
  • 使用者看到灰色或白色空白區域

診斷

// ❌ 錯誤 — 沒有為未選取狀態提供內容
struct DetailView: View {
    let item: Item?
    
    var body: some View {
        if let item = item {
            ItemDetail(item: item)
        }
        // 當 item 為 nil 時,顯示空白視圖
    }
}

修正

// ✅ 正確 — 為未選取狀態提供佔位內容
struct DetailView: View {
    let item: Item?
    
    var body: some View {
        if let item = item {
            ItemDetail(item: item)
        } else {
            ContentUnavailableView(
                "選取一個項目",
                systemImage: "sidebar.left",
                description: Text("從側邊欄選取一個項目以查看詳細資訊")
            )
        }
    }
}

驗證

  • 啟動時顯示有用的佔位內容,而非空白
  • 選取項目後平滑過渡到詳細內容
  • 取消選取時返回佔位內容

生產環境危機防禦

當你在生產環境中遇到導航問題時,以下策略可以幫助你快速恢復:

1. 加入防禦性紀錄

// 在 NavigationStack 的路徑變化中加入詳細紀錄
NavigationStack(path: $path) {
    RootView()
        .onChange(of: path.count) { _, _ in
            let timestamp = Date()
            print("[NAV] \(timestamp) 路徑長度: \(path.count)")
            
            if path.count > 10 {
                print("[NAV] ⚠️ 警告:路徑過長,可能無限推入")
            }
        }
}

2. 添加降級策略

// 如果導航失敗,提供返回根畫面或重置路徑的選項
struct ContentView: View {
    @State private var path = NavigationPath()
    @State private var navigationFailed = false
    
    var body: some View {
        NavigationStack(path: $path) {
            RootView()
                .toolbar {
                    if navigationFailed {
                        ToolbarItem(placement: .navigation) {
                            Button("重置導航") {
                                path = NavigationPath()
                                navigationFailed = false
                            }
                        }
                    }
                }
                .onChange(of: path) { _, _ in
                    // 偵測異常模式
                    if path.count > 20 {
                        navigationFailed = true
                    }
                }
        }
    }
}

3. 使用遠端設定控制導航行為

// 透過遠端設定切換導航實作
struct ContentView: View {
    @State private var path = NavigationPath()
    @AppStorage("useLegacyNavigation") private var useLegacyNavigation = false
    
    var body: some View {
        if useLegacyNavigation {
            LegacyNavigationView()
        } else {
            NavigationStack(path: $path) {
                RootView()
            }
        }
    }
}

4. 監控與警報

// 將導航錯誤報告到分析服務
.navigationDestination(for: Recipe.self) { recipe in
    let _ = TrackNavigation("RecipeDetail", recipe: recipe)
    RecipeDetail(recipe: recipe)
}

func TrackNavigation(_ screen: String, recipe: Recipe) {
    #if DEBUG
    print("[ANALYTICS] 導航到 \(screen): \(recipe.name)")
    #else
    // 發送到分析服務
    AnalyticsService.shared.track(screen: screen, data: ["recipeID": recipe.id])
    #endif
}

常見陷阱速查表

陷阱症狀解決方案
@State 放在子視圖導航狀態在視圖重建時遺失將 @State 移到穩定的父視圖
NavigationLink 在惰性容器內點擊無反應(未載入)將 navigationDestination 移到外部
型別不符navigationDestination 未觸發確保值型別與目標型別完全一致
在非 MainActor 上修改路徑間歇性導航失敗使用 @MainActor 或 DispatchQueue.main
共用 NavigationStack分頁間導航互相影響為每個分頁建立獨立的 NavigationStack
缺少 SceneStorage背景恢復後狀態遺失實作 SceneStorage 或自訂持久化
解碼失敗從背景恢復時崩潰確保所有路徑型別實作 Codable

結論

SwiftUI 的導航非常強大且可靠。當問題發生時,系統性地進行診斷是解決問題最快的方法。請記住:

  1. 80% 的問題 來自於 NavigationLink 在 NavigationStack 外部或 navigationDestination 在錯誤位置
  2. 10% 的問題 來自於狀態管理錯誤(@State 位置、路徑重建)
  3. 5% 的問題 來自於型別註冊或執行緒問題
  4. 只有不到 5% 是真正的 SwiftUI 框架缺陷

使用這個診斷工具,你可以快速識別問題類別,套用對應的模式,並在短時間內解決問題。

最後的建議:始終從最小化重現案例開始。如果無法在 10 行內重現問題,請回頭檢查你的實現。簡化問題往往是解決問題的最佳方法。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相關技能