증상: React Native 0.88 프로젝트가 iOS 시뮬레이터에서 실행되지 않습니다. 해결: iOS 빌드와 검수에는 macOS와 Xcode를 준비하고, 새 프로젝트는 0.88 템플릿으로 시작하세요. 기존 프로젝트는 공식 변경 사항을 비교한 뒤 SceneDelegate 수정 여부를 판단하면 됩니다. React Native 0.88은 2026년 10월 19일 공식 발표됐으며, iOS 27 SDK를 쓰는 경우에는 별도의 장면 수명 주기 조건도 확인해야 합니다. (공식 발표문)
이 안내는 React Native를 배우면서 첫 프로젝트를 iOS 시뮬레이터에서 실행하려는 학생을 위한 글입니다. 기존 수업 프로젝트를 0.88로 올리려는 학습자, Windows나 학교 컴퓨터만 사용할 수 있어 macOS와 Xcode가 필요한 시점을 판단하려는 경우에도 참고할 수 있습니다.
시작 지점부터 구분하기
새 프로젝트와 기존 프로젝트는 같은 절차로 다루지 마세요. 새 프로젝트는 현재 공식 템플릿을 기준으로 만들고, 기존 프로젝트는 먼저 현재 버전과 네이티브 설정을 보존한 뒤 차이를 비교해야 합니다.
React Native에는 화면과 동작을 작성하는 자바스크립트 코드뿐 아니라 iOS용 네이티브 프로젝트도 들어 있습니다. 시뮬레이터에서 iOS 앱을 빌드하고 실행하는 일은 자바스크립트 개발 서버를 켜는 것과 다릅니다. iOS 네이티브 빌드에는 macOS와 Xcode가 필요하며, 도구 요구 사항은 공식 환경 설정 안내에서 확인하세요.
시작 전에 아래 항목을 정리해 두면 강의 안내와 실제 프로젝트 설정이 어긋나는 일을 줄일 수 있습니다.
- 새 프로젝트를 만들지, 기존 프로젝트를 업그레이드할지 구분합니다.
- 프로젝트가 사용하는 React Native 버전과 의존성 관리 방식을 확인합니다.
- 수업에서 요구하는 결과가 앱 화면 실행인지, iOS 기기 설치용 빌드인지 확인합니다.
- 프로젝트 폴더와 네이티브 설정을 별도 위치에 복사해 되돌릴 수 있게 합니다.
실행 환경과 프로젝트 준비
Windows에서 자바스크립트 코드를 편집하거나 일부 개발 서버를 실행할 수는 있어도, 그 자체로 iOS 시뮬레이터 빌드가 완료되지는 않습니다. 브라우저에서 개발 서버가 열린 상태와 Xcode가 iOS 앱을 빌드해 시뮬레이터에서 실행한 상태는 서로 다른 검수 단계입니다.
새 프로젝트라면 공식 시작 안내에서 현재 생성 절차를 확인하고, 공식 템플릿으로 생성한 iOS 폴더를 기준으로 진행하세요. 0.88 템플릿에는 SceneDelegate 경로가 포함되어 있으므로, 예전 강의의 AppDelegate 설정을 그대로 복사하기보다 생성된 파일 구조를 먼저 살펴보는 편이 안전합니다. 0.88의 변경 사항은 앞서 연결한 공식 발표문에서도 확인할 수 있습니다.
기존 프로젝트는 바로 생성 명령이나 의존성 버전을 바꾸지 마세요. 수업에서 지정한 버전, 잠금 파일, iOS 폴더의 변경 사항을 함께 보관해야 문제가 생겼을 때 원래 상태로 돌아갈 수 있습니다.
새 프로젝트에서 SceneDelegate 확인하기
새 프로젝트는 SceneDelegate를 손봐야 하나요?
대부분의 경우 새 프로젝트에서는 템플릿이 만든 네이티브 구성을 출발점으로 삼으면 됩니다. React Native 0.88은 SceneDelegate 수명 주기 지원을 추가했지만, 이것이 새 프로젝트마다 직접 파일을 고쳐야 한다는 뜻은 아닙니다. 먼저 생성된 iOS 프로젝트에 어떤 구성이 들어 있는지 확인하고, 오래된 튜토리얼의 설정을 무조건 덧붙이지 마세요.
SceneDelegate와 UIScene은 iOS 앱의 화면 창과 실행 상태를 관리하는 장면 기반 수명 주기와 관련된 구성입니다. 쉽게 말하면 앱이 켜지고 화면에 나타나는 흐름을 운영체제에 알려주는 부분입니다. iOS 27 SDK를 사용하는 경우에는 장면 기반 수명 주기 요구 사항을 살펴봐야 하며, 0.88의 공식 안내에는 단일 장면 지원 범위도 명시되어 있습니다. 앱에 필요한 장면 구성은 Apple의 장면 수명 주기 안내와 장면 구성 문서에서 확인하세요.
주의: AppDelegate, Info.plist, URL 콜백은 프로젝트와 사용 중인 라이브러리에 따라 연결 방식이 다를 수 있습니다. 튜토리얼의 일부 설정만 복사하지 말고, 템플릿과 실제 파일의 차이를 확인한 뒤 변경하세요.
기존 프로젝트의 업그레이드 차이 살펴보기
기존 프로젝트는 0.88로 올리기 전에 무엇을 확인하나요?
먼저 프로젝트의 현재 React Native 버전을 확인하고, 공식 Upgrade Helper에서 기존 버전과 0.88 사이의 변경 사항을 비교하세요. 안내된 차이를 프로젝트 파일과 대조하고, 이미 적용된 변경이나 수업에서 별도로 수정한 네이티브 코드를 구분합니다.
React Native 공식 발표는 0.88에 사용자에게 보이는 기능의 파괴적 변경이 없다고 설명합니다. 하지만 이를 “모든 서드파티 라이브러리와 기존 iOS 프로젝트를 검사하지 않아도 된다”는 뜻으로 받아들이면 안 됩니다. 네이티브 의존성, AppDelegate와 SceneDelegate의 진입 흐름, Info.plist의 장면 선언, URL 콜백 전달이 프로젝트에서 어떻게 구성됐는지 확인하세요. 특히 iOS 27 SDK를 채택할 계획이라면 장면 수명 주기 요건과 0.88의 단일 장면 지원 범위를 함께 검토해야 합니다.
확인 결과를 기록할 때는 파일 이름만 적지 말고, 어떤 설정이 바뀌었는지와 수정 이유도 남기세요. 업그레이드 뒤 빌드가 실패하면 수업 코드 오류인지 네이티브 설정 차이인지 구분하는 데 도움이 됩니다.
첫 시뮬레이터 실행과 오류 분리
React Native 공식 iOS 시뮬레이터 실행 안내를 따라 다음 순서로 진행하세요.
- macOS에서 Xcode를 열고, 공식 환경 안내에 맞는 개발 도구가 준비됐는지 확인합니다.
- 프로젝트 루트에서 강의가 지정한 패키지 관리자를 사용해 의존성을 설치합니다. 잠금 파일이 있다면 이를 보존하고 임의로 다른 패키지 관리 방식으로 바꾸지 않습니다.
- iOS 네이티브 의존성이 필요한 프로젝트라면 강의 안내와 프로젝트 설정에 따라 CocoaPods 의존성을 준비합니다.
- Xcode에서 프로젝트에 맞는 iOS 워크스페이스를 엽니다. CocoaPods를 쓰는 프로젝트라면 생성된 워크스페이스를 기준으로 실행합니다.
- Xcode에서 사용할 시뮬레이터를 선택하고 앱을 빌드한 뒤 실행합니다. 또는 공식 실행 문서의 절차에 따라 프로젝트 루트에서 iOS 실행 명령을 사용합니다.
- 앱 화면이 열린 뒤 강의 과제의 핵심 동작을 확인하고, 사용한 React Native 버전과 Xcode 설정, 실행 결과를 기록합니다.
실패 위치에 따라 점검 지점도 다릅니다.
- 빌드가 끝나지 않음: Xcode 오류와 네이티브 의존성 설치 상태를 먼저 확인합니다. Metro가 켜져 있어도 iOS 빌드가 성공한 것은 아닙니다.
- 빌드는 됐지만 앱이 열리지 않음: Xcode에서 선택한 실행 대상과 앱 시작 단계의 오류를 확인합니다.
- 앱은 열리지만 화면이 잘못됨: 자바스크립트 오류, 화면 초기화 로직, 네트워크 요청을 분리해서 살펴봅니다.
Mac이 없을 때 검수 경로 결정하기
Mac이 없어도 iOS 프로젝트 검수를 끝낼 수 있나요?
Windows 컴퓨터만으로 코드 편집과 자바스크립트 학습을 이어갈 수는 있지만, Xcode를 이용한 iOS 시뮬레이터 빌드는 macOS 환경에서 해야 합니다. 브라우저나 Metro 화면만으로는 iOS 네이티브 빌드와 시뮬레이터 실행을 확인할 수 없습니다. 앞서 안내한 공식 시뮬레이터 문서에서 실행 조건을 먼저 확인하세요.
아래 항목을 체크하면 지금 필요한 환경을 판단하기 쉽습니다.
- [ ] 과제에 iOS 시뮬레이터 실행 또는 iOS 네이티브 빌드가 포함되어 있나요?
- [ ] 현재 컴퓨터에서 macOS와 Xcode를 사용할 수 있나요?
- [ ] 새 프로젝트라면 0.88 템플릿을 기준으로 만들었나요?
- [ ] 기존 프로젝트라면 Upgrade Helper로 차이를 비교하고 원본을 보관했나요?
- [ ] SceneDelegate, Info.plist, URL 콜백 변경이 필요한지 프로젝트별로 확인했나요?
- [ ] Metro 실행과 iOS 앱 빌드 성공을 따로 확인했나요?
iOS 검수가 과제에 없다면 지금 사용하는 컴퓨터에서 자바스크립트 학습을 계속하고, Mac 환경이 필요한 과제 전에 준비해도 됩니다. 반대로 시뮬레이터 실행이 필수라면 Windows만으로 끝내려 하지 말고 macOS와 Xcode를 쓸 수 있는 경로를 확보하세요.
Windows에서만 작업하면 iOS 빌드와 시뮬레이터 검수 단계가 막히고, 학교 컴퓨터에 의존하면 사용 가능 시간이나 설치 권한에 제약이 생길 수 있습니다. 실물 Mac을 바로 구입하는 방법은 장기간 계속 사용할 때 합리적일 수 있지만, 과제 검수만 필요하다면 초기 장비 구입 부담도 따져봐야 합니다. 필요한 기간에만 macOS 환경을 확보하려는 학생이라면, MACCOME의 원격 Mac 이용 안내에서 연결 방식과 이용 조건을 확인할 수 있습니다. 단기 검수에는 대안이 될 수 있지만, 장시간 이어지는 상시 작업이나 물리 기기 연결이 필요한 경우에는 실제 Mac을 소유하는 편이 맞을 수 있습니다. 학생 과제에 쓸 환경을 알아보는 중이라면 서울 원격 Mac 안내도 비교한 뒤 필요한 조건에 맞춰 선택하세요.