Expo Go 네이티브 모듈 오류의 원인이 앱에 없는 네이티브 코드라면, 같은 패키지를 다시 설치하기보다 development build로 전환하세요. 윈도우에서도 코드를 편집하고 EAS Build로 클라우드 빌드를 요청할 수 있지만, iOS 시뮬레이터는 맥에서 실행해야 합니다.

이 안내는 Expo나 React Native 수업 프로젝트를 만들다가 처음 원시 모듈 오류를 만난 학생을 위한 글입니다.
맥이 없거나 학교 컴퓨터만 쓸 수 있어도, 빌드와 테스트를 어떤 경로로 나눠야 하는지 확인할 수 있습니다.

오류 메시지부터 나눠서 확인하세요

Expo Go는 프로젝트에 설치한 모든 네이티브 코드를 자동으로 받아 실행하는 앱이 아닙니다. Expo Go 안에 미리 포함된 라이브러리 범위가 정해져 있습니다. 프로젝트 의존성으로 자바스크립트 패키지를 설치해도, 그 패키지에 필요한 네이티브 구현이 Expo Go에 없다면 앱에서 모듈을 찾지 못할 수 있습니다. Expo Go가 지원하는 라이브러리 안내와 Expo Go 및 개발 빌드 설명을 대조하세요.

보이는 증상 먼저 확인할 부분 다음 조치
패키지 설치 명령이 실패합니다 네트워크, 패키지 이름, 프로젝트의 의존성 설정 설치 오류를 해결한 뒤 다시 실행합니다
앱은 시작하지만 화면에서 오류가 납니다 오류가 자바스크립트 코드에서 발생했는지 확인합니다 오류 위치와 호출한 코드를 살펴봅니다
모듈을 찾지 못하거나 네이티브 구현이 없다고 나옵니다 라이브러리가 Expo Go에서 지원되는지, 별도 네이티브 설정이 필요한지 확인합니다 미포함 네이티브 코드가 원인이면 개발 빌드로 바꿉니다

패키지 설치 오류, 앱 코드 오류, 네이티브 구현 누락은 해결 방법이 서로 다릅니다. Expo Go 자체를 다시 설치하거나 캐시를 지우는 작업은 세 번째 경우의 빠른 해결책이 아닙니다. 먼저 오류 문구와 라이브러리 공식 문서의 설치 및 설정 조건을 확인하세요. 네이티브 코드나 설정이 필요한 라이브러리라면 Expo의 네이티브 코드 맞춤 안내도 함께 확인합니다.

첫 단계: development build가 필요한지 판단하세요

development build는 프로젝트에 필요한 네이티브 의존성을 담아 만든 개발용 앱입니다. Expo Go에 플러그인을 추가하는 방식이 아닙니다. 개발 빌드 소개에 나온 용도와 현재 프로젝트의 의존성을 비교하세요.

선택 경로 이런 경우에 맞습니다 알아둘 제한
Expo Go 계속 사용 포함된 라이브러리로 화면과 자바스크립트를 연습합니다 Expo Go에 없는 네이티브 코드는 추가할 수 없습니다
development build 사용 프로젝트에 필요한 네이티브 의존성이나 설정을 시험합니다 네이티브 부분이 바뀌면 새 빌드가 필요할 수 있습니다
EAS Build 사용 윈도우에서 iOS 앱 빌드를 클라우드에 요청합니다 클라우드 빌드와 맥의 로컬 시뮬레이터는 다른 경로입니다

현재 의존성이 Expo Go에서 지원되고 수업 목표가 자바스크립트 기초라면 Expo Go로 계속 연습해도 됩니다. 반면 프로젝트가 필요한 네이티브 모듈을 Expo Go가 제공하지 않는다면 development build를 준비하세요. Expo의 개발 빌드 사용 안내를 읽고, 현재 프로젝트에 맞는 절차를 확인할 수 있습니다.

네이티브 변경 뒤에는 다시 빌드하세요

개발 빌드를 만들었는데 새 모듈이 여전히 동작하지 않는다면, 자바스크립트 패키지만 설치한 상태인지 확인하세요. 앱에 네이티브 라이브러리나 네이티브 설정 변경이 반영되려면 변경 내용을 포함한 개발 빌드가 필요할 수 있습니다. 반대로 화면 문구나 자바스크립트 로직만 바꾼 경우에는 네이티브 앱을 다시 만드는 문제와 구분해야 합니다.

바꾼 내용 확인할 것 판단
화면, 문구, 자바스크립트 동작 앱에서 변경 사항이 다시 반영되는지 반영되지 않으면 실행 환경과 프로젝트 저장 상태를 점검합니다
네이티브 의존성 추가 빌드에 새 의존성이 포함됐는지 기존 개발 빌드라면 새 빌드가 필요한지 확인합니다
네이티브 설정 변경 설정이 빌드 결과에 적용됐는지 변경 이후 만든 앱으로 다시 시험합니다

