안드로이드 개발 환경 설정

안드로이드 개발 환경 설정

 

필수 요약 체크리스트

• JDK: Temurin OpenJDK 17 LTS 권장(AGP 8.x 호환). 새 프로젝트·장기운영은 21도 고려(팀/CI 일치 필수).
• Android Studio: Stable 채널 최신 설치. (플러그인 업데이트 시 빌드 툴체인 동기화)
• SDK 필수: platform-tools, build-tools;XX.X.X, platforms;android-XX, cmdline-tools;latest
• 환경 변수: ANDROID_SDK_ROOT 필수. macOS는 기본 ~/Library/Android/sdk
• 라이선스: sdkmanager --licenses 사전 동의
• 에뮬레이터: Apple Silicon → arm64-v8a 이미지. Windows → Hyper‑V/WHPX, Linux → KVM
• 네트워크: 사내 프록시/SSL 검사 환경이면 gradle.properties에 프록시/CA 인증서 설정
• 빌드: Gradle Wrapper 고정, AGP/JDK 버전 매트릭스 준수
• 모바일 프레임워크: Flutter flutter doctor, RN npx react-native doctor로 최종 검증

 

1. 버전 매트릭스(권장 조합)

항목보편/안정대규모/장기운영비고

항목	보편/안정	대규모/장기운영	비고
AGP (Android Gradle Plugin)	8.4–8.6	8.6+	프로젝트 템플릿 기준 상향 추세
Gradle	8.7–8.10	8.10+	Wrapper로 프로젝트별 고정
JDK	17 LTS	21 LTS	AGP 요구와 일치
Kotlin	2.0.21	2.0.21+	Compose/AGP 호환 확인
NDK	r26	r26–r27	네이티브 필요 시만
Build Tools	34.x/35.x	35.x	build.gradle의 compileSdk와 맞춤

※ “정답”은 없으며, 프로젝트 템플릿이 생성한 조합을 최대한 유지하는 것이 안전합니다.

 

2. Android Studio 설치와 SDK 구성

2.1 Android Studio

• macOS: .dmg 설치 후 첫 실행에서 SDK 경로 확인(기본값 권장).
• Windows: 설치 중 SDK 경로가 C:\Users\<계정>\AppData\Local\Android\Sdk 일 가능성 높음.
• Linux: 압축 해제 후 studio.sh, SDK는 ~/Android/Sdk 권장.

2.2 SDK 필수 구성요소

• Platform‑Tools(adb/fastboot), Build‑Tools, Platforms(API), Command‑line Tools
• 선택: NDK, CMake, Google USB Driver(Windows), Intel HAXM(x86은 구형).

2.3 GUI로 설치 경로

Android Studio → Settings/Preferences → Appearance & Behavior → System Settings > Android SDK

- SDK Platforms 탭: 최소 지원/빌드 대상 API 설치(ex. Android 34/35)

- SDK Tools 탭: 위 필수 항목 선택 설치

2.4 CLI로 설치(sdkmanager)

# macOS 기본 경로 가정
export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
yes | "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" --sdk_root="$ANDROID_SDK_ROOT"   "platform-tools" "cmdline-tools;latest"   "platforms;android-35" "build-tools;35.0.0"
yes | "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" --sdk_root="$ANDROID_SDK_ROOT" --licenses

 

3. 환경 변수 세팅

3.1 macOS(zsh)

# ~/.zshrc
export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/emulator:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin"
export JAVA_HOME=$(/usr/libexec/java_home -v 17)   # 또는 21

적용:

source ~/.zshrc && java -version && adb --version

3.2 Windows(PowerShell)

# 관리자 PowerShell


$env:Path += ";$env:ANDROID_SDK_ROOT\platform-tools;$env:ANDROID_SDK_ROOT\emulator;$env:JAVA_HOMEin"

장치 드라이버: 삼성/샤오미 등 OEM USB 드라이버 설치 필요.

3.3 Linux

# ~/.bashrc
export ANDROID_SDK_ROOT="$HOME/Android/Sdk"
export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/emulator:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin"

USB 권한(udev) 예시:

/etc/udev/rules.d/51-android.rules
SUBSYSTEMusb, ATTR{idVendor}18d1, MODE=0666, GROUP=plugdev
sudo udevadm control –reload-rules && sudo udevadm trigger

 

4. 에뮬레이터(AVD) 설정과 최적화

4.1 생성

GUI: Android Studio → Device Manager → Create Device

CLI:

avdmanager create avd -n Pixel15 -k "system-images;android-35;google_apis;arm64-v8a"
emulator -avd Pixel15

4.2 성능 팁

• Apple Silicon: ARM64 이미지 사용, 그래픽 자동/하드웨어, RAM 4–6GB
• Windows: BIOS에서 가상화 켜기, Hyper‑V/WHPX 사용
• Linux: KVM 활성화(lsmod | grep kvm), 권한 설정
• Cold boot 느리면 AVD 재생성, Quick Boot 유지
• Disk I/O: AVD 저장 위치를 SSD로

 

5. 실제 디바이스 디버깅

• 개발자 옵션 → USB 디버깅 켬, USB 연결 후 bash adb devices -l ### 5.1 Wi‑Fi 디버깅(무선)bash adb tcpip 5555 adb connect <device-ip>:5555 adb devices ### 5.2 포트 포워딩
• 네이티브 서버/Flutter Dev 서버 접속:bash adb reverse tcp:8080 tcp:8080 adb reverse tcp:3000 tcp:3000

 

