> ## 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와 React Native로 모바일 앱을 빌드할 때 발생하는 일반적인 문제를 해결합니다.

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

## 빠른 해결 방법

먼저 이 방법들을 시도하세요 — 대부분의 문제는 이것으로 해결됩니다:

| 문제                   | 시도할 방법                              |
| -------------------- | ----------------------------------- |
| 변경 사항이 휴대폰에 표시되지 않음  | 휴대폰을 흔들어 Expo 메뉴를 열고 **Reload** 탭하기 |
| 변경 사항이 미리보기에 표시되지 않음 | 콘솔에서 **R** 키를 눌러 재번들                |
| 앱이 멈추거나 응답하지 않음      | 콘솔에서 앱을 중지하고 다시 시작                  |

## 일반적인 문제

<AccordionGroup>
  <Accordion title="변경 사항이 기기에 나타나지 않습니다">
    변경했지만 휴대폰에서 보이지 않을 때:

    1. **휴대폰을 흔들어** Expo 개발자 메뉴를 엽니다
    2. **Reload**를 탭하여 번들을 다시 다운로드합니다

    웹 미리보기에서는 콘솔에서 **R** 키를 눌러 재번들을 트리거합니다.

    변경 사항이 여전히 나타나지 않으면 캐시를 지워보세요 (아래 [Metro 캐시 지우기](#clear-the-metro-cache) 참조).
  </Accordion>

  <Accordion title="Expo Go에서 빨간 오류 화면이 표시됩니다">
    빨간 오류 화면은 보통 JavaScript 오류 또는 누락된 모듈을 나타냅니다. 오류 메시지를 읽어보세요 — 특정 파일과 줄을 가리키는 경우가 많습니다.

    **일반적인 원인:**

    * 패키지가 설치되지 않았거나 잘못된 버전임
    * 모듈이 웹에서는 작동하지만 네이티브에서는 작동하지 않음 (또는 반대)
    * 코드의 문법 오류

    **시도할 방법:**

    1. 오류 메시지를 주의 깊게 읽으세요 — 무엇이 잘못되었는지 정확히 알려주는 경우가 많습니다
    2. 메시지를 공유하여 Agent에게 오류 수정을 요청하세요
    3. 오류에 특정 패키지가 언급된 경우 의존성을 다시 설치해보세요 ([패키지 재설치](#reinstall-packages) 참조)
  </Accordion>

  <Accordion title="앱이 웹에서는 작동하지만 휴대폰에서 충돌합니다 (또는 반대)">
    일부 패키지나 기능은 플랫폼별로 다르게 작동합니다. React Native는 iOS, Android, 웹 세 가지 타겟으로 컴파일됩니다. 웹에서 작동하는 라이브러리가 네이티브를 지원하지 않거나 다른 구성이 필요할 수 있습니다.

    **시도할 방법:**

    1. 패키지 문서에서 해당 플랫폼을 지원하는지 확인하세요
    2. Agent에게 질문하세요: "Is this package compatible with Expo Go?"
    3. 모바일에서 지원되지 않는 경우 기능을 서버로 이동하는 것을 고려하세요

    <Tip>
      패키지를 조사할 때 "Expo compatible"을 찾거나 지원 모듈에 대한 [Expo SDK 문서](https://docs.expo.dev/versions/latest/)를 확인하세요.
    </Tip>
  </Accordion>

  <Accordion title="QR 코드가 스캔되지 않거나 앱이 연결되지 않습니다">
    **네트워크 확인:**

    * 휴대폰과 컴퓨터가 동일한 WiFi 네트워크에 있어야 합니다
    * 일부 기업 또는 공공 네트워크는 연결을 차단합니다

    **터널 모드 시도:**
    제한된 네트워크에 있다면 터널 모드는 Expo 서버를 통해 트래픽을 라우팅합니다. Agent에게 터널 모드로 앱을 시작하도록 요청하거나, 셸에서 `npx expo start --tunnel`을 실행하세요.

    **Expo Go 재시작:**
    스캔하기 전에 Expo Go를 완전히 닫고 다시 열어보세요.
  </Accordion>

  <Accordion title="빌드 시간이 너무 오래 걸립니다">
    캐시가 없기 때문에 첫 번째 빌드는 항상 더 느립니다. 이후 빌드는 더 빨라야 합니다.

    **빌드 시간에 영향을 미치는 요소:**

    * 프로젝트의 패키지 수
    * 캐시를 지운 후 첫 번째 실행
    * 패키지 다운로드 시 네트워크 속도

    빌드가 지속적으로 느리다면 불필요한 패키지가 설치되어 있는지 확인하세요.
  </Accordion>

  <Accordion title="모듈을 찾을 수 없다는 오류가 발생합니다">
    "Unable to resolve module" 또는 "Module not found"가 표시될 때:

    1. 패키지가 설치되지 않았을 수 있습니다 — Agent에게 설치를 요청하세요
    2. 패키지가 설치되어 있지만 캐시가 오래되었을 수 있습니다 — 캐시를 지우세요
    3. 패키지가 존재하지 않거나 철자가 틀렸을 수 있습니다 — 패키지 이름을 확인하세요

    모듈이 존재해야 한다면 [패키지 재설치](#reinstall-packages)를 시도하세요.
  </Accordion>
</AccordionGroup>

## 디버깅 명령어

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

### Metro 캐시 지우기

Metro는 React Native 코드를 컴파일하는 번들러입니다. 캐시를 지우면 새로운 빌드가 강제됩니다.

셸에서 실행하세요:

```bash theme={null}
npx expo start --clear
```

이렇게 하면 번들러 캐시가 지워지고 개발 서버가 재시작됩니다. 출력에서 "Bundler cache is empty. Rebuilding."을 확인할 수 있습니다.

<Tip>
  캐시 문제가 자주 발생한다면 시작 명령어에 `-c`를 추가할 수 있습니다. Agent에게 clear 플래그를 포함하도록 dev 명령어를 업데이트해달라고 요청하세요.
</Tip>

### 패키지 재설치

모듈 오류나 버전 불일치가 발생하면 패키지를 재설치하는 것이 도움이 되는 경우가 많습니다.

셸에서 실행하세요:

```bash theme={null}
rm -rf node_modules && npm install
```

이렇게 하면 설치된 모든 패키지를 삭제하고 `package.json`을 기반으로 처음부터 다시 설치합니다.

<Note>
  프로젝트에서 다른 패키지 매니저(예: `bun` 또는 `pnpm`)를 사용하는 경우 적절한 설치 명령어를 사용하세요: `bun install` 또는 `pnpm install`.
</Note>

### 버전 불일치 확인

Expo Doctor는 패키지 간 버전 불일치 같은 일반적인 문제를 프로젝트에서 스캔합니다.

셸에서 실행하세요:

```bash theme={null}
npx expo-doctor
```

경고 사항을 확인하세요. 수정을 제안하는 경우 신중하게 평가하세요 — 새 버전에 호환되지 않는 변경 사항이 있을 수 있으므로 패키지를 무분별하게 업그레이드하지 마세요.

<Warning>
  특정 이유가 있을 때만 패키지를 업데이트하세요. "그냥" 업그레이드하면 새 버전에 호환되지 않는 변경 사항이 있는 경우 앱이 중단될 수 있습니다.
</Warning>

## 전체 초기화

다른 방법이 모두 효과가 없을 때 전체 초기화를 통해 모든 캐시를 지우고 모든 것을 재설치합니다.

<Accordion title="최후의 수단: 전체 초기화 명령어">
  이 명령어는 모든 캐시를 제거하고 패키지를 처음부터 재설치합니다. 최후의 수단으로 사용하세요.

  ```bash theme={null}
  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 캐시로 시작

  이 명령어 실행 후 모든 것이 처음부터 다시 빌드되므로 다음 빌드는 더 오래 걸립니다.
</Accordion>

### 기기에서 캐시 지우기

다시 로드한 후에도 휴대폰의 앱이 이전 코드로 멈춰 있는 것처럼 보인다면:

* **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 문제 해결 가이드](https://docs.expo.dev/troubleshooting/overview/)에서 추가 시나리오를 다룹니다.
* **오류 검색**: 정확한 오류 메시지를 복사하여 검색하세요 — 이미 누군가가 이 문제를 겪었을 가능성이 높습니다.

## 다음 단계

* [Native Mobile Apps](/references/artifact-types/building-mobile-apps)로 돌아가기
* 전체 퍼블리싱 흐름 알아보기: [Build and launch a mobile app](/build/mobile-app)