UIKit 애니메이션 디버깅
개요
CAAnimation 문제는 특정 조건에서 완료 핸들러 누락, 잘못된 타이밍, 또는 버벅임으로 나타납니다. 핵심 원칙 CAAnimation 문제의 90%는 CATransaction 타이밍, 레이어 상태, 또는 프레임 속도 가정 때문이며, Core Animation 자체의 버그가 아닙니다.
위험 신호 — CAAnimation 문제 의심
다음 중 하나라도 보이면, 기기 동작이 아닌 애니메이션 로직을 의심하세요:
- 시뮬레이터에서는 완료 핸들러가 실행되지만 기기에서는 실행되지 않음
- 애니메이션 지속 시간(0.5초)이 시각적 지속 시간(1.2초)과 일치하지 않음
- 스프링 애니메이션이 iPhone 15 Pro에서는 올바르게 보이지만 구형 기기에서는 버벅임
- 제스처와 애니메이션을 함께 사용할 때 버벅임 발생 (각각 따로는 정상)
- 완료 핸들러에서
[weak self]를 사용했지만 확실하지 않음 - ❌ 금지: "실제 발생하는 현상과 일치하도록" 지속 시간/값을 하드코딩하는 것
- 이는 다른 하드웨어를 사용하는 사용자에게 기기별 버그를 전달합니다.
- 이를 "임시 수정" 또는 "충분히 괜찮음"이라고 합리화하지 마십시오.
중요한 차이점 시뮬레이터는 종종 타이밍 문제를 숨깁니다(60Hz만 지원, 스로틀링 없음). 실제 기기는 이를 드러냅니다(가변 프레임 속도, CPU 스로틀링, 백그라운드 압력). 필수: 출시 전에 반드시 실제 기기(지원되는 가장 오래된 모델)에서 테스트하세요.
필수 첫 단계
항상 이 단계를 먼저 실행하세요 (코드를 변경하기 전에):
// 1. 완료가 실행되는지 확인
animation.completion = { [weak self] finished in
print("🔥 완료 실행됨: finished=\(finished)")
guard let self = self else {
print("🔥 self가 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("경과 시간: \(Date().timeIntervalSince(startTime))") // 실제
}
// 3. 활성화된 애니메이션 확인
if let keys = layer.animationKeys() {
print("활성 애니메이션: \(keys)")
for key in keys {
if let anim = layer.animation(forKey: key) {
print("\(key): 지속 시간=\(anim.duration), 제거됨=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. 레이어 상태 확인
print("레이어 속도: \(layer.speed)") // != 1.0이면 타이밍이 조정됨
print("레이어 시간 오프셋: \(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 문으로 add() 전에 완료가 설정되었는지 확인 (라인 33)
- 완료가 실행되지만 타이밍이 잘못된 경우에만 패턴 2로 진행
-
그런 다음 패턴 2 (CATransaction 지속 시간 불일치)
- 완료가 실행되지만 경과 시간이 선언된 지속 시간과 다른 경우에만
- 필수 첫 단계의 로그 확인 (라인 40-47)
-
그런 다음 패턴 3 (isRemovedOnCompletion)
- 애니메이션이 완료되지만 시각적 상태가 되돌려지는 경우에만
-
패턴 4-7 특정 증상에 따라 적용 (의사 결정 트리 라인 91+ 참조)
금지
- ❌ 여러 패턴을 동시에 적용 ("패턴 2와 패턴 4를 함께 시도해보자")
- ❌ "이미 그게 아닌 걸 알고 있어"라며 패턴 1을 건너뜀
- ❌ 각 패턴이 왜 필요한지 이해하지 않고 결합함
- ❌ 패턴을 무작위로 시도하고 하나가 작동하길 바람
패턴 1: 완료 핸들러 기본
❌ 잘못됨 (애니메이션 추가 후 핸들러 설정)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ 너무 늦음!
print("완료")
}
✅ 올바름 (추가 전 핸들러 설정)
animation.completion = { [weak self] finished in
print("🔥 애니메이션 완료: \(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: 완료 핸들러에서 약한 참조 (필수)
❌ 금지 (강한 참조는 순환 참조를 만듦)
anim.completion = { finished in
self.property = "value" // ❌ 순환 참조 보장됨
}
✅ 필수 (항상 약한 참조 사용)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "value" // 안전하게 접근
}
왜 이것이 필수인가 (선택 사항이 아님)
- CAAnimation은 완료 핸들러가 애니메이션이 완료될 때까지 살아 있도록 유지합니다.
- 완료 핸들러는 self를 강하게 캡처합니다(명시적으로 약하게 하지 않는 한).
- 순환 참조가 생성됩니다: 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] 사용 |
30분 후에도 막혔을 때
애니메이션을 30분 넘게 수정해도 해결되지 않았다면:
중단하세요. 다음 중 하나일 가능성이 높습니다.
- 필수 단계를 건너뛰었습니다 (가장 일반적)
- 진단 출력을 잘못 해석했습니다.
- 증상에 잘못된 패턴을 적용했습니다.
- Instruments 프로파일링이 필요한 5%의 예외적인 경우에 해당합니다.
"스킬이 작동하지 않았다"고 주장하기 전 필수 체크리스트
- 필수 첫 단계의 4가지 진단 블록을 모두 실행했습니다 (라인 28-63)
- 진단의 정확한 출력(로그, print 문)을 붙여넣었습니다.
- "이를 통해 알 수 있는 것"(라인 66-72)에서 하나의 근본 원인을 식별했습니다.
- 의사 결정 트리(라인 91+)에서 첫 번째로 일치하는 패턴을 적용했습니다.
- 시뮬레이터가 아닌 실제 기기에서 패턴을 테스트했습니다.
- 수정이 작동했음을 보여주는 print 문/로그로 패턴을 확인했습니다.
모든 항목을 확인했지만 여전히 깨진 경우
- Instruments > Core Animation으로 프로파일링해야 합니다.
- 시간 비용: 30-60분 (예외적인 경우에는 불가피함)
- 하드코딩, asyncAfter, 또는 "일단 출시하고 보기"는 금지됩니다.
- 해결 방법을 추가하기 전에 지침을 요청하세요.
시간 비용 투명성
- 패턴 1: 2-5분