Communitygithub.com

ComeOnOliver/skillshub

用于调试 SwiftUI 视图更新、预览崩溃或布局问题 —— 提供诊断决策树,快速定位根因,避免在压力下误判。

skillshub 是什么?

该技能旨在帮助开发者快速诊断和解决 SwiftUI 开发中的三类常见问题:视图不更新、预览崩溃和布局异常。它提供结构化的决策树,引导用户系统性地排除原因,而不是盲目猜测。技能覆盖了从 Xcode 缓存损坏到 struct 突变、绑定身份丢失、意外的视图重建以及缺失的观察者模式等具体场景。它明确支持 iOS 17+ 及 Xcode 26+,同时保留了针对旧版 iOS 的兼容性注释。文档提供了大量可运行的代码示例,包括错误的和正确的写法,并推荐了相关的辅助技能(如 `axiom-xcode-debugging` 用于缓存诊断,`axiom-swift-concurrency` 用于并发模式)。核心工具介绍包括 `Self._printChanges()` 的 LLDB 使用方法,强调其调试专用性质,并警告切勿在生产代码中使用。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

SwiftUI 调试

概述

SwiftUI 调试分为三类,每类都有不同的诊断方法:

  1. 视图未更新 – 你修改了某些内容,但视图未重新绘制。决策树用于识别问题根源:结构体突变、绑定身份丢失、意外的视图重建还是缺失的观察者模式。
  2. 预览崩溃 – 预览无法编译或立即崩溃。决策树用于区分:缺少依赖项、状态初始化失败和 Xcode 缓存损坏。
  3. 布局问题 – 视图出现在错误的位置、尺寸错误或意外重叠。提供常见场景的快速参考模式。

核心原则:从可观察的症状开始,系统地测试,逐一排除原因。不要猜测。

环境要求: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 未被调用;视图根本没有更新

⚠️ 重要:

  • 前缀为下划线 → 可能在未来的版本中被移除
  • 绝对不要提交到 App Store 的 _printChanges 调用
  • 性能影响 → 仅在调试期间使用

何时使用:

  • 需要了解视图更新的确切触发器
  • 调查意外的更新
  • 重构后验证依赖关系

交叉参考:对于复杂的更新模式,请使用 SwiftUI Instrument → 参见 axiom-swiftui-performance 技能


视图未更新决策树

最常见的挫败感:你更改了 @State 但视图没有重绘。根因总是以下四种之一。

步骤 1:你能在最小预览中复现吗?

#Preview {
  YourView()
}

是 → 问题出在你的代码中。继续步骤 2。

否 → 很可能是 Xcode 状态或缓存损坏。跳转到预览崩溃章节。

步骤 2:诊断根因

根因 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("Name", text: Binding(
    get: { name },
    set: { name = $0 }
))  // 每次父视图渲染时都是新的绑定对象

// ✅ 正确:传递实际的绑定
@State var isOn = false

ToggleChild(value: $isOn)

// ✅ 正确(iOS 17+):对 @Observable 对象使用 @Bindable
@Observable class Book {
    var title = "Sample"
    var isAvailable = true
}

struct EditView: View {
    @Bindable var book: Book  // 启用 $book.title 语法

    var body: some View {
        TextField("Title", text: $book.title)
        Toggle("Available", 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("Title", 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("Name", 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("Toggle") {
            showCounter.toggle()
        }
    }
}

// Counter 被重建,@State count 重置为 0

// ✅ 正确:使用 opacity 或 hidden 保持身份
@State var count = 0

var body: some View {
    VStack {
        Counter()
            .opacity(showCounter ? 1 : 0)
        Button("Toggle") {
            showCounter.toggle()
        }
    }
}

// ✅ 也正确:如果必须有条件显示,使用 id()
@State var count = 0

var body: some View {
    VStack {
        if showCounter {
            Counter()
                .id("counter")  // 稳定的身份
        }
        Button("Toggle") {
            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("Increment") {
            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("Increment") {
            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("Increment") {
            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:错误是什么?

错误类型 1:"Cannot find in scope" 或 "No such module"

根因:预览缺少必需的依赖项(@EnvironmentObject、@Environment、导入的模块)。

// ❌ 错误:ContentView 需要一个模型,预览没有提供
struct ContentView: View {
    @EnvironmentObject var model: AppModel

    var body: some View {
        Text(model.title)
    }
}

#Preview {
    ContentView()  // 崩溃:找不到模型
}

// ✅ 正确:提供依赖项
#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("无数据")
        }
    }
}

修复方法:在初始化过程中使用安全默认值和边界检查。


错误类型 3:预览在重新构建后挂起或崩溃(之前正常)

根因:可能是 Xcode 缓存或 DerivedData 损坏。

修复方法:

  1. Product → Clean Build Folder
  2. 退出并重新打开 Xcode
  3. xcodebuild -showBuildSettings(在终端中验证配置)
  4. 如果以上都无效,删除 DerivedData:rm -rf ~/Library/Developer/Xcode/DerivedData

替代方案:使用 axiom-xcode-debugging 技能进行更彻底的诊断。


布局问题快速参考

SwiftUI 布局问题通常属于标准类别。在深入调试之前,检查这些内容。

1. 视图超出屏幕

检查:你是否在滚动容器、VStack/HStack 或 ZStack 上设置了无限宽度/高度?

修复:使用 .frame(maxWidth: .infinity) 指定所需的最大宽度。

2. 视图重叠

检查:你是否在 ZStack 之外使用了 .offset()?偏移量不会影响布局。

修复:使用 Spacer() 或 .padding() 调整位置。

3. 文本截断

检查:Text 视图是否没有足够的空间?

修复:使用 .fixedSize(horizontal: false, vertical: true) 允许垂直增长。

4. 设备适配

检查:布局是否在特定设备上损坏?

修复:使用 GeometryReader 获取可用空间。

仪表

症状最可能的根因快速修复
更改 @State 后视图不更新结构体突变重新赋值整个值
子视图不反映更改绑定身份丢失传递 $state 或使用 @Bindable
视图重置为初始状态意外的视图重建使用 .opacity() 或 .id()
对象更改后视图不更新缺失观察者使用 @Observable(iOS 17+)
预览崩溃:找不到模型缺失 @EnvironmentObject在预览中提供模型
预览崩溃:索引越界状态初始化失败使用安全默认值

进一步学习

  • axiom-swiftui-layout:自适应布局模式
  • axiom-xcode-debugging:Xcode 缓存和运行时崩溃诊断
  • axiom-swiftui-performance:使用 Instruments 进行性能分析
  • SwiftUI 布局指南
  • 管理模型数据

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

相关技能