377 lines
8.3 KiB
Markdown
377 lines
8.3 KiB
Markdown
# Android APK 빌드 가이드
|
|
|
|
## 사전 준비
|
|
|
|
### 1. 필수 소프트웨어 설치
|
|
|
|
#### Java Development Kit (JDK) 11
|
|
```bash
|
|
# 설치 확인
|
|
java -version
|
|
|
|
# 없으면 다운로드: https://adoptium.net/
|
|
```
|
|
|
|
#### Android Studio
|
|
1. https://developer.android.com/studio 에서 다운로드
|
|
2. 설치 시 "Android SDK", "Android SDK Platform", "Android Virtual Device" 선택
|
|
3. SDK Manager에서 다음 설치:
|
|
- Android SDK Platform 34
|
|
- Android SDK Build-Tools 34.0.0
|
|
- Android SDK Command-line Tools
|
|
|
|
#### 환경 변수 설정 (Windows)
|
|
|
|
시스템 환경 변수에 추가:
|
|
|
|
```
|
|
ANDROID_HOME = C:\Users\[사용자명]\AppData\Local\Android\Sdk
|
|
JAVA_HOME = C:\Program Files\Eclipse Adoptium\jdk-11.0.x-hotspot
|
|
|
|
Path에 추가:
|
|
%ANDROID_HOME%\platform-tools
|
|
%ANDROID_HOME%\tools
|
|
%ANDROID_HOME%\tools\bin
|
|
%JAVA_HOME%\bin
|
|
```
|
|
|
|
PowerShell에서 확인:
|
|
```powershell
|
|
$env:ANDROID_HOME
|
|
$env:JAVA_HOME
|
|
adb version
|
|
```
|
|
|
|
### 2. Node.js 의존성 설치
|
|
|
|
```bash
|
|
# 프로젝트 루트에서
|
|
npm install
|
|
```
|
|
|
|
## APK 빌드 방법
|
|
|
|
### 방법 1: Debug APK (테스트용)
|
|
|
|
가장 빠르고 간단한 방법입니다.
|
|
|
|
```bash
|
|
# 프로젝트 루트에서
|
|
cd android
|
|
|
|
# Windows
|
|
.\gradlew assembleDebug
|
|
|
|
# 빌드 완료 후 APK 위치:
|
|
# android\app\build\outputs\apk\debug\app-debug.apk
|
|
```
|
|
|
|
### 방법 2: Release APK (배포용)
|
|
|
|
#### 2-1. 키스토어 생성 (최초 1회만)
|
|
|
|
```bash
|
|
# android/app 디렉토리로 이동
|
|
cd android/app
|
|
|
|
# 키스토어 생성
|
|
keytool -genkeypair -v -storetype PKCS12 -keystore logistream-release.keystore -alias logistream -keyalg RSA -keysize 2048 -validity 10000
|
|
|
|
# 입력 정보:
|
|
# - 키 저장소 비밀번호: [안전한 비밀번호 입력 - 기억할 것!]
|
|
# - 키 비밀번호: [안전한 비밀번호 입력 - 기억할 것!]
|
|
# - 이름: [회사명 또는 개인명]
|
|
# - 조직 단위: [부서명]
|
|
# - 조직: [회사명]
|
|
# - 구/군/시: [도시명]
|
|
# - 시/도: [지역명]
|
|
# - 국가 코드: KR
|
|
```
|
|
|
|
#### 2-2. Gradle 설정 파일 생성
|
|
|
|
`android/gradle.properties` 파일 생성 또는 수정:
|
|
|
|
```properties
|
|
# 기존 내용 유지하고 아래 추가
|
|
|
|
# Release Keystore 설정
|
|
LOGISTREAM_UPLOAD_STORE_FILE=logistream-release.keystore
|
|
LOGISTREAM_UPLOAD_KEY_ALIAS=logistream
|
|
LOGISTREAM_UPLOAD_STORE_PASSWORD=여기에_키스토어_비밀번호_입력
|
|
LOGISTREAM_UPLOAD_KEY_PASSWORD=여기에_키_비밀번호_입력
|
|
```
|
|
|
|
⚠️ **중요**: `gradle.properties` 파일은 `.gitignore`에 추가하여 비밀번호가 Git에 올라가지 않도록 주의!
|
|
|
|
#### 2-3. build.gradle 수정
|
|
|
|
`android/app/build.gradle` 파일에서 signingConfigs 섹션 수정:
|
|
|
|
```gradle
|
|
android {
|
|
...
|
|
|
|
signingConfigs {
|
|
debug {
|
|
storeFile file('debug.keystore')
|
|
storePassword 'android'
|
|
keyAlias 'androiddebugkey'
|
|
keyPassword 'android'
|
|
}
|
|
release {
|
|
if (project.hasProperty('LOGISTREAM_UPLOAD_STORE_FILE')) {
|
|
storeFile file(LOGISTREAM_UPLOAD_STORE_FILE)
|
|
storePassword LOGISTREAM_UPLOAD_STORE_PASSWORD
|
|
keyAlias LOGISTREAM_UPLOAD_KEY_ALIAS
|
|
keyPassword LOGISTREAM_UPLOAD_KEY_PASSWORD
|
|
}
|
|
}
|
|
}
|
|
|
|
buildTypes {
|
|
debug {
|
|
signingConfig signingConfigs.debug
|
|
}
|
|
release {
|
|
signingConfig signingConfigs.release
|
|
minifyEnabled true
|
|
shrinkResources true
|
|
proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 2-4. Release APK 빌드
|
|
|
|
```bash
|
|
# android 디렉토리에서
|
|
cd android
|
|
|
|
# Windows
|
|
.\gradlew assembleRelease
|
|
|
|
# 빌드 완료 후 APK 위치:
|
|
# android\app\build\outputs\apk\release\app-release.apk
|
|
```
|
|
|
|
### 방법 3: React Native CLI 사용
|
|
|
|
```bash
|
|
# 프로젝트 루트에서
|
|
npx react-native build-android --mode=release
|
|
|
|
# APK 위치: android/app/build/outputs/apk/release/app-release.apk
|
|
```
|
|
|
|
## APK 설치 방법
|
|
|
|
### 1. USB 연결로 설치
|
|
|
|
```bash
|
|
# 디바이스를 USB로 연결하고 USB 디버깅 활성화
|
|
|
|
# 연결 확인
|
|
adb devices
|
|
|
|
# APK 설치
|
|
adb install android/app/build/outputs/apk/release/app-release.apk
|
|
|
|
# 기존 앱이 있으면 재설치
|
|
adb install -r android/app/build/outputs/apk/release/app-release.apk
|
|
```
|
|
|
|
### 2. 파일 전송으로 설치
|
|
|
|
1. APK 파일을 이메일, 클라우드, USB 등으로 전송
|
|
2. 안드로이드 기기에서 파일 열기
|
|
3. "알 수 없는 출처" 허용 (설정에서)
|
|
4. 설치 진행
|
|
|
|
### 3. QR 코드로 배포
|
|
|
|
APK를 웹 서버에 업로드하고 QR 코드로 다운로드 링크 공유
|
|
|
|
## 빌드 최적화
|
|
|
|
### ProGuard 규칙 추가
|
|
|
|
`android/app/proguard-rules.pro` 파일:
|
|
|
|
```proguard
|
|
# React Native
|
|
-keep class com.facebook.react.** { *; }
|
|
-keep class com.facebook.hermes.** { *; }
|
|
|
|
# WebView
|
|
-keepclassmembers class * extends android.webkit.WebViewClient {
|
|
public void *(android.webkit.WebView, java.lang.String, android.graphics.Bitmap);
|
|
public boolean *(android.webkit.WebView, java.lang.String);
|
|
}
|
|
|
|
# Geolocation
|
|
-keep class com.google.android.gms.location.** { *; }
|
|
|
|
# AsyncStorage
|
|
-keep class com.reactnativecommunity.asyncstorage.** { *; }
|
|
```
|
|
|
|
### APK 크기 줄이기
|
|
|
|
`android/app/build.gradle`:
|
|
|
|
```gradle
|
|
android {
|
|
...
|
|
buildTypes {
|
|
release {
|
|
...
|
|
minifyEnabled true
|
|
shrinkResources true
|
|
}
|
|
}
|
|
|
|
// ABI 분리 (선택사항)
|
|
splits {
|
|
abi {
|
|
enable true
|
|
reset()
|
|
include "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
|
|
universalApk true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 문제 해결
|
|
|
|
### 빌드 오류 발생 시
|
|
|
|
```bash
|
|
# Gradle 캐시 삭제
|
|
cd android
|
|
.\gradlew clean
|
|
|
|
# node_modules 재설치
|
|
cd ..
|
|
rm -rf node_modules
|
|
npm install
|
|
|
|
# Android 빌드 캐시 삭제
|
|
cd android
|
|
.\gradlew cleanBuildCache
|
|
|
|
# 다시 빌드
|
|
.\gradlew assembleRelease
|
|
```
|
|
|
|
### "SDK location not found" 오류
|
|
|
|
`android/local.properties` 파일 생성:
|
|
|
|
```properties
|
|
sdk.dir=C:\\Users\\[사용자명]\\AppData\\Local\\Android\\Sdk
|
|
```
|
|
|
|
### 메모리 부족 오류
|
|
|
|
`android/gradle.properties`에 추가:
|
|
|
|
```properties
|
|
org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
|
|
org.gradle.daemon=true
|
|
org.gradle.parallel=true
|
|
org.gradle.configureondemand=true
|
|
```
|
|
|
|
### 키스토어 비밀번호 분실
|
|
|
|
키스토어 비밀번호를 잊어버린 경우 복구 불가능합니다. 새로운 키스토어를 생성해야 합니다.
|
|
(이미 Play Store에 업로드한 앱은 동일한 키스토어로 업데이트해야 하므로 주의!)
|
|
|
|
## 버전 관리
|
|
|
|
앱 업데이트 시 버전 변경:
|
|
|
|
`android/app/build.gradle`:
|
|
|
|
```gradle
|
|
android {
|
|
defaultConfig {
|
|
...
|
|
versionCode 2 // 정수로 증가 (1, 2, 3, ...)
|
|
versionName "1.1.0" // 사용자에게 표시되는 버전
|
|
}
|
|
}
|
|
```
|
|
|
|
## 빌드 자동화 스크립트
|
|
|
|
### Windows (build-apk.bat)
|
|
|
|
```batch
|
|
@echo off
|
|
echo LogiStream APK 빌드 시작...
|
|
|
|
cd android
|
|
call gradlew clean
|
|
call gradlew assembleRelease
|
|
|
|
if %ERRORLEVEL% EQU 0 (
|
|
echo.
|
|
echo ========================================
|
|
echo 빌드 성공!
|
|
echo APK 위치: android\app\build\outputs\apk\release\app-release.apk
|
|
echo ========================================
|
|
explorer app\build\outputs\apk\release
|
|
) else (
|
|
echo.
|
|
echo ========================================
|
|
echo 빌드 실패! 오류를 확인하세요.
|
|
echo ========================================
|
|
)
|
|
|
|
cd ..
|
|
pause
|
|
```
|
|
|
|
### 실행:
|
|
```bash
|
|
build-apk.bat
|
|
```
|
|
|
|
## Google Play Store 업로드용 AAB
|
|
|
|
APK 대신 AAB (Android App Bundle) 형식으로 빌드:
|
|
|
|
```bash
|
|
cd android
|
|
.\gradlew bundleRelease
|
|
|
|
# AAB 위치: android\app\build\outputs\bundle\release\app-release.aab
|
|
```
|
|
|
|
AAB는 Google Play Store에 업로드하면 자동으로 각 기기에 최적화된 APK를 생성합니다.
|
|
|
|
## 체크리스트
|
|
|
|
빌드 전 확인사항:
|
|
|
|
- [ ] JDK 11 설치 확인
|
|
- [ ] Android SDK 설치 확인
|
|
- [ ] 환경 변수 설정 확인
|
|
- [ ] npm install 완료
|
|
- [ ] 키스토어 생성 (Release 빌드)
|
|
- [ ] gradle.properties 설정 (Release 빌드)
|
|
- [ ] 버전 코드/이름 업데이트
|
|
- [ ] 앱 아이콘 교체 (선택)
|
|
- [ ] 앱 이름 확인
|
|
|
|
## 참고 자료
|
|
|
|
- [React Native 공식 문서](https://reactnative.dev/docs/signed-apk-android)
|
|
- [Android 개발자 가이드](https://developer.android.com/studio/build/building-cmdline)
|
|
- [Gradle 공식 문서](https://docs.gradle.org/)
|
|
|