빠른 해결책
먼저 이것들을 시도해 보세요. 대부분의 문제를 해결할 수 있습니다.| 문제 | 시도할 것 |
|---|---|
| 휴대폰에 변경 사항이 표시되지 않음 | 휴대폰을 흔들어 Expo 메뉴를 열고 Reload를 탭하세요 |
| 미리보기에 변경 사항이 표시되지 않음 | 콘솔에서 R을 눌러 다시 번들링하세요 |
| 앱이 멈추거나 응답하지 않음 | 콘솔에서 앱을 중지하고 다시 시작하세요 |
흔한 문제
변경 사항이 기기에 나타나지 않습니다
변경 사항이 기기에 나타나지 않습니다
변경했지만 휴대폰에서 보이지 않을 때:
- 휴대폰을 흔들어 Expo 개발자 메뉴를 엽니다.
- Reload를 탭해 번들을 다시 다운로드합니다.
Expo Go에서 빨간 오류 화면이 나타납니다
Expo Go에서 빨간 오류 화면이 나타납니다
빨간 오류 화면은 보통 JavaScript 오류나 누락된 모듈을 나타냅니다. 오류 메시지를 읽어보세요. 대개 특정 파일과 줄을 가리킵니다.흔한 원인:
- 패키지가 설치되지 않았거나 잘못된 버전임
- 모듈이 웹에서는 동작하지만 네이티브에서는 동작하지 않음(또는 반대)
- 코드에 구문 오류가 있음
- 오류 메시지를 주의 깊게 읽으세요. 대개 정확히 무엇이 잘못되었는지 알려줍니다.
- 메시지를 공유해 Agent에게 오류 수정을 도와달라고 요청하세요.
- 오류가 특정 패키지를 언급한다면 종속성을 다시 설치해 보세요(참고: 패키지 다시 설치하기).
앱이 웹에서는 동작하지만 휴대폰에서는 충돌합니다(또는 반대)
앱이 웹에서는 동작하지만 휴대폰에서는 충돌합니다(또는 반대)
일부 패키지나 기능은 플랫폼마다 다르게 동작합니다. React Native는 iOS, Android, 웹이라는 세 가지 대상으로 컴파일됩니다. 웹에서 동작하는 라이브러리가 네이티브를 지원하지 않거나 다른 구성이 필요할 수 있습니다.시도할 것:
- 패키지 문서에서 해당 플랫폼을 지원하는지 확인하세요.
- Agent에게 물어보세요: “이 패키지가 Expo Go와 호환되나요?”
- 모바일에서 지원되지 않는 기능이라면 해당 기능을 서버로 옮기는 것을 고려하세요.
QR 코드가 스캔되지 않거나 앱이 연결되지 않습니다
QR 코드가 스캔되지 않거나 앱이 연결되지 않습니다
네트워크를 확인하세요:
- 휴대폰과 컴퓨터가 동일한 WiFi 네트워크에 있어야 합니다
- 일부 회사나 공공 네트워크는 연결을 차단합니다
npx expo start --tunnel을 실행하세요.Expo Go를 다시 시작하세요:
스캔하기 전에 Expo Go를 완전히 종료하고 다시 여세요.빌드에 시간이 오래 걸립니다
빌드에 시간이 오래 걸립니다
첫 빌드는 캐시가 없기 때문에 항상 더 느립니다. 이후 빌드는 더 빨라야 합니다.빌드 시간에 영향을 미치는 요소:
- 프로젝트에 있는 패키지 수
- 캐시를 지운 후 첫 실행
- 패키지를 다운로드할 때의 네트워크 속도
모듈을 찾을 수 없다는 오류
모듈을 찾을 수 없다는 오류
“Unable to resolve module” 또는 “Module not found”가 표시될 때:
- 패키지가 설치되지 않았을 수 있습니다 — Agent에게 설치를 요청하세요.
- 패키지가 설치되어 있지만 캐시가 오래되었을 수 있습니다 — 캐시를 지우세요.
- 패키지가 존재하지 않거나 이름이 잘못되었을 수 있습니다 — 패키지 이름을 확인하세요.
디버깅 명령
빠른 해결책이 통하지 않을 때, 이 명령들은 다양한 캐시와 상태를 초기화하는 데 도움이 됩니다. Shell에서 실행하세요.Metro 캐시 지우기
Metro는 React Native 코드를 컴파일하는 번들러입니다. 캐시를 지우면 새로 빌드하게 됩니다. 셸에서 다음을 실행하세요.패키지 다시 설치하기
모듈 오류나 버전 불일치가 보인다면, 패키지를 다시 설치하는 것이 대개 도움이 됩니다. 셸에서 다음을 실행하세요.package.json을 기준으로 처음부터 다시 설치됩니다.
프로젝트가 다른 패키지 관리자(예:
bun 또는 pnpm)를 사용한다면, 적절한 설치 명령을 사용하세요: bun install 또는 pnpm install.버전 불일치 확인하기
Expo Doctor는 패키지 간 버전 불일치와 같은 흔한 문제를 프로젝트에서 스캔합니다. 셸에서 다음을 실행하세요.전체 초기화
다른 방법이 모두 통하지 않을 때, 전체 초기화는 모든 캐시를 지우고 모든 것을 다시 설치합니다.최후의 수단: 전체 초기화 명령
최후의 수단: 전체 초기화 명령
이 명령은 모든 캐시를 제거하고 패키지를 처음부터 다시 설치합니다. 최후의 수단으로만 사용하세요.이 명령이 하는 일:
rm -rf node_modules— 설치된 패키지를 삭제합니다rm -rf .expo— Expo의 로컬 캐시를 삭제합니다npm cache clean --force— npm의 전역 캐시를 지웁니다npm install— 모든 패키지를 다시 설치합니다npx expo start --clear— 새로운 Metro 캐시로 시작합니다
기기의 캐시 지우기
리로드한 후에도 휴대폰의 앱이 이전 코드로 멈춰 있는 것처럼 보인다면:- iOS: Expo Go에서 Settings로 이동해 Clear Cache를 탭하세요
- Android: Settings > Apps > Expo Go > Storage > Clear Cache로 이동하세요
빠른 참조
| 문제 | 먼저 시도할 것 | 그다음 시도할 것 |
|---|---|---|
| 변경 사항이 표시되지 않음 | 휴대폰 흔들기 → Reload | Metro 캐시 지우기 |
| 번들러 오류 | npx expo start --clear | node_modules 삭제 |
| 모듈을 찾을 수 없음 | 종속성 다시 설치 | 전체 초기화 |
| 버전 불일치 경고 | npx expo-doctor 실행 | 제안된 수정 사항 평가 |
| 새 패키지가 동작하지 않음 | 서버 다시 시작 | Metro 캐시 지우기 |
| app.json 변경함 | 서버 다시 시작 | — |
더 많은 도움 받기
여전히 문제가 해결되지 않는다면:- Agent에게 물어보세요: 오류와 시도한 방법을 설명하세요. Agent가 문제를 진단하고 수정할 수 있는 경우가 많습니다.
- Expo 문서를 확인하세요: Expo 문제 해결 가이드에서 추가 시나리오를 다룹니다.
- 오류를 검색하세요: 정확한 오류 메시지를 복사해 검색해 보세요. 다른 누군가가 이미 겪었을 가능성이 높습니다.
다음 단계
- 네이티브 모바일 앱으로 돌아가기
- 전체 게시 흐름 알아보기: 모바일 앱 빌드 및 출시하기