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가 호출되지 않음; 뷰가 전혀 업데이트되지 않음
⚠️ 중요:
- 밑줄 접두사 → 향후 릴리스에서 제거될 수 있음
- 절대 App Store에 제출하지 마세요 _printChanges 호출이 포함된 상태로
- 성능 영향 → 디버깅 중에만 사용
사용 시점:
- 뷰 업데이트의 정확한 트리거를 이해해야 할 때
- 예상치 못한 업데이트를 조사할 때
- 리팩토링 후 의존성을 확인할 때
참고: 복잡한 업데이트 패턴의 경우 SwiftUI Instrument 사용 → axiom-swiftui-performance 스킬 참조
뷰 업데이트 안 됨 결정 트리
가장 흔한 좌절: @State를 변경했지만 뷰가 다시 그려지지 않습니다. 근본 원인은 항상 다음 네 가지 중 하나입니다.
1단계: 최소 프리뷰에서 재현할 수 있나요?
#Preview {
YourView()
}
예 → 문제는 코드에 있습니다. 2단계로 계속 진행하세요.
아니요 → Xcode 상태 또는 캐시 손상일 가능성이 높습니다. 프리뷰 크래시 섹션으로 건너뛰세요.
2단계: 근본 원인 진단
근본 원인 1: 구조체 변경 (Struct Mutation)
증상: @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: 바인딩 항등성 상실 (Lost Binding Identity)
증상: 자식 뷰에 바인딩을 전달했지만, 자식에서 변경해도 부모가 업데이트되지 않습니다.
이유: .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: 의도치 않은 뷰 재생성 (Accidental View Recreation)
증상: 뷰가 업데이트되지만 @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: 옵저버 패턴 누락 (Missing Observer Pattern)
증상: 객체가 변경되었지만, 이를 관찰하는 뷰가 업데이트되지 않습니다.
이유: 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+): @State와 함께 @Observable 사용
@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을 environment와 함께 사용
@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래퍼 불필요@StateObject대신@State와 함께 작동@ObservedObject대신 일반 프로퍼티로 전달 가능
참고: Managing model data in your app
결정 트리 요약
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() // 크래시: 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("데이터 없음")
}
}
}
해결 방법: 강제 언래핑(!)을 찾아 제거하고, 안전한 기본값을 사용하며, 옵셔널을 적절히 처리하세요.
오류 유형 3: 프리뷰 캔버스에 "렌더링 실패" 또는 빈 화면
근본 원인: Xcode 프리뷰 캐시가 손상되었거나, 프리뷰 프로세스가 알 수 없는 이유로 충돌했습니다.
해결 방법:
-
프리뷰 캐시 지우기
- Xcode 메뉴: Product → Clear All Preview Cache
- 또는: 프로젝트 폴더에서
~/Library/Developer/Xcode/UserData/Previews삭제
-
빌드 폴더 정리
xcodebuild clean build -scheme YourScheme -
작업 재개
- Editor → Canvas → Refresh All Previews
- 그래도 안 되면 Xcode 재시작
-
마지막 수단
- Mac 재시동
~/Library/Caches/com.apple.dt.Xcode삭제
해결 방법: 위 방법들을 순서대로 시도하세요. 일반적으로 캐시 지우기가 문제를 해결합니다.
결정 트리 요약
digraph preview_crashes {
start [label="프리뷰 크래시?" shape=diamond];
error_type [label="오류 유형:" shape=box];
scope [label="범위/모듈 누락"];
silent [label="조용한 크래시"];
cache [label="프리뷰 렌더링 실패"];
start -> error_type;
error_type -> scope [label="Cannot find in scope / No such module"];
error_type -> silent [label="치명적 오류 / 메시지 없음"];
error_type -> cache [label="렌더링 실패 / 빈 화면"];
scope -> "의존성 제공 (.environment 등)";
silent -> "강제 언래핑 제거, 안전한 기본값 사용";
cache -> "프리뷰 캐시 지우기, 빌드 폴더 정리";
}
레이아웃 문제 빠른 참조
다음은 프리뷰나 시뮬레이터에서 즉시 확인할 수 있는 일반적인 레이아웃 문제 패턴입니다.
패턴 1: 뷰가 화면 밖으로 나감
증상: 뷰가 화면 가장자리를 넘어 확장됩니다.
// ❌ 잘못됨: 컨테이너에 뷰가 맞지 않음
HStack {
Text("긴 텍스트...")
Spacer()
Button("확인") { }
}
// ✅ 올바름: 텍스트 줄 바꿈 허용
HStack {
Text("긴 텍스트...")
.lineLimit(2) // 또는 .fixedSize(horizontal: true, vertical: false)
Spacer()
Button("확인") { }
}
// ✅ 또한 올바름: 오버플로우 방지를 위해 공간 제한
HStack {
Text("긴 텍스트...")
.frame(maxWidth: .infinity, alignment: .leading)
Button("확인") { }
}
패턴 2: VStack/HStack의 예상치 않은 간격
증상: 뷰 사이에 예상보다 더 많은 또는 적은 공간이 있습니다.
// ❌ 잘못됨: Spacer() 누락
VStack {
Text("상단")
Text("하단") // 바로 아래에 붙음
}
// ✅ 올바름: Spacer()로 공간 채우기
VStack {
Text("상단")
Spacer()
Text("하단")
}
// ❌ 잘못됨: .frame()과 불일치하는 패딩
Text("Hello")
.frame(height: 50)
.padding(.bottom, 20) // .frame() 안의 공간과 충돌
// ✅ 올바름: 일관된 공간 사용
Text("Hello")
.padding(.bottom, 20) // frame 없이 padding만 사용
패턴 3: ZStack 정렬 문제
증상: ZStack의 뷰가 예상과 다른 위치에 정렬됩니다.
// ❌ 잘못됨: 기본 정렬이 .center임
ZStack {
Image("background") // 전체 채움
Text("Hello") // 중앙
Button("닫기") { } // 중앙, 겹침
}
// ✅ 올바름: 명시적 정렬
ZStack(alignment: .topLeading) {
Image("background")
.resizable()
.ignoresSafeArea()
Text("Hello")
.padding()
Button("닫기") { }
.frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topTrailing)
.padding()
}
패턴 4: GeometryReader로 인한 예상치 않은 크기
증상: GeometryReader를 사용할 때 뷰가 너무 작거나 큽니다.
// ❌ 잘못됨: GeometryReader가 사용 가능한 모든 공간을 차지함
var body: some View {
GeometryReader { geometry in
Text("너비: \(geometry.size.width)")
}
.background(Color.blue) // GeometryReader가 전체 공간을 채움
}
// ✅ 올바름: GeometryReader에 크기 제한
var body: some View {
GeometryReader { geometry in
Text("너비: \(geometry.size.width)")
}
.frame(height: 100) // 높이 제한
.background(Color.blue)
}
// ✅ 올바름: 명시적 프레임 없이 preferredSize 사용
var body: some View {
MyCustomView()
.fixedSize() // 뷰의 이상적인 크기 사용
}
패턴 5: 아이폰 vs 아이패드 레이아웃 불일치
증상: 아이패드에서 뷰가 예상과 다르게 보입니다.
// ❌ 잘못됨: 아이패드에서 너무 넓게 퍼짐
Text("Hello")
.frame(maxWidth: .infinity)
// ✅ 올바름: 읽기 쉬운 너비로 제한
Text("Hello")
.frame(maxWidth: 400) // 아이패드에서도 너무 넓지 않음
// ❌ 잘못됨: 아이패드에서 뷰가 세로로 늘어남
VStack {
HStack {
Text("왼쪽")
Spacer()
Text("오른쪽")
}
}
// ✅ 올바름: 명시적 프레임 또는 크기 클래스 사용
struct MyView: View {
@Environment(\.horizontalSizeClass) var sizeClass
var body: some View {
if sizeClass == .compact {
VStack {
Text("좁은 레이아웃")
}
} else {
HStack {
Text("넓은 레이아웃")
}
}
}
}
패턴 6: 상태 표시줄 또는 세이프 에어리어 문제
증상: 뷰가 상태 표시줄 아래에서 시작하거나, 위젯과 겹칩니다.
// ❌ 잘못됨: 세이프 에어리어 무시로 겹침
Color.blue
.ignoresSafeArea()
.overlay(Text("위젯")) // 상태 표시줄과 겹침
// ✅ 올바름: 세이프 에어리어 고려
Color.blue
.ignoresSafeArea(edges: .bottom) // 상단은 세이프 에어리어 유지
// ✅ 올바름: 세이프 에어리어 인셋 사용
VStack {
Text("내용")
.padding(.top, 20) // 수동 세이프 에어리어
}
// ✅ 올바름: @Environment 세이프 에어리어 사용 (iOS 17+)
struct MyView: View {
@Environment(\.safeAreaInsets) var safeAreaInsets
var body: some View {
Text("안전한 영역")
.padding(.top, safeAreaInsets.top)
}
}
모범 사례 요약
뷰 업데이트 문제 방지
| 패턴 | iOS 17+ 방법 | iOS 17 미만 방법 |
|---|---|---|
| 관찰 가능한 객체 | @Observable + @State | ObservableObject + @StateObject |
| 의존성 주입 | @Environment(T.self) | @EnvironmentObject |
| 자식에서 부모 업데이트 | $state 또는 @Bindable | ObservedObject 또는 Binding |
| 뷰 항등성 유지 | .opacity(), .id() | .opacity(), .id() |
프리뷰 크래시 방지
- 프리뷰에 항상 필요한 의존성 제공
- 강제 언래핑 제거, 안전한 기본값 사용
- 주기적으로 프리뷰 캐시 지우기
레이아웃 문제 방지
- 명시적 프레임과 정렬 사용 (기본값에 의존하지 않음)
- 세이프 에어리어 존중 (무시하기보다는)
- 프레임 제한 없이 GeometryReader를 사용하면 전체 공간을 차지함을 명심
- 아이패드 레이아웃은 크기 클래스로 처리
관련 문서
- Managing model data in your app - Apple 공식 문서
- SwiftUI 프리뷰 문제 해결 - Apple 공식 문서
- Human Interface Guidelines: 레이아웃 - Apple HIG
관련 스킬:
axiom-xcode-debugging- Xcode 캐시 손상 진단 및 환경 문제axiom-swift-concurrency- async/await, MainActor, 데이터 경합axiom-swiftui-performance- Instruments 프로파일링, 성능 최적화axiom-swiftui-layout- 적응형 레이아웃 패턴