chpark/DTGAPK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4f7aa593a1df3aca0eaac274e0f5aef3f40c462d
DTGAPK/BUILD_GUIDE.md

8.3 KiB
Raw Blame History

Android APK 빌드 가이드

사전 준비

1. 필수 소프트웨어 설치

Java Development Kit (JDK) 11

# 설치 확인
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에서 확인:

$env:ANDROID_HOME
$env:JAVA_HOME
adb version

2. Node.js 의존성 설치

# 프로젝트 루트에서
npm install

APK 빌드 방법

방법 1: Debug APK (테스트용)

가장 빠르고 간단한 방법입니다.

# 프로젝트 루트에서
cd android

# Windows
.\gradlew assembleDebug

# 빌드 완료 후 APK 위치:
# android\app\build\outputs\apk\debug\app-debug.apk

방법 2: Release APK (배포용)

2-1. 키스토어 생성 (최초 1회만)

# 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 파일 생성 또는 수정:

# 기존 내용 유지하고 아래 추가

# 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 섹션 수정:

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 빌드

# android 디렉토리에서
cd android

# Windows
.\gradlew assembleRelease

# 빌드 완료 후 APK 위치:
# android\app\build\outputs\apk\release\app-release.apk

방법 3: React Native CLI 사용

# 프로젝트 루트에서
npx react-native build-android --mode=release

# APK 위치: android/app/build/outputs/apk/release/app-release.apk

APK 설치 방법

1. USB 연결로 설치

# 디바이스를 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 파일:

# 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:

android {
    ...
    buildTypes {
        release {
            ...
            minifyEnabled true
            shrinkResources true
        }
    }
    
    // ABI 분리 (선택사항)
    splits {
        abi {
            enable true
            reset()
            include "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
            universalApk true
        }
    }
}

문제 해결

빌드 오류 발생 시

# 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 파일 생성:

sdk.dir=C:\\Users\\[사용자명]\\AppData\\Local\\Android\\Sdk

메모리 부족 오류

android/gradle.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:

android {
    defaultConfig {
        ...
        versionCode 2          // 정수로 증가 (1, 2, 3, ...)
        versionName "1.1.0"    // 사용자에게 표시되는 버전
    }
}

빌드 자동화 스크립트

Windows (build-apk.bat)

@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

실행:

build-apk.bat

Google Play Store 업로드용 AAB

APK 대신 AAB (Android App Bundle) 형식으로 빌드:

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 빌드)
  • 버전 코드/이름 업데이트
  • 앱 아이콘 교체 (선택)
  • 앱 이름 확인

참고 자료

Reference in New Issue View Git Blame Copy Permalink