# 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/)