iOS 27 UIScene 마이그레이션: 2026 앱 시작 실패를 어떻게 고칠까?

iOS 27 UIScene 마이그레이션 여부는 아이폰의 버전만 보고 판단하면 안 됩니다. 최종 Archive에 들어간 SDK와 Info.plist가 기준입니다. 다음 두 항목을 먼저 확인합니다.

• UIApplicationSceneManifest가 Info.plist에 있는지 확인합니다.
• application(_:configurationForConnecting:options:)가 유효한 장면 설정을 반환하는지 확인합니다.

Apple의 UIKit 문서는 기존 생명 주기에서 장면 기반 생명 주기로 옮길 때 설정, 창, 장면 이벤트를 함께 분리하도록 안내합니다. UIKit 장면 생명 주기 이전 문서

조건별 처리 기준

• 최종 Archive가 iOS 27 SDK로 만들어지고 장면 설정이 비어 있으면 즉시 이전합니다.
• 아직 출시 빌드가 이전 SDK를 사용하고, Xcode 27 검증만 필요한 경우에는 단기 이중 환경을 유지합니다.
• 최종 Archive가 새 SDK가 아니며 가까운 시점에 새 SDK로 빌드하지 않는다면 즉시 코드 변경 대신 검증 계획을 세울 수 있습니다.
• 단, 새 SDK를 사용해 출시할 계획이라면 마지막 조건에 오래 머물러서는 안 됩니다.

Apple은 오래된 SDK로 만든 빌드에는 이 시작 조건이 아직 적용되지 않는다고 설명했습니다. 그렇다고 출시용 도구를 계속 고정해도 된다는 뜻은 아닙니다. 새 SDK에서 시작하지 못하는 문제를 뒤로 미루는 것과 회귀 환경을 보존하는 것은 다른 작업입니다.

스토리보드 기반 앱

스토리보드 앱은 장면 설정과 화면 진입점을 따로 확인해야 합니다. 주 스토리보드가 장면 구성에 연결되지 않으면 시스템이 창을 만들었지만 화면 계층을 채우지 못할 수 있습니다. 반대로 코드와 설정에서 같은 창을 동시에 만들면 중복 초기화가 발생할 수 있습니다.

AppDelegate에는 프로세스 수준 초기화만 남깁니다. 분석 설정, 공통 서비스 준비, 푸시 등록처럼 앱 전체에 한 번 필요한 작업이 여기에 해당합니다. 화면 생성과 루트 화면 연결은 SceneDelegate의 장면 연결 시점에서 확인합니다.

Apple의 장면 지원 설정 문서에 맞춰 다음 순서로 확인합니다.

1. Info.plist의 Scene Manifest가 올바른 장면 설정을 가리키는지 확인합니다.
2. 주 스토리보드 이름과 장면 역할이 서로 맞는지 확인합니다.
3. AppDelegate에서 별도 UIWindow를 만드는 코드를 찾아 제거 여부를 검토합니다.
4. 냉간 시작 뒤 첫 화면이 표시되는지 확인합니다.
5. 전면과 배경 전환 뒤 같은 화면 상태가 복원되는지 확인합니다.

컴파일 성공만으로 통과 처리하면 안 됩니다. 설치 후 아이콘을 눌렀을 때 빈 화면이 없는지, 장면이 다시 연결될 때 초기화가 두 번 실행되지 않는지 확인해야 합니다.

순수 코드 UIKit 앱

순수 코드 앱은 scene(_:willConnectTo:options:)가 핵심 진입점입니다. 여기서 전달된 UIWindowScene에 UIWindow를 연결하고, 루트 뷰 컨트롤러를 설정한 뒤, 창을 표시해야 합니다. Apple의 UIScene API 문서는 장면이 앱 화면의 실행 단위라는 점을 설명합니다.

기존 코드에서 다음 패턴을 검색합니다.

• AppDelegate.window
• 전역 keyWindow
• 앱 시작 때 한 번만 실행된다고 가정한 화면 생성 함수
• 화면이 없는 상태에서 전역 창을 참조하는 서비스
• 모든 URL 처리를 AppDelegate 한 곳에서 끝내는 코드

화면을 만드는 함수 자체를 삭제할 필요는 없습니다. 다만 어느 장면의 창을 대상으로 하는지 전달해야 합니다. 여러 장면이 생길 수 있는 구조에서 전역 창을 반환하면 잘못된 화면에 URL이나 상태를 적용할 수 있습니다.

혼합 구조와 공통 서비스

