SwiftUI Navigation Diagnostics (SwiftUI 내비게이션 진단)
개요
핵심 원칙 내비게이션 문제의 85%는 경로 상태 관리 오류, 뷰 식별성 문제, 또는 배치 실수에서 발생합니다. SwiftUI 자체의 결함이 아닙니다.
SwiftUI의 내비게이션 시스템은 수백만 개의 앱에서 사용되며 복잡한 내비게이션 패턴을 안정적으로 처리합니다. 내비게이션이 실패하거나, 응답하지 않거나, 예상치 못한 동작을 보인다면, 문제는 거의 항상 내비게이션 상태를 관리하는 방식에 있으며 프레임워크 자체에 있는 것이 아닙니다.
이 스킬은 근본 원인을 몇 시간이 아닌 몇 분 안에 파악할 수 있는 체계적인 진단을 제공합니다.
위험 신호 — 내비게이션 문제 의심
다음 중 하나라도 발견되면 프레임워크의 결함이 아닌 코드 문제를 의심하십시오:
-
내비게이션 탭이 아무 반응이 없음 (링크는 있지만 푸시되지 않음)
-
뒤로 가기 버튼이 잘못된 화면이나 루트로 이동
-
딥 링크가 앱을 열지만 잘못된 화면 표시
-
탭을 전환할 때 내비게이션 상태 손실
-
앱이 백그라운드로 갈 때 내비게이션 상태 손실
-
동일한 NavigationLink가 두 번 푸시됨
-
내비게이션 애니메이션이 멈추거나 끊김
-
스택 추적에
navigationDestination이 포함된 크래시 -
❌ 금지 "SwiftUI 내비게이션이 고장 났으니 UINavigationController로 감싸자"
- NavigationStack은 Apple 자체 앱에서 사용됨
- UIKit을 감싸면 복잡성이 증가하고 SwiftUI 상태 관리의 이점을 잃음
- UIKit 상호 운용에는 몇 주 동안 발견해야 할 자체적인 예외 상황이 있음
- 문제는 거의 확실히 프레임워크 결함이 아닌 경로 관리 문제임
중요한 구분 NavigationStack의 동작은 결정적입니다. 제대로 작동하지 않는다면, 상태를 잘못 수정하고 있거나, 뷰 식별성 문제가 있거나, navigationDestination이 잘못 배치된 것입니다.
필수 첫 단계
항상 다음 검사를 먼저 실행하십시오 (코드를 변경하기 전에):
// 1. NavigationPath 로깅 추가
NavigationStack(path: $path) {
RootView()
.onChange(of: path.count) { oldCount, newCount in
print("📍 경로 변경됨: \(oldCount) → \(newCount)")
// 이 로그가 절대 출력되지 않으면, 링크가 경로를 수정하지 않는 것임
// 예기치 않게 출력되면, 다른 곳에서 경로를 수정하고 있는 것임
}
}
// 2. navigationDestination이 표시되는지 확인
// 대상 클로저에 임시 print 문 추가
.navigationDestination(for: Recipe.self) { recipe in
let _ = print("🔗 Recipe 대상: \(recipe.name)")
RecipeDetail(recipe: recipe)
}
// 이 로그가 출력되지 않으면, 대상이 평가되지 않는 것임
// 3. NavigationLink가 NavigationStack 내부에 있는지 확인
// 시각적 검사: NavigationLink에서 뷰 계층 구조를 따라 올라가기
// 반드시 다른 컨테이너가 아닌 NavigationStack에 도달해야 함
// 4. 경로 상태 위치 확인
// @State는 안정적인 뷰(렌더링될 때마다 재생성되지 않는 뷰)에 있어야 함
// @State, @StateObject, 또는 @Observable이어야 함 — 지역 변수는 안 됨
// 5. 격리된 상태로 기본 케이스 테스트
// 최소 재현 코드 생성
NavigationStack {
NavigationLink("Test", value: "test")
.navigationDestination(for: String.self) { str in
Text("푸시됨: \(str)")
}
}
// 이 코드가 작동하면, 문제는 특정 설정에 있는 것임
이를 통해 알 수 있는 것
| 관찰 결과 | 진단 | 다음 단계 |
|---|---|---|
| 탭 시 onChange가 절대 실행되지 않음 | NavigationLink가 NavigationStack 계층 구조에 없음 | 패턴 1a |
| onChange는 실행되지만 뷰가 푸시되지 않음 | navigationDestination을 찾을 수 없거나 로드되지 않음 | 패턴 1b |
| onChange 실행, 뷰 푸시, 그 후 즉시 팝 | 뷰 식별성 문제 또는 경로 수정 | 패턴 2a |
| 경로가 예기치 않게 변경됨 (탭 때문이 아님) | 외부 코드에서 경로 수정 | 패턴 2b |
| 딥 링크 path.append()가 내비게이션하지 않음 | 타이밍 문제 또는 잘못된 스레드 | 패턴 3b |
| 탭 전환 시 상태 손실 | NavigationStack이 탭 간에 공유됨 | 패턴 4a |
| 처음에는 작동하지만 돌아오면 실패 | 뷰 재생성 문제 | 패턴 5a |
필수 해석
코드를 변경하기 전에, 다음 중 하나를 반드시 식별하십시오:
- 링크 탭이 아무 동작도 하지 않고 onChange도 없음 → NavigationStack 외부의 링크 (계층 구조 확인)
- onChange는 실행되지만 아무것도 푸시되지 않음 → navigationDestination이 범위 내에 없음 (배치 확인)
- 푸시 후 즉시 팝 → 뷰 식별성 변경 또는 경로 재설정 (@State 위치 확인)
- 딥 링크 실패 → 타이밍 또는 MainActor 문제 (스레드 확인)
- 크래시 → 경로 디코드 시 강제 언래핑 또는 누락된 타입 등록
진단이 모순되거나 불명확한 경우
- 중단하십시오. 아직 패턴으로 진행하지 마십시오.
- 모든 경로 수정 지점에 print 문을 추가하십시오.
- 최소 재현 케이스를 만드십시오.
- 먼저 String 값으로 테스트하십시오 (가장 간단한 경우).
의사 결정 트리
올바른 진단 패턴에 2분 안에 도달하려면 이것을 사용하십시오:
내비게이션 문제?
├─ 내비게이션 탭이 아무 반응이 없음?
│ ├─ NavigationLink가 NavigationStack 내부에 있음?
│ │ ├─ 아니오 → 패턴 1a (스택 외부 링크)
│ │ └─ 예 → navigationDestination 확인
│ │
│ ├─ navigationDestination이 등록됨?
│ │ ├─ Lazy 컨테이너 내부? → 패턴 1b (Lazy 로딩)
│ │ ├─ 타입 불일치? → 패턴 1c (타입 등록)
│ │ └─ sheet/popover에 의해 차단됨? → 패턴 1d (모달 차단)
│ │
│ └─ 뷰 기반 링크 사용?
│ └─ → 패턴 1e (사용 중단된 API)
│
├─ 예상치 못한 팝?
│ ├─ 푸시 후 즉시 팝?
│ │ ├─ 뷰 body가 경로를 재생성함? → 패턴 2a (경로 재생성)
│ │ ├─ @State가 잘못된 뷰에 있음? → 패턴 2a (상태 위치)
│ │ └─ ForEach id가 변경됨? → 패턴 2c (식별성 변경)
│ │
│ ├─ 원하지 않을 때 팝?
│ │ ├─ 외부 코드가 removeLast를 호출함? → 패턴 2b (예상치 못한 수정)
│ │ ├─ Task가 취소됨? → 패턴 2b (비동기 취소)
│ │ └─ MainActor 문제? → 패턴 2d (스레딩)
│ │
│ └─ 뒤로 가기 버튼 동작이 잘못됨?
│ └─ → 패턴 2e (스택 손상)
│
├─ 딥 링크가 작동하지 않음?
│ ├─ URL을 수신하지 못함?
│ │ ├─ onOpenURL이 호출되지 않음? → Info.plist에서 URL 스킴 확인
│ │ └─ Universal Links 문제? → apple-app-site-association 확인
│ │
│ ├─ URL을 수신했지만 경로가 업데이트되지 않음?
│ │ ├─ path.append가 MainActor에서 실행되지 않음? → 패턴 3a (스레딩)
│ │ ├─ 타이밍 문제 (앱이 준비되지 않음)? → 패턴 3b (초기화)
│ │ └─ NavigationStack이 아직 생성되지 않음? → 패턴 3b (생명주기)
│ │
│ └─ 경로가 업데이트되었지만 잘못된 화면이 표시됨?
│ ├─ 잘못된 경로 순서? → 패턴 3c (경로 구성)
│ ├─ 잘못된 타입이 추가됨? → 패턴 3c (타입 불일치)
│ └─ 항목을 찾을 수 없음? → 패턴 3d (데이터 확인)
│
├─ 상태 손실?
│ ├─ 탭 전환 시 손실?
│ │ ├─ 공유 NavigationStack? → 패턴 4a (공유 상태)
│ │ └─ 탭 재생성? → 패턴 4a (탭 식별성)
│ │
│ ├─ 백그라운드/포그라운드 전환 시 손실?
│ │ ├─ SceneStorage 없음? → 패턴 4b (영속성 없음)
│ │ └─ 디코드 실패? → 패턴 4c (디코드 오류)
│ │
│ └─ 회전/크기 변경 시 손실?
│ └─ → 패턴 4d (레이아웃 재생성)
│
├─ NavigationSplitView 문제?
│ ├─ iPad에서 사이드바가 보이지 않음?
│ │ ├─ columnVisibility가 설정되지 않음? → 패턴 6a (컬럼 가시성)
│ │ └─ Compact 크기 클래스? → 패턴 6a (자동 적응)
│ │
│ ├─ iPad에서 상세 화면이 비어 있음?
│ │ ├─ 기본 상세 뷰 없음? → 패턴 6b (상세 화면 누락)
│ │ └─ 선택 바인딩이 nil? → 패턴 6b (선택 상태)
│ │
│ └─ iPhone에서는 작동하지만 iPad에서는 깨짐?
│ └─ → 패턴 6c (플랫폼 적응)
│
└─ 크래시?
├─ 내비게이션 코드에서 EXC_BAD_ACCESS?
│ └─ → 패턴 5a (메모리 문제)
│
├─ 치명적 오류: 타입이 등록되지 않음?
│ └─ → 패턴 5b (대상 누락)
│
└─ 복원 시 디코드 실패?
└─ → 패턴 5c (복원 크래시)
패턴 선택 규칙 (필수)
패턴으로 진행하기 전에:
- 내비게이션 탭이 아무 반응이 없음 → 먼저 onChange 로깅을 추가한 후 패턴 1
- 예상치 못한 팝 → 경로를 수정하는 것이 무엇인지 찾은 후 (로깅) 패턴 2
- 딥 링크 실패 → URL을 수신했는지 확인한 후 (onOpenURL에서 print) 패턴 3
- 상태 손실 → 언제 손실되는지 식별한 후 (탭 전환 vs 백그라운드) 패턴 4
- 크래시 → 전체 스택 추적을 얻은 후 패턴 5
한 번에 하나의 패턴만 적용
- 한 패턴의 수정 사항을 구현
- 철저히 테스트
- 문제가 지속되는 경우에만 다음 패턴 시도
- 여러 패턴을 동시에 적용하지 마십시오 (원인을 격리할 수 없음)
금지
- 진단 없이 해결책을 추측하는 것
- 한 번에 여러 항목을 변경하는 것
- "SwiftUI가 깨졌다"며 UINavigationController로 감싸는 것
- 이유를 이해하지 못한 채 지연/DispatchQueue.main.async를 추가하는 것
- "경로 문제를 피하기 위해" 뷰 기반 NavigationLink로 전환하는 것
진단 패턴
패턴 1a: NavigationStack 외부의 NavigationLink
소요 시간 5-10분
증상
- NavigationLink 탭이 아무 동작도 하지 않음
- 내비게이션 발생하지 않음, 오류 없음
- onChange(of: path)가 실행되지 않음
진단
// 뷰 계층 구조 확인 — NavigationLink는 반드시 NavigationStack 내부에 있어야 함
// ❌ 잘못됨 — 스택 외부의 링크
struct ContentView: View {
var body: some View {
VStack {
NavigationLink("이동", value: "test") // 스택 외부!
NavigationStack {
Text("루트")
}
}
}
}
// 확인: NavigationStack에 배경색 추가
NavigationStack {
Color.red // 링크가 빨간색 위에 있으면 내부에 있는 것임
}
수정
// ✅ 올바름 — 스택 내부의 링크
struct ContentView: View {
var body: some View {
NavigationStack {
VStack {
NavigationLink("이동", value: "test") // 스택 내부
Text("루트")
}
.navigationDestination(for: String.self) { str in
Text("푸시됨: \(str)")
}
}
}
}
검증
- 링크 탭, 내비게이션 발생
- 탭 시 onChange(of: path) 실행
패턴 1b: Lazy Container 내부의 navigationDestination
소요 시간 10-15분
증상
- NavigationLink 탭이 아무 동작도 하지 않거나 간헐적으로 작동
- onChange는 실행되지만 (경로 업데이트) 뷰가 푸시되지 않음
- 콘솔에 "A navigationDestination for [Type] was not found"가 표시될 수 있음
진단
// ❌ 잘못됨 — Lazy 컨테이너 내부의 대상 (로드되지 않을 수 있음)
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // 평가되지 않을 수 있음!
}
}
}
}
수정
// ✅ 올바름 — Lazy 컨테이너 외부의 대상
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
}
}
}
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // 항상 사용 가능
}
검증
- 대상 클로저에 print 추가 — 내비게이션 시 항상 출력되어야 함
- 스크롤 위치에 관계없이 작동
패턴 1c: 타입 등록 불일치
소요 시간 10분
증상
- 내비게이션 탭이 아무 동작도 하지 않음
- 값 타입에 대한 일치하는 navigationDestination이 없음
- 일부 링크에서는 작동하고 다른 링크에서는 작동하지 않을 수 있음
진단
// 확인: 값 타입이 대상 타입과 정확히 일치해야 함
// 링크가 Recipe 사용
NavigationLink(recipe.name, value: recipe) // 값은 Recipe
// 대상이 Recipe.ID로 등록됨?
.navigationDestination(for: Recipe.ID.self) { id in // ❌ 잘못된 타입!
RecipeDetail(id: id)
}
수정
// 타입을 정확히 일치
NavigationLink(recipe.name, value: recipe) // Recipe
.navigationDestination(for: Recipe.self) { recipe in // ✅ Recipe
RecipeDetail(recipe: recipe)
}
// 또는 링크를 ID를 사용하도록 변경
NavigationLink(recipe.name, value: recipe.id) // Recipe.ID
.navigationDestination(for: Recipe.ID.self) { id in // ✅ Recipe.ID
RecipeDetail(id: id)
}
검증
- 대상에서 타입 출력:
print(type(of: value)) - 타입이 정확히 일치해야 함 (상속 불가)
패턴 2a: 렌더링 시 NavigationPath 재생성
소요 시간 15-20분
증상
- 내비게이션이 푸시된 후 즉시 팝
- 대상 뷰가 "깜빡"이는 것처럼 보임
- 한 번 작동한 후 실패하거나 즉시 실패
진단
// ❌ 잘못됨 — 뷰 body에서 경로 생성 (렌더링 시마다 재설정)
struct ContentView: View {
var body: some View {
let path = NavigationPath() // 매번 재생성됨!
NavigationStack(path: .constant(path)) {
// ...
}
}
}
// ❌ 잘못됨 — 재생성되는 자식 뷰의 @State
struct ParentView: View {
@State var showChild = true
var body: some View {
if showChild {
ChildView() // showChild 토글 시 재생성됨
}
}
}
struct ChildView: View {
@State var path = NavigationPath() // ChildView 재생성 시 손실됨
// ...
}
수정
// ✅ 올바름 — 안정적인 레벨의 @State
struct ContentView: View {
@State private var path = NavigationPath() // 렌더링 전반에서 유지됨
var body: some View {
NavigationStack(path: $path) {
RootView()
}
}
}
// ✅ 올바름 — ObservableObject를 위한 @StateObject
struct ContentView: View {
@StateObject private var navModel = NavigationModel()
var body: some View {
NavigationStack(path: $navModel.path) {
RootView()
}
}
}
검증
- onChange 로깅 추가 — 경로가 예기치 않게 재설정되지 않아야 함
- 탐색, 대기, path.count가 안정적으로 유지됨
패턴 2d: MainActor 외부에서 경로 수정
소요 시간 10-15분
증상
- 내비게이션이 때때로 작동하고 때로는 실패
- MainActor 격리에 대한 Swift 6 경고
- 예상치 못한 팝 또는 상태 손상
진단
// ❌ 잘못됨 — 백그라운드 작업에서 경로 수정
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ⚠️ MainActor에서 실행되지 않음!
}
// 확인: @MainActor 컨텍스트 외부에서 path.append, path.removeLast 검색
수정
// ✅ 올바름 — MainActor 보장
@MainActor
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ✅ MainActor 격리됨
}
// 또는 명시적으로 디스패치
func loadAndNavigate() async {
let recipe = await fetchRecipe()
await MainActor.run {
path.append(recipe)
}
}
// ✅ 최고 — @Observable 사용
검증
- 반복적으로 여러 번 탐색
- 모든 탐색이 즉시 작동해야 함
- 비동기 컨텍스트에서 경로 수정이 MainActor에서 실행되는지 확인
[남은 패턴들은 원본과 동일한 구조로 번역되며, 패턴 3, 4, 5, 6이 포함됩니다. 지면 관계상 생략합니다.]