메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.replit.com/llms.txt

Use this file to discover all available pages before exploring further.

Replit에서 모바일 앱을 빌드할 때 미리보기, 번들링, 패키지 의존성 관련 문제가 발생할 수 있습니다. 이 가이드는 빠른 해결 방법부터 심층 디버깅 단계까지 일반적인 문제를 해결하는 데 도움을 줍니다.

​
빠른 해결 방법

먼저 이 방법들을 시도하세요 — 대부분의 문제는 이것으로 해결됩니다:
문제시도할 방법
변경 사항이 휴대폰에 표시되지 않음휴대폰을 흔들어 Expo 메뉴를 열고 Reload 탭하기
변경 사항이 미리보기에 표시되지 않음콘솔에서 R 키를 눌러 재번들
앱이 멈추거나 응답하지 않음콘솔에서 앱을 중지하고 다시 시작

​
일반적인 문제

변경했지만 휴대폰에서 보이지 않을 때:
  1. 휴대폰을 흔들어 Expo 개발자 메뉴를 엽니다
  2. Reload를 탭하여 번들을 다시 다운로드합니다
웹 미리보기에서는 콘솔에서 R 키를 눌러 재번들을 트리거합니다.변경 사항이 여전히 나타나지 않으면 캐시를 지워보세요 (아래 Metro 캐시 지우기 참조).
빨간 오류 화면은 보통 JavaScript 오류 또는 누락된 모듈을 나타냅니다. 오류 메시지를 읽어보세요 — 특정 파일과 줄을 가리키는 경우가 많습니다.일반적인 원인:
  • 패키지가 설치되지 않았거나 잘못된 버전임
  • 모듈이 웹에서는 작동하지만 네이티브에서는 작동하지 않음 (또는 반대)
  • 코드의 문법 오류
시도할 방법:
  1. 오류 메시지를 주의 깊게 읽으세요 — 무엇이 잘못되었는지 정확히 알려주는 경우가 많습니다
  2. 메시지를 공유하여 Agent에게 오류 수정을 요청하세요
  3. 오류에 특정 패키지가 언급된 경우 의존성을 다시 설치해보세요 (패키지 재설치 참조)
일부 패키지나 기능은 플랫폼별로 다르게 작동합니다. React Native는 iOS, Android, 웹 세 가지 타겟으로 컴파일됩니다. 웹에서 작동하는 라이브러리가 네이티브를 지원하지 않거나 다른 구성이 필요할 수 있습니다.시도할 방법:
  1. 패키지 문서에서 해당 플랫폼을 지원하는지 확인하세요
  2. Agent에게 질문하세요: “Is this package compatible with Expo Go?”
  3. 모바일에서 지원되지 않는 경우 기능을 서버로 이동하는 것을 고려하세요
패키지를 조사할 때 “Expo compatible”을 찾거나 지원 모듈에 대한 Expo SDK 문서를 확인하세요.
네트워크 확인:
  • 휴대폰과 컴퓨터가 동일한 WiFi 네트워크에 있어야 합니다
  • 일부 기업 또는 공공 네트워크는 연결을 차단합니다
터널 모드 시도: 제한된 네트워크에 있다면 터널 모드는 Expo 서버를 통해 트래픽을 라우팅합니다. Agent에게 터널 모드로 앱을 시작하도록 요청하거나, 셸에서 npx expo start --tunnel을 실행하세요.Expo Go 재시작: 스캔하기 전에 Expo Go를 완전히 닫고 다시 열어보세요.
캐시가 없기 때문에 첫 번째 빌드는 항상 더 느립니다. 이후 빌드는 더 빨라야 합니다.빌드 시간에 영향을 미치는 요소:
  • 프로젝트의 패키지 수
  • 캐시를 지운 후 첫 번째 실행
  • 패키지 다운로드 시 네트워크 속도
빌드가 지속적으로 느리다면 불필요한 패키지가 설치되어 있는지 확인하세요.
“Unable to resolve module” 또는 “Module not found”가 표시될 때:
  1. 패키지가 설치되지 않았을 수 있습니다 — Agent에게 설치를 요청하세요
  2. 패키지가 설치되어 있지만 캐시가 오래되었을 수 있습니다 — 캐시를 지우세요
  3. 패키지가 존재하지 않거나 철자가 틀렸을 수 있습니다 — 패키지 이름을 확인하세요
