David Brain

Mobile-기동-방법-가이드

5 min read

ID: key_26_30_05_26_mobile_guide_01 Created date: 5월 30 2026 토요일

연관 문서

모바일 개발 | 모바일 (React Native)

전제 조건 (최초 1회)

필수 설치 항목

도구확인 명령설치 위치
Node.js 18+node -vhttps://nodejs.org
npm / yarnnpm -vNode 설치 시 포함
React Native CLInpx react-native --version자동 (npx 사용)
JDK 17+java -versionhttps://adoptium.net
Android Studio-https://developer.android.com/studio
Xcode (Mac only)xcode-select -vApp Store

Android 환경변수 설정 (Windows)

# 시스템 환경변수에 추가
ANDROID_HOME = C:\Users\{사용자명}\AppData\Local\Android\Sdk
 
# Path에 추가
%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\emulator

프로젝트 기동 방법

프로젝트 경로

C:\workspace\tsh\cira-mobile

Step 1 — 의존성 설치

cd C:\workspace\tsh\cira-mobile
npm install
# 또는
yarn install

Step 2 — iOS Pod 설치 (Mac 전용)

cd ios && pod install && cd ..

Step 3 — 에뮬레이터/디바이스 준비

Android 에뮬레이터

# 실행 중인 디바이스 확인
adb devices
 
# Android Studio에서 AVD Manager 열어 에뮬레이터 실행
# 또는 CLI로 실행 (AVD 이름 확인 후)
emulator -avd {AVD_NAME}

실물 Android 디바이스 연결

설정 → 개발자 옵션 → USB 디버깅 ON
USB 케이블 연결 후 adb devices 로 인식 확인

iOS 시뮬레이터 (Mac 전용)

# 시뮬레이터 목록 확인
xcrun simctl list devices
 
# 특정 시뮬레이터 실행
xcrun simctl boot "iPhone 15"
open -a Simulator

Step 4 — Metro Bundler 실행

cd C:\workspace\tsh\cira-mobile
npx react-native start
# 또는
npm start

Metro Bundler가 백그라운드에서 JS 번들을 제공하는 서버 역할을 함.
별도 터미널에서 유지 후 Step 5 진행.

Step 5 — 앱 빌드 및 실행

Android

# 새 터미널에서
cd C:\workspace\tsh\cira-mobile
npx react-native run-android
 
# 특정 디바이스 지정 시
npx react-native run-android --deviceId {DEVICE_ID}

iOS (Mac 전용)

npx react-native run-ios
# 특정 시뮬레이터 지정
npx react-native run-ios --simulator "iPhone 15"

개발 중 주요 기능

빠른 새로고침 (Fast Refresh)

코드 변경 시 자동으로 화면에 반영됨 (저장 즉시).
동작하지 않을 경우 디바이스/에뮬레이터에서 R 키 또는 더블 탭으로 수동 새로고침.

개발자 메뉴 호출

플랫폼방법
Android 에뮬레이터Ctrl+M 또는 Cmd+M
Android 실물 기기디바이스 흔들기
iOS 시뮬레이터Cmd+D
iOS 실물 기기디바이스 흔들기

개발자 메뉴에서 접근 가능한 기능:

  • Reload: 앱 새로고침
  • Toggle Inspector: UI 요소 검사
  • Open Debugger: Chrome DevTools 연결
  • Perf Monitor: 성능 모니터링

네트워크 API 서버 연결

에뮬레이터/디바이스에서 로컬 백엔드 서버 접근 시:

Android 에뮬레이터 → 10.0.2.2:{포트}  (localhost 대신)
iOS 시뮬레이터     → localhost:{포트}  (동일 Mac이므로 직접 접근 가능)
실물 기기          → PC의 실제 IP:{포트}  (같은 Wi-Fi 네트워크 필요)

src/config/api.ts (또는 .env) 에서 BASE_URL 확인 및 수정:

// 예시
const BASE_URL = __DEV__
  ? 'http://10.0.2.2:8080'  // Android 에뮬레이터용
  : 'https://api.cira.yourdomain.com';

트러블슈팅

증상원인해결
adb: command not foundANDROID_HOME 환경변수 미설정platform-tools PATH 추가 후 터미널 재시작
Metro Bundler 포트 충돌8081 포트 사용 중npx react-native start --port 8082
빌드 실패 (JAVA_HOME)JDK 경로 미설정JAVA_HOME 환경변수 설정
앱 설치되나 흰 화면Metro 미실행Step 4 먼저 실행 후 앱 재실행
pod install 실패CocoaPods 미설치sudo gem install cocoapods
네트워크 요청 실패API 주소 오류BASE_URL을 에뮬레이터용 IP로 수정

빠른 기동 체크리스트

□ adb devices 로 에뮬레이터/기기 인식 확인
□ npm install 완료
□ npx react-native start (Metro 실행, 터미널 유지)
□ npx react-native run-android (별도 터미널)
□ 앱 화면 정상 렌더링 확인
□ 백엔드 API BASE_URL 에뮬레이터 IP로 설정 확인

Graph View