> ## 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에게 물어보세요: "이 패키지가 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에게 클리어 플래그를 포함하도록 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/)에서 추가 시나리오를 다룹니다.
* **오류를 검색하세요**: 정확한 오류 메시지를 복사해 검색해 보세요. 다른 누군가가 이미 겪었을 가능성이 높습니다.

## 다음 단계

* [네이티브 모바일 앱](/ko/features/artifact-types/building-mobile-apps)으로 돌아가기
* 전체 게시 흐름 알아보기: [모바일 앱 빌드 및 출시하기](/ko/build/mobile-app)