혼합 앱은 스토리보드가 루트 화면을 만들고 코드가 추가 화면을 덧붙이는지부터 확인합니다. SceneDelegate에서 같은 루트 컨트롤러를 다시 만들면 로그인 상태나 내비게이션 스택이 사라질 수 있습니다.

공통 서비스는 장면과 화면에서 분리합니다. 네트워크 계층, 데이터 저장소, 인증 상태는 앱 수준에 둘 수 있지만, 선택된 탭이나 현재 문서처럼 화면에 종속된 값은 장면별로 관리해야 합니다. Apple의 UIKit 이전 기술 문서는 이 분리를 확인하면서 기존 구조를 단계적으로 옮기는 방법을 다룹니다.

깊은 연결, Universal Link, 푸시 알림, 제3자 로그인은 단순한 아이콘 시작만으로 시험할 수 없습니다. 프로세스가 새로 시작되는 경우와 이미 실행 중인 장면이 다시 활성화되는 경우의 입력 경로가 다릅니다.

connectionOptions에는 장면 연결을 유발한 URL, 사용자 활동, 알림 관련 정보가 전달될 수 있습니다. ConnectionOptions 문서를 기준으로 입력을 분리해 기록합니다.

• 앱이 종료된 상태에서 깊은 연결로 시작합니다.
• 배경 상태의 앱을 깊은 연결로 깨웁니다.
• 이미 활성화된 앱에 같은 링크를 전달합니다.
• 종료된 앱을 푸시 알림으로 시작합니다.
• 로그인 앱에서 돌아오는 URL Scheme을 확인합니다.
• Universal Link가 예상 화면으로 이동하는지 확인합니다.

로그에는 프로젝트 이름, Bundle ID, Team ID, URL, 계정, 호스트 주소, 경로와 알림 내용을 그대로 남기지 않습니다. 탈취 가능한 값을 가린 테스트 입력을 사용합니다. 특히 실제 사용자 토큰과 푸시 내용은 저장소와 원격 세션 기록에서 제거해야 합니다.

UIScene을 도입한다고 곧바로 다중 창 기능을 공개할 필요는 없습니다. 다만 단일 화면만 존재한다고 가정한 전역 상태는 다시 살펴봐야 합니다. iPad의 창 이동, Stage Manager, 외부 화면, Mac Catalyst에서 장면이 사라졌다가 다시 연결되는 경로가 있기 때문입니다.

외부 화면 역할이나 문서 앱 처리를 오래된 예제만 보고 확대 개편하지 마십시오. 기본 이전을 먼저 끝내고, 실제 요구가 있는 장면 상태와 자원 해제만 최신 UIScene 안내에 맞춰 추가합니다.

생산 맥의 Xcode를 바로 바꾸는 방법은 빠르지만 회귀 비용이 큽니다. 반대로 원격 맥에 격리된 환경을 만들면 같은 소스와 같은 인증 흐름을 비교하기 쉽습니다. 다만 원격 화면 접속만 확인해서는 안 됩니다. 실제 설치와 Archive까지 확인해야 합니다.

현재 사용 중인 원격 맥 환경 선택 화면을 확인할 때도 가격이나 장비 이름만 보지 마십시오. Xcode 설치 방식, 재접속 뒤 작업 상태, 호스트 재시작 후 자동화 작업의 복구 여부가 더 중요합니다.

다음 순서는 생산 맥을 건드리기 전에 실행합니다.

• [ ] 비공개 저장소 복사본에서 프로젝트명, 식별자, 계정, 주소와 로그를 탈취 불가능한 값으로 바꿉니다.
• [ ] 이전 브랜치와 이전 후 브랜치를 분리하고 각 브랜치의 커밋을 기록합니다.
• [ ] Xcode 27 환경에서 Build와 Test를 실행한 뒤 실패 로그를 저장합니다.
• [ ] 앱을 설치하고 아이콘 시작, 냉간 시작, 전후면 이동, 장면 재연결을 확인합니다.
• [ ] 종료 상태, 배경 상태, 활성 상태에서 깊은 연결과 푸시 경로를 각각 실행합니다.
• [ ] Archive를 생성하고 서명, 설치, 실제 시작까지 확인합니다.
• [ ] 원격 세션을 끊었다가 다시 연결하고 작업 산출물과 로그가 남는지 확인합니다.
• [ ] 호스트를 재시작한 뒤 수동 작업과 무인 빌드가 다시 실행되는지 확인합니다.
• [ ] 모든 결과를 통과, 실패, 재현 조건으로 나눠 보관합니다.
• [ ] 이전 후 빌드가 통과하기 전까지 생산 맥의 기본 Xcode를 바꾸지 않습니다.

조건 분기

