For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/mobile/local-setup.md (or send Accept: text/markdown).
모바일 앱 실행
Expo를 도달 가능한 개발 API에 연결하세요.
1. 컴퓨터, 휴대폰, 백엔드 준비
시작하기 전에 완료하고 편집기에서 모바일 저장소 또는 모든 플랫폼 단일 저장소를 엽니다. 저장소 루트의 터미널 → 새 터미널에서 아래 설치 명령을 실행합니다. 완료될 때까지 기다리세요. 아래 링크된 공식 Expo 페이지를 사용하여 휴대폰에 Expo Go를 설치하세요. 해당 버전은 apps/mobile/package.json.에 기록된 Expo SDK 버전을 지원해야 합니다.
백엔드는 로그인, 작업 영역 데이터 및 AI 요청을 처리하는 웹 서버입니다. 체크아웃에 apps/web가 포함된 경우 먼저 다른 터미널에서 웹 설정을 실행하고 해당 서버를 실행 상태로 둡니다. 기본 가입 또는 로그인을 시도하기 전에 Postgres 설정을 완료하세요. 모바일 전용 결제에는 apps/web가 포함되어 있지 않습니다. 대신 별도로 제공되는 실행 중인 백엔드에 연결하세요. Expo를 시작하면 백엔드가 아닌 화면 미리보기 서버가 시작됩니다.
휴대폰과 컴퓨터를 동일한 Wi-Fi에 연결하세요. 로컬 연결을 차단하는 경우 VPN의 연결을 일시적으로 끊습니다. 전화기의 localhost는 전화기 자체를 의미합니다. 실제 휴대폰이나 Android 기기에 컴퓨터의 개인 네트워크 주소를 사용하세요. 동일한 Mac의 iOS 시뮬레이터는 http://localhost:3000,를 사용할 수 있고 Android 에뮬레이터는 일반적으로 http://10.0.2.2:3000.를 사용합니다.
corepack pnpm install2. 백엔드 주소 찾기 및 테스트
Windows에서는 새 PowerShell 터미널에서 ipconfig를 실행하고 활성 Wi-Fi 어댑터를 찾아 IPv4 주소를 읽습니다. macOS에서 시스템 설정 → Wi-Fi → 세부 정보 → TCP/IP를 열고 IP 주소를 읽습니다. Linux에서는 네트워크 설정을 열고 IPv4 주소를 읽어보세요. 주소는 192.168.1.25와 같습니다. 당신의 경우는 대개 다를 것입니다.
컴퓨터 주소가 192.168.1.25인 경우 웹 서버가 실행되는 동안 휴대폰의 브라우저에서 http://192.168.1.25:3000를 엽니다. 실제 주소를 대체하세요. 계속하려면 홈페이지를 로드해야 합니다. Windows 방화벽에서 요청하면 개인 네트워크에서 Node 앱을 허용합니다. 로드되지 않으면 주소, Wi-Fi, 방화벽 및 실행 중인 웹 서버를 확인하세요. Expo 터널은 미리보기 번들만 전달하며 별도의 API에 연결할 수는 없습니다.
# Windows PowerShell only:
ipconfig3. 모바일 앱의 구성 파일 생성
편집기의 탐색기에서 apps → mobile을 확장하고 .env.local이라는 새 파일을 생성한 후 해당 파일에 아래 구성을 붙여넣습니다. 192.168.1.25를 방금 테스트한 주소로 바꾸거나 제공된 HTTPS 백엔드 주소를 사용하세요. 파일을 저장합니다. 전체 경로는 apps/mobile/.env.local입니다. 루트 .env는 Expo에서 자동으로 읽히지 않습니다.
첫 번째 미리보기에서는 휴대폰의 구매 설정을 꺼진 상태로 유지하세요. EXPO_PUBLIC_는 설정이 전화 앱에 포함되어 있으므로 이러한 값에는 공개 URL, 구성표 및 공개 클라이언트 설정만 포함되어야 함을 의미합니다. 여기에 AI 제공자, 데이터베이스 또는 청구 비밀을 붙여넣지 마십시오. 웹 서버에는 자체 apps/web/.env.local가 있습니다. 모바일 파일을 변경해도 서버는 변경되지 않습니다.
EXPO_PUBLIC_API_URL=http://192.168.1.25:3000
EXPO_PUBLIC_APP_SCHEME=supastack
EXPO_PUBLIC_MOBILE_PURCHASES_PROVIDER=off4. Expo를 시작하고 미리보기를 엽니다.
저장소 루트에서 아래 명령을 실행합니다. QR 코드와 지하철 대기 메시지를 기다리세요. 이 터미널과 백엔드 터미널을 열어두세요. Android에서는 Expo Go를 열고 QR 코드를 스캔하세요. iPhone에서 카메라를 사용하여 코드를 스캔하고 Expo Go에서 엽니다. QR 코드는 백엔드 홈페이지가 아닌 개발 앱을 엽니다.
성공은 기기에서 앱의 로그인 화면이 열리는 것을 의미합니다. 구매가 꺼진 상태에서는 UI 미리보기입니다. 로그인, 저장된 작업 영역 또는 채팅을 테스트하기 전에 데이터베이스 기반 웹 인증 설정을 완료하세요. 설치된 시뮬레이터가 대상인 경우 Android의 경우 Expo 터미널에서 a를 누르고 iOS의 경우 i를 누릅니다. iOS 시뮬레이터에는 macOS 및 Xcode가 필요합니다. Windows에서는 실행할 수 없습니다.
corepack pnpm --filter @supastack/mobile start5. 미리보기 오류 복구 및 실제 흐름 테스트
Expo Go가 호환되지 않는 프로젝트를 보고하는 경우 지원되는 SDK를 apps/mobile/package.json와 비교하고 공식 Expo 페이지에서 호환되는 버전을 사용하세요. 단지 메시지를 무시하기 위해 키트의 종속성 버전을 업그레이드하지 마십시오. 필수 네이티브 모듈을 사용할 수 없는 경우 모바일 빌드를 따라 해당 모듈이 포함된 개발 빌드를 따르세요.
네트워크 오류로 인해 로그인에 실패하는 경우 먼저 휴대폰 브라우저에서 백엔드 URL를 다시 시도하세요. URL가 작동하지만 로그인에 실패하는 경우 백엔드 터미널을 검사하고 Postgres 및 마이그레이션을 확인하세요. 로컬/대시보드 데모 세션에서는 전화기에 로그인되지 않습니다. 구성이 오래된 것 같으면 Expo 터미널에서 Ctrl + C를 누른 다음 아래 다시 시작 명령을 실행하고 미리보기를 다시 엽니다.
Expo Go는 실제 StoreKit 또는 Play Billing 구매/복원 동작을 증명할 수 없습니다. EAS 개발 빌드를 위한 인앱 구매 및 모바일 빌드를 따르고 테스트 계정을 저장하세요. 최초의 기본 빌드 및 계정 등록은 5분 이상 걸릴 수 있습니다. 이 미리보기를 중지하려면 Expo 터미널에서 Ctrl + C를 누르세요. 완료되면 백엔드를 별도로 중지합니다.
corepack pnpm --filter @supastack/mobile start --clear