6. Gradle/AGP/Kotlin 구성

6.1 gradle.properties 예시

org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8
org.gradle.parallel=true
org.gradle.configureondemand=true
android.useAndroidX=true
android.enableJetifier=true
kotlin.code.style=official

메모리 부족 시:
properties
org.gradle.jvmargs=-Xms1g -Xmx6g -XX:MaxMetaspaceSize=1g -Dkotlin.daemon.jvm.options=-Xmx2g

6.2 build.gradle 설정 포인트

• compileSdk, targetSdk 최신 유지(버전 상향 시 종속성 업데이트 동반)
• Kotlin 플러그인 버전 = Compose/AGP 호환 범위 확인
• ProGuard/R8: 릴리스 최적화 규칙 정리

6.3 버전 충돌 해결

• “AGP xxx requires Java 17/21” → JDK 맞춤
• “Kotlin xx required by… ” → Kotlin 플러그인 올리기
• “Duplicate class …” → 종속성 중복 제거(gradle dependencies로 추적)

 

7. 네트워크/프록시/기업 환경

7.1 프록시 설정

~/.gradle/gradle.properties 또는 프로젝트 gradle.properties:
properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

인증 필요 시:
properties
systemProp.http.proxyUser=your_id
systemProp.http.proxyPassword=your_pw

7.2 사내 SSL 검사 차단 이슈

• 사내 CA 인증서(java keystore)에 추가하거나 Gradle/SDK Manager에 신뢰 루트 추가
• 임시 우회: 사설 저장소 URL 대신 미러 서버 사용

 

8. 릴리스 빌드 & 서명(AAB)

8.1 Keystore 생성

keytool -genkey -v -keystore my-release-key.jks -alias app -keyalg RSA -keysize 4096 -validity 36500

8.2 Gradle 서명 설정(네이티브 예)

android {
  signingConfigs {
    release {
      storeFile file("$rootDir/keystore/my-release-key.jks")
      storePassword System.getenv("KS_PASS")
      keyAlias "app"
      keyPassword System.getenv("KEY_PASS")
    }
  }
  buildTypes {
    release {
      signingConfig signingConfigs.release
      minifyEnabled true
      proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
  }
}

환경변수는 CI에서 주입. Keystore는 리포에 올리지 말 것.

8.3 Play Console 업로드

• AAB 필요, App Integrity(Play App Signing) 사용 권장
• 콘텐츠 등급/개인정보 양식/타겟 연령대 체크
• 테스트 트랙(Internal/Closed/Open) 운영

 

9. Flutter/React Native 통합

9.1 Flutter

flutter doctor -v
flutter config --android-sdk $ANDROID_SDK_ROOT
flutter doctor --android-licenses
flutter run

• android/local.properties에 sdk.dir= 자동 생성
• AGP 업데이트 경고 시 Flutter 채널·플러그인 호환 확인

9.2 React Native

node -v && npm -v && java -version
npx react-native doctor
cd android && ./gradlew assembleDebug

• New Architecture(bridgeless) 옵션은 RN 버전별 가이드에 따름
• Hermes/ProGuard 설정 확인

 

10. 정적 분석/품질

• Lint: ./gradlew lint 결과를 CI에 업로드
• ktlint/Detekt 적용: bash ./gradlew ktlintCheck ./gradlew detekt
• 유닛/계측 테스트: ./gradlew test / ./gradlew connectedAndroidTest

 

11. CI(예: GitHub Actions) 예시

name: Android CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup JDK
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17
          cache: gradle
      - name: Android SDK
        uses: android-actions/setup-android@v3
      - name: Accept Licenses
        run: yes | sdkmanager --licenses
      - name: Build Debug
        run: ./gradlew assembleDebug --stacktrace

캐시: ~/.gradle, ~/.android 유지로 속도 개선.

 

12. 자주 발생하는 오류와 해결

증상	원인	해결
SDK location not found	local.properties유실	sdk.dir 추가 또는 ANDROIDSDKROOT 점검
“requires Java 17/21”	JDK/Studio JDK 미일치	JAVA_HOME, Gradle JDK 맞춤
NDK not configured	NDK 미설치	sdkmanager "ndk;26.1.10909125"설치
Emulator x86 on Apple Silicon	아키텍처 불일치	arm64 이미지로 재생성
BUILD_TOOLS corrupted	파일 손상	해당 build-tools 버전 제거 후 재설치
Could not resolve dep.	저장소/프록시	mirrors, 프록시 설정, 저장소 가용성 확인
Duplicate class	라이브러리 중복	종속성 정리, exclude 규칙 추가

 

13. 프로젝트 템플릿 추천 세팅

• compileSdk = 35, targetSdk = 35(2025 현재)
• JDK 17, AGP 8.6, Gradle 8.10
• Kotlin 2.0.21(Compose 최신과 호환 확인)
• CI에서 ./gradlew lint test assembleDebug 기본 파이프라인

 

14. 템플릿 파일

14.1 local.properties 예시

sdk.dir=/Users/you/Library/Android/sdk

14.2 .gitignore (안드로이드)

.gradle/
.local/
.idea/
**/local.properties
**/*.jks
.cxx/

14.3 ProGuard 기본 규칙

-keep class com.google.gson.** { *; }
-keep class kotlin.** { *; }
-dontwarn javax.annotation.**