모듈이 존재해야 한다면 패키지 재설치를 시도하세요.

​
디버깅 명령어

빠른 해결 방법이 작동하지 않을 때 이 명령어들은 다양한 캐시와 상태를 초기화하는 데 도움이 됩니다. Shell에서 실행하세요.

​
Metro 캐시 지우기

Metro는 React Native 코드를 컴파일하는 번들러입니다. 캐시를 지우면 새로운 빌드가 강제됩니다. 셸에서 실행하세요: 
npx expo start --clear
이렇게 하면 번들러 캐시가 지워지고 개발 서버가 재시작됩니다. 출력에서 “Bundler cache is empty. Rebuilding.”을 확인할 수 있습니다.
캐시 문제가 자주 발생한다면 시작 명령어에 -c를 추가할 수 있습니다. Agent에게 clear 플래그를 포함하도록 dev 명령어를 업데이트해달라고 요청하세요.

​
패키지 재설치

모듈 오류나 버전 불일치가 발생하면 패키지를 재설치하는 것이 도움이 되는 경우가 많습니다. 셸에서 실행하세요: 
rm -rf node_modules && npm install
이렇게 하면 설치된 모든 패키지를 삭제하고 package.json을 기반으로 처음부터 다시 설치합니다.
프로젝트에서 다른 패키지 매니저(예: bun 또는 pnpm)를 사용하는 경우 적절한 설치 명령어를 사용하세요: bun install 또는 pnpm install.

​
버전 불일치 확인

Expo Doctor는 패키지 간 버전 불일치 같은 일반적인 문제를 프로젝트에서 스캔합니다. 셸에서 실행하세요: 
npx expo-doctor
경고 사항을 확인하세요. 수정을 제안하는 경우 신중하게 평가하세요 — 새 버전에 호환되지 않는 변경 사항이 있을 수 있으므로 패키지를 무분별하게 업그레이드하지 마세요.
특정 이유가 있을 때만 패키지를 업데이트하세요. “그냥” 업그레이드하면 새 버전에 호환되지 않는 변경 사항이 있는 경우 앱이 중단될 수 있습니다.

​
전체 초기화

다른 방법이 모두 효과가 없을 때 전체 초기화를 통해 모든 캐시를 지우고 모든 것을 재설치합니다.
이 명령어는 모든 캐시를 제거하고 패키지를 처음부터 재설치합니다. 최후의 수단으로 사용하세요.
rm -rf node_modules .expo && npm cache clean --force && npm install && npx expo start --clear
이 명령어가 하는 일:
  1. rm -rf node_modules — 설치된 패키지 삭제
  2. rm -rf .expo — Expo의 로컬 캐시 삭제
  3. npm cache clean --force — npm의 전역 캐시 지우기
  4. npm install — 모든 패키지 재설치
  5. npx expo start --clear — 새로운 Metro 캐시로 시작
이 명령어 실행 후 모든 것이 처음부터 다시 빌드되므로 다음 빌드는 더 오래 걸립니다.

​
기기에서 캐시 지우기

다시 로드한 후에도 휴대폰의 앱이 이전 코드로 멈춰 있는 것처럼 보인다면:
  • iOS: Expo Go에서 Settings로 이동하여 Clear Cache 탭하기
  • Android: Settings > Apps > Expo Go > Storage > Clear Cache로 이동

​
빠른 참조

문제먼저 시도그 다음 시도
변경 사항이 표시되지 않음휴대폰 흔들기 → ReloadMetro 캐시 지우기
번들러 오류npx expo start --clearnode_modules 삭제
모듈을 찾을 수 없음의존성 재설치전체 초기화
버전 불일치 경고npx expo-doctor 실행제안된 수정 사항 평가
새 패키지가 작동하지 않음서버 재시작Metro 캐시 지우기
app.json 변경서버 재시작—

​
추가 도움 받기

여전히 막혀 있다면:
  • Agent에게 질문하세요: 오류와 시도한 방법을 설명하세요. Agent가 문제를 진단하고 수정할 수 있는 경우가 많습니다.
  • Expo 문서 확인: Expo 문제 해결 가이드에서 추가 시나리오를 다룹니다.
  • 오류 검색: 정확한 오류 메시지를 복사하여 검색하세요 — 이미 누군가가 이 문제를 겪었을 가능성이 높습니다.

​
다음 단계