Expo Go와 개발 빌드의 차이를 혼동하면 같은 패키지를 반복 설치하거나 캐시 삭제에 시간을 쓰기 쉽습니다. 빌드용 환경 변수나 비밀 값이 필요하다면 EAS 환경 변수 문서를 따르세요. 계정 정보와 프로젝트 비밀 값은 공개 저장소에 올리거나 다른 사람과 공유하지 마세요.

맥이 없을 때는 빌드와 실행 기기를 따로 고르세요

윈도우 노트북에서 코드를 편집하는 일, 클라우드에서 iOS 앱을 빌드하는 일, 실제 기기나 시뮬레이터에서 실행하는 일은 서로 다른 작업입니다. EAS Build는 iOS 클라우드 빌드 경로를 제공하지만, 이를 사용한다고 윈도우 컴퓨터에서 iOS 시뮬레이터가 실행되는 것은 아닙니다. EAS 시뮬레이터 빌드 안내와 Expo의 iOS 시뮬레이터 안내에서 빌드 대상과 실행 조건을 확인하세요.

경로 무엇을 할 수 있나요? 선택 전에 확인할 점
Expo Go와 현재 기기 지원되는 기능으로 기본 수업을 진행합니다 필요한 모듈이 Expo Go에 포함돼야 합니다
EAS Build와 실제 iPhone 클라우드에서 만든 iOS 앱을 기기에서 시험합니다 계정, 앱 설치, 수업의 기기 요구 사항을 확인합니다
맥과 iOS 시뮬레이터 맥의 시뮬레이터에서 개발 빌드를 실행하고 화면을 확인합니다 시뮬레이터는 macOS에서 실행해야 합니다

수업이 화면 설계와 자바스크립트 동작 확인까지만 요구한다면 지금 가진 기기로 진행할 수 있는지 먼저 확인하세요. 제출 조건에 시뮬레이터 화면이나 Xcode 디버깅이 있다면 학교 맥 사용 가능 여부를 확인하고, 해당 작업에 맞는 macOS 환경을 마련해야 합니다. 맥이 필요한 과제라면 원격 맥 사용 환경을 살펴보고, 실제 수업 일정과 연결 방식이 맞는지 확인하세요.

중간 점검: 자주 막히는 지점을 질문으로 정리하세요

프로젝트의 모듈을 Expo Go에서 찾지 못하는 이유는 무엇인가요?
프로젝트에 설치한 패키지와 Expo Go 앱에 포함된 네이티브 구현은 별개입니다. 공식 지원 목록에 없는 모듈이라면 패키지를 다시 설치하는 대신 개발 빌드가 필요한지 확인하세요.

어떤 시점에 Expo Go에서 development build로 바꾸면 되나요?
필요한 네이티브 라이브러리가 Expo Go에 없거나 네이티브 설정을 시험해야 할 때 전환합니다. 현재 라이브러리가 지원되고 자바스크립트만 연습한다면 Expo Go를 계속 써도 됩니다.

맥 없이 iOS development build를 만들 수 있나요?
윈도우에서 EAS Build로 클라우드 빌드를 요청할 수 있습니다. 다만 빌드가 끝나는 것과 윈도우에서 iOS 시뮬레이터를 실행하는 것은 다른 일입니다. 실제 기기 테스트나 맥 시뮬레이터 테스트가 과제에 필요한지 구분하세요.

iOS 시뮬레이터에서 개발 빌드를 어떻게 확인하나요?
시뮬레이터용으로 빌드했는지 확인한 뒤, 맥에서 앱을 실행하고 문제가 난 네이티브 모듈을 실제로 호출하세요. 앱 시작 여부만 보지 말고 화면 기능과 자바스크립트 변경 반영도 확인해야 합니다.

마지막 단계: 같은 수업 프로젝트로 끝까지 검사하세요

  • 프로젝트 파일과 변경한 설정을 저장합니다.
  • 오류가 난 라이브러리와 필요한 네이티브 설정을 다시 확인합니다.
  • 프로젝트의 네이티브 변경이 새 development build에 반영됐는지 확인합니다.
  • 앱이 목표 기기에서 시작되는지 확인하고, 문제가 난 모듈 기능을 직접 실행합니다.
  • 자바스크립트만 수정한 뒤 결과가 앱에 반영되는지 확인합니다.
  • 제출 기기와 화면 조건이 수업 요구 사항과 일치하는지 대조합니다.

앱이 켜지는 것만으로는 네이티브 모듈 오류가 해결됐다고 볼 수 없습니다. 문제의 기능까지 실행하고, 빌드 방식과 테스트 기기가 과제 조건에 맞는지 확인해야 합니다.

윈도우에서 코드 편집과 클라우드 빌드만 하면 되는 과제라면 맥을 준비할 필요가 없을 수 있습니다. 다만 시뮬레이터와 Xcode 확인이 요구되면 학교 컴퓨터의 이용 시간 제한이나 클라우드 빌드만으로는 부족한 부분이 생길 수 있습니다. 그런 조건에서 단기간 macOS 테스트 환경이 필요하다면 MACCOME의 맥 미니 대여 경로를 확인해 보세요. 원격 환경에서 프로젝트 연결과 수업 요구 사항을 충족할 수 있는지 먼저 살펴본 뒤 선택하면 됩니다.