ByungCheol
840ec84e0d
CI / build (push) Failing after 13m47s
- capacitor.config + android/ 네이티브 프로젝트 - 앱 전용 빌드(.env.capacitor, build:app), 뒤로가기·safe-area - docs/ANDROID.md Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
50 lines
2.3 KiB
Markdown
50 lines
2.3 KiB
Markdown
# 안드로이드 하이브리드 앱 (Capacitor)
|
|
|
|
Vue `dist` 를 네이티브 WebView로 패키징해 Android 앱으로 빌드합니다.
|
|
|
|
## 구성
|
|
- `capacitor.config.json` — appId `kr.sblog.slimbudget`, appName `Slim Budget`, webDir `dist`
|
|
- `android/` — 네이티브 프로젝트(커밋됨, 빌드 산출물은 .gitignore)
|
|
- `.env.capacitor` — **앱 전용 환경변수** (`vite build --mode capacitor` 가 로드)
|
|
- `src/capacitor.js` — 하드웨어 뒤로가기 → 라우터 back, safe-area 클래스(`is-native`)
|
|
- npm 스크립트: `build:app`, `cap:sync`, `cap:android`
|
|
|
|
## ⚠️ 빌드 전 반드시 설정
|
|
**`.env.capacitor` 의 백엔드 절대 URL 을 운영 도메인으로 교체** (앱 안에선 `/api` 상대경로가 안 됨):
|
|
```
|
|
VITE_API_BASE_URL=https://yourdomain.com/api
|
|
```
|
|
백엔드는 이미 CORS에 Capacitor 오리진(`https://localhost`, `capacitor://localhost`, `http://localhost`)을 허용합니다. **백엔드는 HTTPS** 여야 합니다(안드로이드 평문 차단).
|
|
|
|
## 사전 준비 (PC)
|
|
- **Android Studio** + Android SDK + **JDK 17**
|
|
- 에뮬레이터 또는 실기기(USB 디버깅 on)
|
|
|
|
## 빌드 & 실행
|
|
```bash
|
|
# 1) 웹 자산 빌드 + 네이티브로 동기화
|
|
npm run cap:sync # = vite build --mode capacitor && cap sync
|
|
|
|
# 2) Android Studio 열기 → Run ▶ 으로 에뮬레이터/기기 실행
|
|
npm run cap:android # = cap open android
|
|
```
|
|
코드 변경 시마다 `npm run cap:sync` 후 Android Studio에서 다시 실행.
|
|
|
|
## (선택) 아이콘 · 스플래시
|
|
```bash
|
|
npm i -D @capacitor/assets
|
|
# 1024x1024 아이콘을 assets/icon.png 등으로 준비 후
|
|
npx capacitor-assets generate --android
|
|
```
|
|
|
|
## 배포 (Play Store)
|
|
1. Android Studio → Build → **Generate Signed Bundle/APK** → **Android App Bundle(.aab)**
|
|
2. **keystore 생성·보관**(분실 시 업데이트 불가) → 서명
|
|
3. **Google Play Console**(계정 1회 $25) → 앱 생성 → `.aab` 업로드 → 심사
|
|
|
|
## 자주 막히는 부분
|
|
- **네트워크 안 됨/빈 화면**: `.env.capacitor` 의 `VITE_API_BASE_URL` 이 실제 HTTPS 백엔드인지, 재빌드(`cap:sync`) 했는지
|
|
- **CORS 오류**: 백엔드가 앱 오리진 허용하는지(`CorsConfig`), HTTPS 인지
|
|
- **평문 차단**: 백엔드가 http면 안드로이드가 차단 → HTTPS 사용
|
|
- **로그인 유지**: 토큰은 WebView `localStorage` 에 저장되어 유지됨(정상)
|