Communitygithub.com

SwiftUI 除錯診斷

用於 SwiftUI 視圖除錯需要系統性調查時——基本故障排除後視圖更新仍無效、間歇性 UI 問題、複雜狀態依賴,或 Self._printChanges() 顯示非預期更新模式——結合 Instruments 整合的系統性診斷工作流程。

SwiftUI 除錯診斷 是什麼?

此技能提供了一套全面的 SwiftUI 視圖除錯診斷模式,專為開發者系統性調查複雜 UI 問題而設計。它涵蓋了從基礎的 `Self._printChanges()` 分析到進階的 `SwiftUI Instrument` 整合,幫助開發者診斷視圖未更新、過度更新、間歇性問題(即海森堡 bug)以及預覽崩潰等情況。技能明確禁止使用猜測性修改(如隨機更改 `@State` 或 `@Observable`)、強制刷新(如添加 `.id(UUID())`)或忽視根本原因的捷徑。它提供了一套強制性的初始化步驟,包括驗證 Xcode 版本、以 Release 模式建置,以及清理衍生資料,以確保除錯環境的正確性。該技能支援 macOS 和 iOS 平台(需要 Xcode 26+ 和 iOS 26+/macOS Tahoe+),並詳細說明了五大診斷模式:D1 用於分析 `_printChanges()` 輸出,D2 用於 Instruments 調查以追蹤資料流和效能瓶頸,D3 用於視圖身份調查以解決狀態重置或動畫問題,D4 用於環境依賴檢查以減少不必要的更新,以及 D5 用於 Xcode 26 預覽診斷。每個模式都包含清晰的步驟、常見案例、修復方案和驗證方法,確保開發者能找到根本原因,而非僅修復表面症狀。

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

在你喜歡的 AI 中提問

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

說明文件

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:視圖身份調查

常見發現:

  1. 非預期的 "@self changed"

    • 父層不必要地重建視圖
    • 檢查父層的狀態管理
  2. 屬性顯示已變更,但您並未變更它

    • 間接依賴(讀取了已變更的物件)
    • 模式 D2:使用 Instruments 追蹤
  3. 多個屬性同時變更

    • 廣泛的依賴(例如,讀取整個陣列但只需要一個項目)
    • 修正:萃取特定依賴

驗證:

  • 在提交前移除 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
  • 互動應如預期般運作

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

相關技能