Communitygithub.com

ComeOnOliver/skillshub

用于 SwiftUI 视图调试需要系统性调查时——基本故障排除后视图更新仍不正常、间歇性 UI 问题、复杂状态依赖,或 Self._printChanges() 显示意外更新模式——提供系统化诊断工作流及 Instruments 集成。

skillshub 是什么?

此 AI 技能为 SwiftUI 开发者提供系统化的视图调试诊断工作流,适用于基本故障排除无效、间歇性 “heisenbug” 问题、复杂依赖链追踪及性能调优场景。技能基于五大诊断模式:Pattern D1 通过 Self._printChanges() 分析视图更新根因;Pattern D2 利用 Xcode 26+ 的 SwiftUI 仪器(Instruments)进行因果图追踪;Pattern D3 调查视图标识(identity)意外变化导致的 @State 重置或动画失败;Pattern D4 检查环境(Environment)依赖导致的级联更新;Pattern D5 处理 Xcode 预览崩溃。技能明确禁止猜测式状态类型切换、滥用 .id(UUID()) 强制刷新、忽略间歇性问题等有害行为,并强调在 Release 模式下采集基线数据,确保诊断准确。适用于所有主流 SwiftUI 开发平台(iOS/macOS),开发者可遵循决策树快速定位问题模式。

兼容平台~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() 显示意外模式 —— 视图不该更新时却在更新,或者应该更新时却没有更新
  • 间歇性问题 —— 有时正常,有时失败(“heisenbug”)
  • 复杂依赖链 —— 需要追踪通过多个视图/模型的数据流
  • 性能调查 —— 视图更新过于频繁或耗时过长
  • 预览谜团 —— 立即原因不明的崩溃或失败

禁止操作

在压力下,你可能会倾向于走捷径来掩盖问题而不是进行诊断。绝不要做以下事情:

❌ 胡乱猜测 @State/@Observable 变更

  • “让我试试在这里添加 @Observable 看行不行”
  • “也许改成 @StateObject 就能修复”

❌ 添加 .id(UUID()) 强制更新

  • 每次渲染都会创建新的视图标识
  • 破坏状态保留
  • 掩盖根本原因

❌ 当 @Observable (iOS 17+) 可用时使用 ObservableObject

  • 增加不必要的复杂性
  • 错过自动依赖追踪

❌ 忽略间歇性问题(“有时有效”)

  • “我就合并了,希望生产环境不会出现”
  • 间歇 = 系统性 bug,不是随机性

❌ 不理解就提交

  • “修复能工作,但不知道为什么”
  • 生产环境不适合试错

强制第一步

在深入诊断模式之前,先建立基线环境:

# 1. 验证 Instruments 设置
xcodebuild -version  # 必须为 Xcode 26+ 以支持 SwiftUI Instrument

# 2. 以 Release 模式构建用于分析
xcodebuild build -scheme YourScheme -configuration Release

# 3. 如果调查预览问题,清除 Derived Data
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 分钟)

  • 查看 Long View Body Updates 轨道
  • 有橙色/红色条?那些是开销大的视图
  • 点击长更新 → 详情面板显示视图名称
  • 右键 → “Set Inspection Range and Zoom”
  • 切换到 Time Profiler 轨道
  • 在调用栈中找到你的视图
  • 识别开销大的操作(格式化器创建、计算等)

修复:将开销大的操作移至模型层,缓存结果

4. 分析不必要的更新(7 分钟)

  • 高亮用户操作的时间范围(例如,点击收藏按钮)
  • 在详情面板中展开层次结构
  • 计算更新次数 —— 是否超出预期?
  • 悬停在视图 → 点击箭头 → “Show Cause & Effect Graph”

5. 解释因果图(5 分钟)

图节点:

[蓝色节点] = 你的代码(手势、状态变更、视图 body)
[系统节点] = SwiftUI/系统工作
[标记为 “update” 的箭头] = 造成这次更新
[标记为 “creation” 的箭头] = 导致视图出现

常见模式:

# 模式 A:单个视图更新(良好)
[Gesture] → [State Change in ViewModelA] → [ViewA body]

