SwiftUI 除錯診斷 是做什麼的?
何時使用此診斷技能
當以下情況發生時,請使用此技能:
- 基本故障排除失敗 — 已套用
axiom-swiftui-debugging技能模式,但問題仍然存在 Self._printChanges()顯示非預期模式 — 視圖在不該更新時更新,或在不該更新時未更新- 間歇性問題 — 有時正常,有時失敗(「海森堡 bug」)
- 複雜的依賴鏈 — 需要追蹤資料流經多個視圖/模型
- 效能調查 — 視圖更新過於頻繁或耗時過長
- 預覽之謎 — 原因不明的崩潰或失敗
禁止行為
在壓力下,您可能傾向於使用捷徑來隱藏問題,而不是診斷它們。切勿執行以下操作:
❌ 猜測性地隨機更改 @State/@Observable
- 「讓我試試在這裡加上 @Observable 看看是否有效」
- 「也許把它改成 @StateObject 就能解決」
❌ 添加 .id(UUID()) 強制更新
- 每次渲染都創造新的視圖身份
- 破壞狀態保留
- 掩蓋根本原因
❌ 在 @Observable 可用的情況下使用 ObservableObject(iOS 17+)
- 增加不必要的複雜性
- 失去自動依賴追蹤
❌ 忽略間歇性問題(「有時會正常」)
- 「我先合併,希望它不會在正式環境中發生」
- 間歇性 = 系統性錯誤,而非隨機性
❌ 在不了解原因的情況下交付
- 「修復有效,但我不知道為什麼」
- 正式環境不容許反覆嘗試
強制性初始步驟
在深入診斷模式之前,請先建立基準環境:
# 1. 驗證 Instruments 設定
xcodebuild -version # 必須為 Xcode 26+ 才能使用 SwiftUI Instrument
# 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 # Environment 是 @self 的一部分
→ 環境值已變更(色彩配置、語言代碼、自訂值)
→ 模式 D4:檢查環境依賴
# 情境 4:無任何記錄
→ body 未被呼叫
→ 模式 D3:視圖身份調查
常見發現:
-
非預期的 "@self changed"
- 父層不必要地重建視圖
- 檢查父層的狀態管理
-
屬性顯示已變更,但您並未變更它
- 間接依賴(讀取了已變更的物件)
- 模式 D2:使用 Instruments 追蹤
-
多個屬性同時變更
- 廣泛的依賴(例如,讀取整個陣列但只需要一個項目)
- 修正:萃取特定依賴
驗證:
- 在提交前移除
Self._printChanges()呼叫 - 絕不能將此程式碼交付至正式環境
交叉參考:對於複雜案例,請使用模式 D2(SwiftUI Instrument)
模式 D2:SwiftUI Instrument 調查
時間成本:25 分鐘
症狀:Self._printChanges() 無法完全解釋的複雜更新模式
何時使用:
- 多個視圖在應該只有一個更新時更新
- 需要追蹤資料在應用程式中的流向
- 視圖正在更新,但不知道是哪個資料觸發的
- 視圖 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 分鐘)
- 點擊「記錄」按鈕
- 執行觸發非預期更新的操作
- 停止記錄(10-30 秒的互動即足夠)
3. 分析長時間的視圖 Body 更新(5 分鐘)
- 查看「長時間視圖 Body 更新」行
- 是否有橘色/紅色長條?那些是耗資源的視圖
- 點擊一個長時間更新 → 詳細資訊窗格會顯示視圖名稱
- 右鍵點擊 → 「設定檢查範圍並縮放」
- 切換到「Time Profiler」軌道
- 在呼叫堆疊中找到您的視圖
- 識別耗資源的操作(格式化程序建立、計算等)
修正:將耗資源的操作移至模型層,快取結果
4. 分析不必要的更新(7 分鐘)
- 反白顯示使用者操作的時間範圍(例如,點擊收藏按鈕)
- 在詳細資訊窗格中展開層級結構
- 計算更新次數 — 超出預期?
- 將滑鼠懸停在視圖上 → 點擊箭頭 → 「顯示因果關係圖」
5. 解讀因果關係圖(5 分鐘)
圖形節點:
[藍色節點] = 您的程式碼(手勢、狀態變更、視圖 body)
[系統節點] = SwiftUI/系統工作
[箭頭標示 "update"] = 導致此次更新
[箭頭標示 "creation"] = 導致視圖出現
常見模式:
# 模式 A:單一視圖更新(良好)
[Gesture] → [ViewModelA 中的狀態變更] → [ViewA body]
# 模式 B:所有視圖更新(不良 - 廣泛依賴)
[Gesture] → [陣列變更] → [所有列表項目視圖更新]
└─ 修正:使用細粒度的視圖模型,每個項目一個
# 模式 C:透過環境串聯(需檢查)
[狀態變更] → [環境寫入] → [許多視圖 body 檢查]
└─ 若環境值頻繁變更 → 模式 D4 修正
點擊節點:
- 狀態變更節點 → 查看設定值的回溯
- 視圖 body 節點 → 查看它讀取了哪些屬性(依賴)
驗證:
- 在修復後記錄新的軌跡
- 比較修復前後的更新次數
- 驗證橘色/紅色長條已減少或消除
交叉參考:請參考 axiom-swiftui-performance 技能以獲得詳細的 Instruments 工作流程
模式 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)") // ID 隨 isEditing 變更
// ✅ 修正:穩定的 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 分鐘
症狀:許多視圖在不相關的資料變更時更新
何時使用:
- 因果關係圖顯示「環境」節點觸發了許多更新
- 捲動或動畫效能緩慢
- 非預期的串聯更新
根本原因:環境中的值頻繁變更,或者太多視圖讀取環境
調查步驟:
1. 尋找環境寫入(3 分鐘)
# 在目前專案中搜尋環境修飾詞
grep -r "\.environment(" --include="*.swift" .
尋找:
// ❌ 不良:頻繁變更的值
.environment(\.scrollOffset, scrollOffset) // 每秒更新 60+ 次
.environment(model) // 如果模型頻繁更新
// ✅ 良好:穩定的值
.environment(\.colorScheme, .dark)
.environment(appModel) // 如果 appModel 很少變更
2. 檢查環境中的內容(3 分鐘)
使用模式 D2(Instruments),檢查因果關係圖:
- 點擊「環境」節點
- 查看哪些屬性已變更
- 計算有多少視圖檢查了更新
問題:
- 此值是否在每次捲動/動畫幀時變更?
- 所有這些視圖是否真的需要此值?
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 分鐘)
位置:編輯器選單 → 畫布 → 診斷
顯示內容:
- 詳細的錯誤訊息
- 缺少的依賴
- 狀態初始化問題
- 預覽特定的問題
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)
}
// 無效的狀態初始化
#Preview {
// ❌ 假設 EditMode 預設為 0,但 0 無效
// ✅ 使用有效的初始值
EditItemView(item: Item(name: "Sample"))
}
// 缺少導航環境
#Preview {
NavigationStack {
ContentView()
}
}
驗證:
- 預覽應成功載入
- 應顯示預期的 UI
- 互動應如預期般運作