SwiftUI 디버깅 진단
이 진단 스킬을 사용해야 하는 경우
다음 상황에서 이 스킬을 사용하세요:
- 기본 문제 해결 실패 —
axiom-swiftui-debugging스킬 패턴을 적용했지만 문제가 지속됨 - Self._printChanges()가 예상치 못한 패턴을 보임 — 뷰가 업데이트되어서는 안 될 때 업데이트되거나, 업데이트되어야 할 때 업데이트되지 않음
- 간헐적 문제 — 어떤 때는 작동하고 어떤 때는 실패함 (하이젠버그)
- 복잡한 의존성 체인 — 여러 뷰/모델을 통해 데이터 흐름을 추적해야 함
- 성능 조사 — 뷰가 너무 자주 업데이트되거나 시간이 너무 오래 걸림
- 프리뷰 미스터리 — 명확하지 않은 충돌 또는 실패
금지된 행동
압박을 받으면 문제를 진단하는 대신 숨기는 지름길을 사용하고 싶은 유혹을 느낄 수 있습니다. 절대 하지 마세요:
❌ 무작위 @State/@Observable 변경으로 추측하기
- "여기에 @Observable을 추가해보고 작동하는지 봅시다"
- "이걸 @StateObject로 바꾸면 고쳐질 수도 있어요"
❌ 강제 업데이트를 위해 .id(UUID()) 추가하기
- 매 렌더링마다 새로운 뷰 정체성을 생성함
- 상태 보존을 파괴함
- 근본 원인을 가림
❌ @Observable로 충분한데 ObservableObject 사용하기 (iOS 17+)
- 불필요한 복잡성 추가
- 자동 의존성 추적을 놓침
❌ 간헐적 문제 무시하기 ("가끔 작동해요")
- "그냥 머지하고 프로덕션에 문제 없길 바라자"
- 간헐적 = 무작위가 아닌 체계적인 버그
❌ 이해하지 않고 배포하기
- "수정은 됐는데, 왜 되는지 모르겠어요"
- 프로덕션은 시행착오를 하기에는 너무 비용이 큼
필수 첫 단계
진단 패턴을 시작하기 전에 기본 환경을 설정하세요:
# 1. Instruments 설정 확인
xcodebuild -version # SwiftUI Instrument를 위해 Xcode 26+ 필수
# 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 → Cause & Effect 그래프
│ └─ 데이터 흐름 추적, 광범위한 의존성 찾기
│
├─ 간헐적 문제 (가끔 작동함)?
│ ├─ 패턴 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)")
Text("모델 값: \(model.value)")
}
}
}
출력 해석:
# 시나리오 1: 뷰 매개변수 변경됨
MyView: @self changed
→ 부모가 새 MyView 인스턴스를 전달함
→ 부모 코드 확인 - 무엇이 재생성을 트리거했는가?
# 시나리오 2: 상태 속성 변경됨
MyView: count changed
→ 로컬 @State가 업데이트를 트리거함
→ count를 수정했다면 예상된 동작
# 시나리오 3: 환경 속성 변경됨
MyView: @self changed # 환경은 @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분)
# 릴리스 빌드
xcodebuild build -scheme YourScheme -configuration Release
# Instruments 실행
# Xcode에서 Command-I 누르기
# "SwiftUI" 템플릿 선택
2. 트레이스 기록 (3분)
- Record 버튼 클릭
- 예상치 못한 업데이트를 유발하는 작업 수행
- 기록 중지 (10-30초 상호작용이면 충분)
3. 긴 뷰 Body 업데이트 분석 (5분)
- Long View Body Updates 레인 확인
- 주황색/빨간색 막대가 있나요? 그게 비용이 많이 드는 뷰입니다
- 긴 업데이트 클릭 → 세부 정보 창에 뷰 이름 표시
- 우클릭 → "Set Inspection Range and Zoom" 선택
- Time Profiler 트랙으로 전환
- 호출 스택에서 뷰 찾기
- 비용이 많이 드는 작업 식별 (포맷터 생성, 계산 등)
수정: 비용이 많이 드는 작업을 모델 계층으로 이동, 결과 캐싱
4. 불필요한 업데이트 분석 (7분)
- 사용자 작업 시간 범위 강조 (예: 즐겨찾기 버튼 탭)
- 세부 정보 창에서 계층 확장
- 업데이트 수 계산 — 예상보다 많습니까?
- 뷰 위로 마우스 hover → 화살표 클릭 → "Show Cause & Effect Graph" 선택
5. Cause & Effect 그래프 해석 (5분)
그래프 노드:
[파란색 노드] = 사용자 코드 (제스처, 상태 변경, 뷰 body)
[시스템 노드] = SwiftUI/시스템 작업
["update" 레이블 화살표] = 이 업데이트를 유발함
["creation" 레이블 화살표] = 뷰가 나타나도록 함
일반적인 패턴:
# 패턴 A: 단일 뷰 업데이트 (좋음)
[제스처] → [ViewModelA의 상태 변경] → [ViewA body]
# 패턴 B: 모든 뷰 업데이트 (나쁨 - 광범위한 의존성)
[제스처] → [배열 변경] → [모든 리스트 항목 뷰 업데이트]
└─ 수정: 항목당 세분화된 뷰 모델 사용
# 패턴 C: 환경을 통한 캐스케이드 (확인 필요)
[상태 변경] → [환경 쓰기] → [많은 뷰 body 확인]
└─ 환경 값이 자주 변경되면 → 패턴 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)") // isEditing에 따라 ID 변경됨
// ✅ 수정: 안정적인 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분
증상: 관련 없는 데이터가 변경될 때 많은 뷰가 업데이트됨
사용 시기:
- Cause & Effect 그래프에서 "Environment" 노드가 많은 업데이트를 트리거함
- 느린 스크롤 또는 애니메이션 성능
- 예상치 못한 캐스케이딩 업데이트
근본 원인: 환경에서 자주 변경되는 값 또는 너무 많은 뷰가 환경을 읽음
조사 단계:
1. 환경 쓰기 찾기 (3분)
# 현재 프로젝트에서 환경 수정자 검색
grep -r "\.environment(" --include="*.swift" .
찾을 대상:
// ❌ 나쁨: 자주 변경되는 값
.environment(\.scrollOffset, scrollOffset) // 초당 60회 이상 업데이트
.environment(model) // 모델이 자주 업데이트되면
// ✅ 좋음: 안정적인 값
.environment(\.colorScheme, .dark)
.environment(appModel) // appModel이 거의 변경되지 않으면
2. 환경에 무엇이 있는지 확인 (3분)
패턴 D2 (Instruments)를 사용하여 Cause & Effect 그래프 확인:
- "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에서 새 트레이스 기록
- Cause & Effect 그래프 확인 — 더 적은 뷰가 업데이트되어야 함
- 성능이 개선되어야 함 (더 부드러운 스크롤/애니메이션)
패턴 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("테스트")
}
// 이게 작동하면, 점차 추가:
#Preview {
MyView() // 실제 뷰지만, 모의 데이터 사용
.environment(MockModel()) // 모든 의존성 제공
}
// 어떤 의존성이 충돌을 유발하는지 찾기
일반적인 문제:
| 오류 | 원인 | 수정 |
|---|---|---|
| "범위에서 찾을 수 없음" | 누락된 의존성 | 프리뷰에 추가 (아래 예시 참조) |
| "치명적 오류: 예기치 않게 nil 발견됨" | 옵셔널 언래핑 실패 | 프리뷰에 nil이 아닌 값 제공 |
| "그런 모듈 없음" | 가져오기 누락 | 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)
}
검증:
- 프리뷰가 일관되게 로드되어야 함
- 오류가 해결되어야 함
- 여러 번 새로고침해도 안정적이어야 함
진단 워크플로 요약
| 패턴 | 증상 | 시간 | 주요 도구 |
|---|---|---|---|
| D1: Self._printChanges() | 기본 업데이트 문제 | 5분 | 소스 코드 |
| D2: SwiftUI Instrument | 복잡한 업데이트 패턴 | 25분 | Xcode Instruments |
| D3: 뷰 정체성 | 상태 재설정/애니메이션 문제 | 15분 | 소스 코드 검토 |
| D4: 환경 의존성 | 광범위한 업데이트 캐스케이드 | 10분 | grep + Instruments |
| D5: 프리뷰 진단 | 프리뷰 충돌/오류 | 10분 | 진단 + 충돌 로그 |
검증 체크리스트
문제를 해결한 후 모든 진단 패턴에 대해 이 목록을 사용하세요:
- 수정 없이도 문제가 재현됩니까? (재현 단계 확인)
- Self._printChanges()가 예상된 출력을 보여줍니까?
- Instruments Cause & Effect 그래프가 개선되었습니까?
- @State 값이 예상대로 유지됩니까?
- 애니메이션이 부드럽게 작동합니까?
- 여러 번 프리뷰를 새로고침해도 안정적입니까?
- 프로덕션 빌드에서도 문제가 해결됩니까?
- 디버깅 코드를 제거했습니까? (Self._printChanges() 등)