# 模式 B:所有视图更新(不良 – 宽泛依赖)
[Gesture] → [Array change] → [All list item views update]
└─ 修复:使用细粒度视图模型,每个项目一个

# 模式 C:通过环境级联(需检查)
[State Change] → [Environment write] → [Many view bodies check]
└─ 如果环境值频繁变化 → 模式 D4 修复

点击节点:

  • 状态变更节点 → 查看值被设置的回溯
  • 视图 body 节点 → 查看它读取了哪些属性(依赖)

验证:

  • 修复后录制新跟踪
  • 对比前后更新次数
  • 验证红色/橙色条已减少或消除

交叉引用:详细 Instruments 工作流见 axiom-swiftui-performance 技能


模式 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 分钟

症状:不相关数据变化时许多视图更新

何时使用:

  • 因果图显示 “Environment” 节点触发大量更新
  • 滚动或动画性能缓慢
  • 非预期级联更新

根本原因:环境中频繁变化的值 或 过多视图读取环境

调查步骤:

1. 查找环境写入点(3 分钟)

# 在当前项目中搜索环境修饰符
grep -r "\.environment(" --include="*.swift" .

查找:

// ❌ 不良:频繁变化的值
.environment(\.scrollOffset, scrollOffset)  // 每秒更新 60+ 次
.environment(model)  // 如果模型频繁更新

// ✅ 良好:稳定的值
.environment(\.colorScheme, .dark)
.environment(appModel)  // 如果 appModel 很少变化

2. 检查环境中包含什么(3 分钟)

使用模式 D2(Instruments),检查因果图:

  • 点击 “Environment” 节点
  • 查看哪些属性发生了变化
  • 统计多少视图检查了更新

问题:

  • 这个值是否随着每次滚动/动画帧的变化而变化?
  • 所有这些视图真的需要这个值吗?

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 分钟)

位置:Editor 菜单 → Canvas → Diagnostics

显示内容:

  • 详细的错误消息
  • 缺少的依赖
  • 状态初始化问题
  • 预览特定问题

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)
}

验证:

  • 预览现在应该加载
  • 使用预览交互测试依赖
  • 确认无崩溃或警告

高级参考

避免观感级联更新(Performance Anti-Pattern)

State Change → Compute heavy property (e.g., filtered list) → Multiple views

解决方案:

  • 使用 @Observable 属性来注册依赖
  • 使用 @State 进行计算并缓存
  • 使用 .onChange(of:) 监听特定变化

混合 @Observable / ObservableObject 血泪史

  • 不要混用 iOS 17 前和 iOS 17+ 的观察机制
  • 选择并在整个视图层级中保持一致
  • 混合会增加复杂性并可能导致隐藏的竞争条件

依赖注入最小化

  • 尽量传递具体值而非整个对象(例如,Text("\(model.name)") 而不是在视图中存储 model)
  • 减少对象被传递的场景数量

错误决策清单

在生产环境中,不要为上述模式浪费时间 – 使用决策树。但如果你不确定从哪里开始,问自己以下问题:

  1. 是持续失败还是间歇性失败?

    • 持续 → 模式 D1 或 D3
    • 间歇 → 模式 D2 或 D4
  2. 视图更新过于频繁还是太少?

    • 过多 → 模式 D1/模式 D2
    • 不足 → 模式 D1/模式 D3
  3. 是否使用了环境值?

    • 是的,频繁变化 → 模式 D4
  4. 预览崩溃或无法加载?

    • 是的 → 模式 D5

版本兼容性

功能最低 Xcode最低 OS备注
Self._printChanges()Xcode 15iOS 17 / macOS 14所有模式下可用
SwiftUI InstrumentXcode 26iOS 26 / macOS Tahoe必须 Release 构建
预览诊断Xcode 26不适用仅 Xcode
@ObservableXcode 15iOS 17 / macOS 14推荐的观察机制

注意:对于 iOS 16 及更早版本,使用 @StateObject / @ObservedObject 替代 @Observable

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

相关技能