SwiftUI 除錯 是做什麼的?
概述
SwiftUI 除錯主要分為三大類,每類都有不同的診斷方法:
- 檢視未更新 – 你修改了某些東西,但檢視沒有重新繪製。決策樹可幫助判斷是否是結構體突變、綁定身份遺失、意外檢視重建或遺漏觀察者模式。
- 預覽崩潰 – 你的預覽無法編譯或立即崩潰。決策樹可區分是遺漏依賴項、狀態初始化失敗或 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 沒有被呼叫;檢視完全沒有更新
⚠️ 重要事項:
- 前綴底線 → 可能在未來版本中被移除
- 絕對不要將 _printChanges 提交到 App Store
- 會影響效能 → 僅在除錯時使用
何時使用:
- 需要了解檢視更新的確切觸發原因
- 調查非預期的更新
- 重構後驗證相依關係
交叉參考:對於複雜的更新模式,請使用 SwiftUI 分析工具 → 參閱 axiom-swiftui-performance 技能
檢視未更新決策樹
最常見的困擾:你更改了 @State,但檢視沒有重新繪製。根本原因總是以下四種之一。
第一步:能否在最小預覽中重現問題?
#Preview {
YourView()
}
可以 → 問題在你的程式碼中。繼續第二步。
不可以 → 很可能是 Xcode 狀態或快取損毀。跳到預覽崩潰區段。
第二步:診斷根本原因
根本原因 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("名字", text: Binding(
get: { name },
set: { name = $0 }
)) // 每次父檢視渲染都會產生新的綁定物件
// ✅ 正確:傳遞實際的綁定
@State var isOn = false
ToggleChild(value: $isOn)
// ✅ 正確 (iOS 17+):對 @Observable 物件使用 @Bindable
@Observable class Book {
var title = "範例"
var isAvailable = true
}
struct EditView: View {
@Bindable var book: Book // 啟用 $book.title 語法
var body: some View {
TextField("標題", text: $book.title)
Toggle("可借出", 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("標題", 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("名字", text: nameBinding!)
}
修復方式:盡可能直接傳遞 $state。對於 @Observable 物件(iOS 17+),使用 @Bindable。如果需要建立自訂綁定(iOS 17 之前),請在 init 中建立或快取起來,不要在 body 中建立。
根本原因 3:意外檢視重建
症狀:檢視更新了,但 @State 值重設為初始狀態。你會看到初始值的短暫閃爍。
原因:檢視獲得了新身份(從條件判斷中被移除、在容器中移動、或容器本身被重建),導致 SwiftUI 將其視為新檢視。
// ❌ 錯誤:條件翻轉時檢視身份變更
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter() // 每次 showCounter 變更時獲得新身份
}
Button("切換") {
showCounter.toggle()
}
}
}
// Counter 被重建,@State count 重設為 0
// ✅ 正確:使用 opacity 或 hidden 保留身份
@State var count = 0
var body: some View {
VStack {
Counter()
.opacity(showCounter ? 1 : 0)
Button("切換") {
showCounter.toggle()
}
}
}
// ✅ 也正確:如果必須條件顯示,使用 id()
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter()
.id("counter") // 穩定的身份
}
Button("切換") {
showCounter.toggle()
}
}
}
修復方式:使用 .opacity() 取代條件判斷來保留檢視身份,或使用 .id() 並提供穩定的識別碼。
根本原因 4:遺漏觀察者模式
症狀:物件改變了,但觀察該物件的檢視沒有更新。
原因:SwiftUI 不知道要監視該物件的變更。
// ❌ 錯誤:屬性變更不會觸發更新
class Model {
var count = 0 // 不可觀察
}
struct ContentView: View {
let model = Model() // 每次渲染都是新實例,不可觀察
var body: some View {
Text("\(model.count)")
Button("增加") {
model.count += 1 // 檢視不更新
}
}
}
// ✅ 正確 (iOS 17+):使用 @Observable 搭配 @State
@Observable class Model {
var count = 0 // 不需要 @Published
}
struct ContentView: View {
@State private var model = Model() // 使用 @State,不是 @StateObject
var body: some View {
Text("\(model.count)")
Button("增加") {
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("增加") {
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包裝器 - 可以使用
@State替代@StateObject - 可以作為純屬性傳遞,而不是
@ObservedObject
另請參閱:管理應用程式中的模型資料
決策樹摘要
digraph view_not_updating {
start [label="檢視未更新?" shape=diamond];
reproduce [label="可以在預覽中重現嗎?" shape=diamond];
cause [label="什麼改變了?" shape=diamond];
start -> reproduce;
reproduce -> cause [label="可以:程式碼錯誤"];
reproduce -> "快取/Xcode 狀態 → 預覽崩潰" [label="不可以"];
cause -> "結構體突變" [label="直接修改了結構體"];
cause -> "綁定身份遺失" [label="傳遞了綁定給子檢視"];
cause -> "意外重建" [label="檢視在條件判斷內"];
cause -> "遺漏觀察者" [label="物件改變,檢視沒變"];
}
預覽崩潰決策樹
當你的預覽無法載入或立即崩潰時,三個根本原因各有不同。
第一步:錯誤訊息是什麼?
錯誤類型 1:「Cannot find in scope」或「No such module」
根本原因:預覽缺少必要的依賴項(@EnvironmentObject、@Environment、導入的模組)。
// ❌ 錯誤:ContentView 需要一個 model,預覽沒有提供
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("無資料")
}
}
}
修復方式:檢查所有強制解開的運算子、強制轉換和陣列索引。確保初始狀態值是有效的。
診斷工具:
// 暫時將強制解開換成 guard
// ❌ 現在:
Text(data!.title)
// ✅ 暫時改為:
if let data = data {
Text(data.title)
} else {
Text("data 為 nil,請檢查初始化")
// 設定中斷點
}
// 或是對表達式設定例外中斷點
// Xcode → 中斷點導覽器 → + → 例外中斷點
// 選擇「Objective-C」與「所有例外」
錯誤類型 3:Xcode 快取損毀
根本原因:Xcode 的衍生資料或預覽快取已毀損。
症狀:
- 預覽顯示「無法建立預覽器」
- 清理建置資料夾後問題解決,但幾分鐘後又回來
- 多個預覽以同樣方式失敗
修復方式:
# 步驟 1:清理建置資料夾
# Xcode → Product → Clean Build Folder (按住 Option)
# 步驟 2:刪除衍生資料
rm -rf ~/Library/Developer/Xcode/DerivedData
# 步驟 3:重設預覽快取
# Xcode → Preferences → Platforms → 點擊你的裝置 → Reset Simulator
# 步驟 4:Xcode 版本 15 以上的特定修復
# 刪除特定於專案的快取
rm -rf ~/Library/Caches/com.apple.dt.Xcode
在執行時重新整理預覽:
- 點擊預覽畫布上的「重新整理」按鈕
- 或者,如果選單中有,選擇「Editor → Canvas → Refresh All Previews」
- 如果持續存在,重新啟動 Xcode
預覽崩潰摘要
預覽崩潰?
│
├─ 錯誤:「Cannot find...」或「No such module」
│ └─ 修復:檢查遺漏的 .environmentObject()、.environment() 或匯入
│
├─ 致命錯誤或無訊息崩潰
│ └─ 修復:檢查索引、強制解開、以及無效的初始狀態
│
└─ 無法建立預覽器 / 僅在 Xcode 中崩潰
└─ 修復:清除衍生資料、重設預覽快取、重新啟動 Xcode
常見佈局問題快速參考
問題 1:檢視重疊或位於錯誤的位置
// ❌ 錯誤:忽略安全區域
var body: some View {
VStack {
ForEach(items) { item in
Text(item.name)
}
}
.frame(maxWidth: .infinity, maxHeight: .infinity)
.background(Color.blue) // 邊緣可能超出
}
// ✅ 正確:尊重安全區域
var body: some View {
VStack {
ForEach(items) { item in
Text(item.name)
}
}
.frame(maxWidth: .infinity, maxHeight: .infinity)
.background(Color.blue)
.ignoresSafeArea(.container) // 如果需要延伸到邊緣
}
問題 2:不同裝置上大小不一致
// ❌ 錯誤:硬編碼尺寸
var body: some View {
Image("logo")
.frame(width: 100, height: 50) // 小螢幕上太大,大螢幕上太小
}
// ✅ 正確:使用相對尺寸
var body: some View {
GeometryReader { geometry in
Image("logo")
.frame(width: geometry.size.width * 0.8, height: 50)
}
}
問題 3:ForEach 中的動態長度文字被截斷
// ❌ 錯誤:沒有指定行數限制
var body: some View {
List(items) { item in
Text(item.longDescription) // 可能會被截斷或換行
}
}
// ✅ 正確:明確指定行數
var body: some View {
List(items) { item in
Text(item.longDescription)
.lineLimit(3) // 最多 3 行
}
}
進階除錯技巧
技巧 1:在 body 中追蹤狀態變更
struct ContentView: View {
@State private var count = 0
var body: some View {
// 會列印每次 body 被呼叫的原因
let _ = Self._printChanges()
VStack {
Text("計數器:\(count)")
Button("增加") {
count += 1
}
}
}
}
技巧 2:在預覽中使用不同裝置
#Preview("iPhone SE") {
ContentView()
.previewDevice("iPhone SE (3rd generation)")
}
#Preview("iPad Pro 12.9\"") {
ContentView()
.previewDevice("iPad Pro (12.9-inch) (6th generation)")
}
技巧 3:檢查佈局幾何
struct ContentView: View {
var body: some View {
GeometryReader { geometry in
VStack {
Text("寬度:\(geometry.size.width)")
Text("高度:\(geometry.size.height)")
Text("安全區域頂部:\(geometry.safeAreaInsets.top)")
}
}
}
}
常見陷阱
陷阱 1:在 body 中建立新的 ObservableObject
// ❌ 錯誤:每次渲染都建立新實例
struct ContentView: View {
var body: some View {
MyView(model: MyObservableObject()) // 新實例,狀態遺失
}
}
// ✅ 正確:在外部建立並保留
struct ContentView: View {
@StateObject private var model = MyObservableObject()
var body: some View {
MyView(model: model) // 同一個實例,狀態保留
}
}
陷阱 2:忘記 @Published 或 @Observable
// ❌ 錯誤:不會觸發更新
class ViewModel: ObservableObject {
var count = 0 // 缺少 @Published
}
// ✅ 正確:使用 @Published
class ViewModel: ObservableObject {
@Published var count = 0
}
陷阱 3:在 body 中使用計算屬性建立 Binding
// ❌ 錯誤:每次渲染都建立新 Binding
@State private var name = ""
var body: some View {
TextField("名字", text: Binding(
get: { name },
set: { name = $0 }
))
// 每次渲染都建立新綁定,可能導致更新問題
}
// ✅ 正確:在 init 中建立
@State private var name = ""
@State private var nameBinding: Binding<String>?
init() {
_nameBinding = State(initialValue: Binding(
get: { [name] in name.wrappedValue },
set: { name = $0 }
))
}
總結
SwiftUI 除錯不需要靠猜測。透過此決策樹:
- 檢視未更新:檢查結構體突變、綁定身份、檢視重建、觀察者模式
- 預覽崩潰:檢查遺漏的依賴項、無效的狀態、Xcode 快取
- 佈局問題:使用 GeometryReader、相對尺寸、lineLimit
記住核心工具:Self._printChanges() 用於檢視更新,GeometryReader 用於佈局,而乾淨的預覽是最快的診斷方法。
請參閱 axiom-xcode-debugging、axiom-swift-concurrency、axiom-swiftui-performance 及 axiom-swiftui-layout 以獲取更專業的除錯協助。