UIKit 애니메이션 디버깅은(는) 무엇을 하나요?
개요
CAAnimation 문제는 특정 조건에서 완료 핸들러 미실행, 잘못된 타이밍, 또는 끊김 현상으로 나타납니다. 핵심 원칙: CAAnimation 문제의 90%는 Core Animation 버그가 아니라 CATransaction 타이밍, 레이어 상태, 또는 프레임 레이트 가정으로 인해 발생합니다.
위험 신호 — CAAnimation 문제 의심
다음 중 하나라도 발견되면 애니메이션 로직이 아닌 기기 동작 문제로 의심하세요:
- 시뮬레이터에서는 완료 핸들러가 실행되지만 기기에서는 실행되지 않음
- 애니메이션 지속 시간(0.5초)이 시각적 지속 시간(1.2초)과 일치하지 않음
- 스프링 애니메이션이 iPhone 15 Pro에서는 정상이지만 구형 기기에서는 끊김
- 제스처와 애니메이션을 함께 사용하면 끊김 현상 발생 (각각 따로는 정상)
- 완료 핸들러에서
[weak self]를 사용하고 있고, 그 이유를 확신하지 못함 - ❌ 금지: "실제 동작과 일치하도록" 지속 시간/값을 하드코딩하는 행위
- 이는 다른 하드웨어를 사용하는 사용자에게 기기별 버그를 배포하는 것입니다.
- 이를 "임시 수정" 또는 "충분히 좋은" 방법이라고 합리화하지 마십시오.
중요한 차이점: 시뮬레이터는 종종 타이밍 문제를 숨깁니다(60Hz만 지원, 조절 없음). 실제 기기는 이를 드러냅니다(가변 프레임 레이트, CPU 조절, 백그라운드 압력). 필수: 배포 전에 반드시 실제 기기(지원되는 가장 오래된 모델)에서 테스트하세요.
필수 첫 번째 단계
항상 다음을 먼저 실행하세요 (코드 변경 전):
// 1. 완료 핸들러가 실행되는지 확인
animation.completion = { [weak self] finished in
print("🔥 COMPLETION FIRED: finished=\(finished)")
guard let self = self else {
print("🔥 SELF WAS NIL")
return
}
// 원래 코드
}
// 2. 실제 지속 시간과 선언된 지속 시간 확인
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5 // 선언됨
layer.add(anim, forKey: "test")
DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
print("Elapsed: \(Date().timeIntervalSince(startTime))") // 실제
}
// 3. 활성 애니메이션 확인
if let keys = layer.animationKeys() {
print("Active animations: \(keys)")
for key in keys {
if let anim = layer.animation(forKey: key) {
print("\(key): duration=\(anim.duration), removed=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. 레이어 상태 확인
print("Layer speed: \(layer.speed)") // != 1.0이면 타이밍이 조정된 것
print("Layer timeOffset: \(layer.timeOffset)") // != 0이면 애니메이션이 오프셋된 것
이 정보가 알려주는 것
- 완료 출력 나타남 → 핸들러 실행됨, 문제는 콜백 코드에 있음
- 완료 출력 없음 → 핸들러 실행되지 않음, CATransaction/레이어 상태 확인
- 경과 시간 == 선언된 시간 → 지속 시간은 정확, 시각적 끊김은 프레임 문제
- 경과 시간 != 선언된 시간 → CATransaction 래핑이 지속 시간을 변경함
- layer.speed != 1.0 → 애니메이션을 늦추는 무언가가 있음
- 활성 애니메이션 목록이 긺 → 여러 애니메이션이 경쟁함
필수 해석
코드를 변경하기 전에 다음 중 어떤 진단이 근본 원인인지 반드시 식별해야 합니다:
- 완료는 실행되지만 경과 시간이 선언된 지속 시간과 다름 → 패턴 2(CATransaction) 적용
- 완료가 실행되지 않고 isRemovedOnCompletion이 true → 패턴 3 적용
- 완료는 실행되지만 시각적으로 끊김 → 먼저 반드시 Instruments로 프로파일링
- "아마 프레임 문제일 거야"라고 추측할 수 없습니다. 데이터로 증명하세요.
- 프로파일 > Core Animation 인스트루먼트는 프레임 드롭을 확실하게 보여줍니다.
- Instruments를 건너뛰면, 추측하는 것입니다.
진단이 모순되거나 불명확한 경우
- 중단하세요. 아직 패턴으로 진행하지 마십시오.
- 원인을 좁히기 위해 print 문을 더 추가하세요.
- 스스로에게 질문하세요: "진단 결과 X와 Y를 보여주지만 Z는 일치하지 않습니다. 무엇을 놓치고 있습니까?"
- 확실하지 않으면 Instruments > Core Animation으로 프로파일링하세요.
의사 결정 트리
CAAnimation 문제?
├─ 완료 핸들러가 실행되지 않습니까?
│ ├─ 시뮬레이터에서만?
│ │ └─ 시뮬레이터 타이밍이 다릅니다(60Hz). 실제 기기에서 테스트하세요.
│ ├─ 실제 기기에서만?
│ │ ├─ 확인: isRemovedOnCompletion 및 fillMode
│ │ ├─ 확인: CATransaction 래핑
│ │ └─ 확인: 애니메이션 중에 앱이 백그라운드로 전환됨
│ └─ 시뮬레이터와 기기 모두에서?
│ ├─ 확인: 완료 핸들러가 애니메이션 추가 전에 설정됨
│ └─ 확인: [weak self]가 실제로 캡처됨(완료 전에 nil이 아님)
│
├─ 지속 시간 불일치(선언됨 != 시각적)?
│ ├─ layer.speed != 1.0입니까?
│ │ └─ 애니메이션 지속 시간을 조정하는 무언가가 있습니다. 찾아서 수정하세요.
│ ├─ 애니메이션이 CATransaction에 래핑되었습니까?
│ │ └─ CATransaction.setAnimationDuration()이 animation.duration을 재정의합니다.
│ └─ 시각적 지속 시간이 선언된 시간보다 깁니까?
│ └─ 시뮬레이터(60Hz) 대 기기 프레임 레이트(120Hz). 실제 하드웨어에 맞게 다시 계산하세요.
│
├─ 기기에서 스프링 물리 효과가 잘못됩니까?
│ ├─ 값이 하나의 기기에 하드코딩되었습니까?
│ │ └─ 모델이 아닌 기기 성능 클래스를 사용하세요.
│ ├─ 감쇠/강성 값이 질량/강성과 바뀌었습니까?
│ │ └─ CASpringAnimation 매개변수 의미를 확인하세요.
│ └─ 시뮬레이터에서는 작동하지만 기기에서는 작동하지 않습니까?
│ └─ 시뮬레이터는 60Hz를 사용합니다. 기기는 120Hz를 사용할 수 있습니다. 다시 계산하세요.
│
└─ 제스처 + 애니메이션 끊김?
├─ 애니메이션이 경쟁하고 있습니까(동일한 keyPath)?
│ └─ 새 애니메이션을 추가하기 전에 이전 애니메이션을 제거하세요.
├─ 제스처가 애니메이션 실행 중에 레이어를 업데이트합니까?
│ └─ 동기화된 업데이트를 위해 CADisplayLink를 사용하세요.
└─ 제스처가 메인 스레드를 차단하고 있습니까?
└─ Instruments > Core Animation으로 프로파일링하세요.
일반적인 패턴
패턴 선택 규칙 (필수)
한 번에 하나의 패턴을 다음 순서로 적용하세요
-
항상 패턴 1부터 시작 (완료 핸들러 기본)
- 완료 핸들러가 절대 실행되지 않는 경우 → 패턴 1
- print 문(라인 33)을 사용하여 완료 핸들러가
add()전에 설정되었는지 확인 - 완료 핸들러는 실행되지만 타이밍이 잘못된 경우에만 패턴 2로 진행
-
그 다음 패턴 2 (CATransaction 지속 시간 불일치)
- 완료 핸들러는 실행되지만 경과 시간이 선언된 지속 시간과 다른 경우만
- 필수 첫 번째 단계(라인 40-47)의 로그 확인
-
그 다음 패턴 3 (isRemovedOnCompletion)
- 애니메이션이 완료되지만 시각적 상태가 되돌아가는 경우만
-
패턴 4-7 특정 증상에 따라 적용 (의사 결정 트리 라인 91+ 참조)
금지
- ❌ 여러 패턴을 한 번에 적용("패턴 2와 패턴 4를 함께 시도하자")
- ❌ "내가 이미 그게 아니라는 걸 알고 있어"라며 패턴 1을 건너뜀
- ❌ 각 패턴이 필요한 이유를 이해하지 않고 패턴을 결합
- ❌ 무작위로 패턴을 시도하고 하나가 작동하길 바람
패턴 1: 완료 핸들러 기본
❌ 잘못됨 (애니메이션 추가 후 핸들러 설정)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ 너무 늦음!
print("Done")
}
✅ 올바름 (추가 전에 핸들러 설정)
animation.completion = { [weak self] finished in
print("🔥 Animation finished: \(finished)")
guard let self = self else { return }
self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")
이유: 완료 핸들러는 애니메이션이 레이어에 추가되기 전에 설정되어야 합니다. 추가 후에 설정하면 아무 효과가 없습니다.
패턴 2: CATransaction 대 animation.duration
❌ 잘못됨 (CATransaction이 애니메이션 지속 시간을 재정의)
CATransaction.begin()
CATransaction.setAnimationDuration(2.0) // ❌ 모든 애니메이션을 재정의!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5 // 무시됨
layer.add(anim, forKey: nil)
CATransaction.commit() // 애니메이션이 0.5초가 아닌 2.0초 걸림
✅ 올바름 (트랜잭션이 아닌 애니메이션에 지속 시간 설정)
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// CATransaction 래핑 없음
이유: CATransaction.setAnimationDuration()은 트랜잭션 블록 내의 모든 애니메이션에 영향을 미칩니다. 모든 애니메이션을 균일하게 변경하려는 경우에만 사용하세요.
패턴 3: isRemovedOnCompletion 및 fillMode
❌ 잘못됨 (애니메이션이 완료 후 사라짐)
let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// 0.5초 후, 애니메이션이 제거되고 레이어가 원래 상태로 되돌아감
✅ 올바름 (애니메이션 상태 유지)
anim.isRemovedOnCompletion = false
anim.fillMode = .forwards // 애니메이션 후 최종 상태 유지
layer.add(anim, forKey: nil)
// 0.5초 후, 애니메이션 상태가 보존됨
이유: 기본적으로 애니메이션은 제거되고 레이어는 되돌아갑니다. 영구적인 상태 변경을 위해서는 isRemovedOnCompletion = false 및 fillMode = .forwards를 설정하세요.
패턴 4: 완료 핸들러에서 Weak Self (필수)
❌ 금지 (Strong self는 순환 참조 생성)
anim.completion = { finished in
self.property = "value" // ❌ 확정적인 순환 참조
}
✅ 필수 (항상 weak self 사용)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "value" // 안전하게 접근
}
이것이 선택 사항이 아닌 필수인 이유
- CAAnimation은 애니메이션이 완료될 때까지 완료 핸들러를 유지합니다.
- 완료 핸들러는 self를 강하게 캡처합니다(명시적으로 weak로 하지 않는 한).
- 순환 참조 생성: self → animation → completion → self
- 애니메이션이 짧더라도(0.3초) 메모리 누수가 발생합니다.
금지된 합리화
- ❌ "애니메이션이 짧아서 순환 참조 위험이 없습니다."
- ❌ "애니메이션을 수동으로 제거할 것이므로 괜찮습니다."
- ❌ "이 코드 경로는 한 번만 실행됩니다."
완료 핸들러에서 항상 [weak self]를 사용하세요. 예외는 없습니다.
패턴 5: 여러 애니메이션 (동일한 keyPath)
❌ 잘못됨 (애니메이션 충돌)
// 애니메이션 1 추가
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")
// 나중에, 애니메이션 2 추가
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide") // ❌ 동일한 키, anim1을 대체!
✅ 올바름 (추가하기 전에 제거)
layer.removeAnimation(forKey: "slide") // 먼저 이전 애니메이션 제거
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")
또는 고유 키 사용:
let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")
let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2") // 다른 키
이유: 동일한 키로 애니메이션을 추가하면 이전 애니메이션이 대체됩니다. 이전 애니메이션을 제거하거나 고유 키를 사용하세요.
패턴 6: 제스처 + 애니메이션 동기화를 위한 CADisplayLink
❌ 잘못됨 (제스처가 직접 업데이트, 애니메이션이 다른 속도로 업데이트)
func handlePan(_ gesture: UIPanGestureRecognizer) {
let translation = gesture.translation(in: view)
view.layer.position.x = translation.x // ❌ 동기화 문제
}
// 별도로:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil) // 동기화 해제로 인한 끊김
✅ 올바름 (동기화를 위해 CADisplayLink 사용)
var displayLink: CADisplayLink?
func startSyncedAnimation() {
displayLink = CADisplayLink(
target: self,
selector: #selector(updateAnimation)
)
displayLink?.add(to: .main, forMode: .common)
}
@objc func updateAnimation() {
// 동일한 프레임에서 제스처와 애니메이션 업데이트
let gesture = currentGesture
let position = calculatePosition(from: gesture)
layer.position = position // 동기화된 업데이트
}
이유: 제스처 인식기와 CAAnimation은 다른 프레임 레이트로 실행될 수 있습니다. CADisplayLink는 둘 다 화면 새로 고침 속도에 동기화합니다.
패턴 7: 스프링 애니메이션 기기 차이
❌ 잘못됨 (하나의 기기에 하드코딩)
let springAnim = CASpringAnimation()
springAnim.damping = 0.7 // iPhone 15 Pro에 하드코딩
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil) // iPhone 12에서 끊김
✅ 올바름 (기기 성능에 맞게 조정)
let springAnim = CASpringAnimation()
// 모델이 아닌 기기 성능 클래스 사용
if ProcessInfo.processInfo.processorCount >= 6 {
// 최신 A-시리즈 (A14+)
springAnim.damping = 0.7
springAnim.stiffness = 100
} else {
// 구형 A-시리즈
springAnim.damping = 0.85
springAnim.stiffness = 80
}
layer.add(springAnim, forKey: nil)
이유: 스프링 물리 효과는 60Hz와 120Hz에서 다르게 느껴집니다. 모델이 아닌 기기 클래스(코어 수, GPU)를 사용하세요.
빠른 참조 표
| 문제 | 확인 사항 | 수정 방법 |
|---|---|---|
| 완료 핸들러가 실행되지 않음 | add() 전에 핸들러 설정 확인 | completion =을 add() 앞으로 이동 |
| 지속 시간 불일치 | CATransaction 래핑 여부? | CATransaction 제거 또는 애니메이션 분리 |
| 구형 기기에서 끊김 | 값이 하드코딩되었습니까? | ProcessInfo를 사용하여 기기 클래스 확인 |
| 애니메이션이 사라짐 | isRemovedOnCompletion? | false로 설정, fillMode = .forwards 사용 |
| 제스처 + 애니메이션 끊김 | 동기화된 업데이트? | CADisplayLink 사용 |
| 여러 애니메이션 충돌 | 동일한 키? | 고유 키 사용 또는 removeAnimation() 먼저 호출 |
| 핸들러에서 Weak self | 완료 핸들러가 올바르게 캡처되었습니까? | 완료 핸들러에서 항상 [weak self] 사용 |
30분 후에도 막혔을 때
30분 이상 애니메이션이 여전히 고장나 있다면:
중단하세요. 다음 중 하나일 가능성이 높습니다.
- 필수 단계를 건너뛰었습니다(가장 흔함).
- 진단 출력을 잘못 해석했습니다.
- 증상에 맞지 않는 잘못된 패턴을 적용했습니다.
- Instruments 프로파일링이 필요한 5%의 특수한 경우에 해당합니다.
"스킬이 작동하지 않았다"고 주장하기 전 필수 체크리스트
- 필수 첫 번째 단계(라인 28-63)의 4가지 진단 블록을 모두 실행했습니다.
- 진단 결과(로그, print 문)의 정확한 출력을 붙여넣었습니다.
- "이 정보가 알려주는 것"(라인 66-72)에서 하나의 근본 원인을 식별했습니다.
- 의사 결정 트리(라인 91+)에서 첫 번째로 일치하는 패턴을 적용했습니다.
- 시뮬레이터가 아닌 실제 기기에서 패턴을 테스트했습니다.
- [ ]
...
[번역을 위해 잘림]