• 최종 Archive가 새 SDK이고 시작이 실패하면, 즉시 UIScene 이전을 진행하고 이전 SDK 빌드로만 임시 회귀합니다.
• 시작은 되지만 깊은 연결이나 푸시가 실패하면, 창 생성 코드를 더 고치기보다 connectionOptions와 활성 장면 콜백을 먼저 추적합니다.
• 냉간 시작은 통과하지만 전후면 전환에서 상태가 사라지면, 장면별 상태 복원과 전역 상태 의존을 분리합니다.
• 모든 검증이 통과하고 Archive 설치까지 재현되면, 그때 생산 도구 체계의 기본 버전을 바꿉니다.
• 원격 호스트 재시작 뒤 무인 빌드가 복구되지 않으면, 코드 이전은 통과했더라도 상시 패키징 환경 전환을 보류합니다.

iOS 27에서 UIScene 생명 주기를 요구하는 이유는 무엇인가요?

기준은 설치된 기기의 운영 체제가 아니라 앱을 빌드한 SDK입니다. Apple이 확인한 범위에서는 iOS 27 SDK로 빌드한 UIKit 앱이 UIScene 기반 생명 주기를 사용하지 않으면 시작되지 않을 수 있습니다. 실제 Archive의 SDK와 Info.plist를 확인하고, 오래된 SDK 빌드는 잠시 되돌리는 수단으로만 사용해야 합니다.

AppDelegate만 있는 오래된 UIKit 앱은 어떻게 바꾸나요?

Scene Manifest를 등록한 뒤 장면이 연결되는 시점에 창과 루트 화면을 준비합니다. 스토리보드 앱은 장면 설정에 주 스토리보드를 연결하고, 순수 코드 앱은 scene(_:willConnectTo:options:)에서 UIWindowScene을 받아 창을 연결합니다. 기존 AppDelegate.window와 전역 keyWindow 참조도 함께 찾아야 합니다.

UIScene 이전 뒤 깊은 연결과 푸시 시작 처리는 어디에 두나요?

프로세스 시작과 장면 연결을 같은 사건으로 처리하지 않습니다. URL, Universal Link, 알림 응답과 사용자 활동은 ConnectionOptions 및 장면 생명 주기 콜백에서 확인합니다. 앱이 종료된 상태, 배경 상태, 활성 상태에서 입력 경로가 달라지므로 세 상태를 모두 시험해야 합니다.

오래된 Xcode를 잠시 사용하면 UIScene 시작 실패를 피할 수 있나요?

오래된 SDK 빌드에는 새 시작 조건이 아직 적용되지 않는다는 설명이 있습니다. 그러나 이는 회귀 수단이지 해결책이 아닙니다. 출시 빌드가 Xcode 27과 iOS 27 SDK를 사용한다면 UIScene 이전을 끝내야 합니다. 기존 도구 체계는 새 코드가 실패했을 때 되돌릴 목적으로만 보존합니다.

원격 맥에서 이전 전후 iOS 빌드를 함께 검증하려면 어떻게 하나요?

생산 맥을 바로 변경하지 말고 원격 맥에 비공개 복사본과 별도 Xcode 27 환경을 준비합니다. 이전 전과 이전 후 브랜치에서 Build, Test, Archive, 설치와 실제 시작을 각각 기록합니다. 깊은 연결, 푸시, 전후면 이동, 재접속과 호스트 재시작까지 통과한 뒤에만 생산 도구 체계를 바꿉니다.

생산 맥 한 대에서 바로 Xcode 27로 바꾸면 장점은 단순합니다. 하지만 실패 시 기존 배포 작업과 새 이전 작업이 같은 기계에서 충돌합니다. 인증서와 캐시를 함께 건드릴 위험도 있고, 원격 재현 없이 로그를 다시 모으기도 어렵습니다. 반대로 원격 맥은 접속 지연과 환경 초기화 절차를 관리해야 하며, 물리 장치 연결이 필요한 테스트에는 별도 계획이 필요합니다.

따라서 장기간 같은 무거운 빌드를 한 대에서 계속 실행하고 물리 장치를 직접 연결해야 한다면 자체 맥이 더 적합할 수 있습니다. 생산 맥을 멈출 수 없고, UIScene 이전과 Xcode 27 Archive를 먼저 격리 검증해야 한다면 CALMVPS의 원격 맥이 더 안전한 중간 단계가 됩니다. 맥 렌탈 요금과 제공 조건을 확인한 뒤, 비공개 프로젝트를 복제해 시작·링크·푸시·Archive 검증에만 사용하십시오. 통과한 뒤 생산 환경을 바꾸면 회귀 시 되돌릴 경로도 남습니다.