Linux, Windows 및 CI에서 Android Studio 없이 Android Release Build하기

Android Studio는 훌륭한 IDE이지만, 스토어 출시용 Android build를 만드는 데 반드시 필요한 것은 아닙니다. 생성된 android/ Capacitor 프로젝트의 폴더에는 어떤 터미널에서도 build 및 서명이 가능한 Gradle wrapper가 포함되어 있습니다. 이는 디스플레이가 없는 Linux 서버, Studio가 느린 Windows 환경, 그리고 CI 환경에서 매우 유용합니다.

이 가이드는 명령줄만 사용하여 서명된 AAB를 빌드하는 방법과, Capgo 빌드 노트북에 keystore를 보관하고 싶지 않은 팀을 위한 클라우드 방식,

사전 요구사항

• JDK 21 (java -version 21로 출력됨).
• Android 명령줄 SDK 및 platform-tools, build-tools 사용 중인 Capacitor 버전에 맞는 플랫폼 (Capacitor 8의 경우 API 36, Capacitor 7의 경우 API 35). Linux 가이드 및 Windows 가이드 설치 과정을 다룹니다.
• ANDROID_HOME 내보내거나, android/local.properties 포함 sdk.dir=....
• Capacitor 앱과 android/ 생성됨: bunx cap add android.

1) 서명용 keystore 생성

keytool 모든 플랫폼의 JDK에 포함되어 있습니다:

keytool -genkeypair -v \
  -keystore release.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias release

프롬프트에 따라 스토어 비밀번호와 키 비밀번호를 설정하세요. 파일과 두 비밀번호는 즉시 비밀번호 관리자나 보안 금고에 저장해야 합니다. 절대 release.jks.

Play Console에서 앱을 생성할 때 Play App Signing을 활성화하세요. 그러면 Google이 최종 서명 키를 관리하며, 사용자의 keystore는 분실 시 재설정 가능한 업로드 키가 됩니다.

2) Gradle 서명 설정

비밀 정보를 build.gradle. 생성: android/keystore.properties (gitignored):

storeFile=/absolute/path/to/release.jks
storePassword=your-store-password
keyAlias=release
keyPassword=your-key-password

그다음 이를 다음에서 참조하세요: android/app/build.gradle:

def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file("keystore.properties")
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        release {
            if (keystorePropertiesFile.exists()) {
                storeFile file(keystoreProperties['storeFile'])
                storePassword keystoreProperties['storePassword']
                keyAlias keystoreProperties['keyAlias']
                keyPassword keystoreProperties['keyPassword']
            }
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
        }
    }
}

추가 android/keystore.properties 및 *.jks 대상 .gitignore.

3) 버전 번호 올리기

Google Play는 다음 항목이 포함된 업로드를 거부합니다: versionCode 이전에 확인된 버전입니다. 다음을 수정하세요: android/app/build.gradle:

defaultConfig {
    versionCode 12
    versionName "1.4.0"
}

팀에서는 보통 다음 방식을 사용합니다: versionCode 수동 수정을 피하기 위해 CI 실행 번호나 git commit count를 활용합니다.

4) 터미널에서 AAB 빌드하기

bun run build
bunx cap sync android
cd android
./gradlew bundleRelease

Windows 사용자는 다음을 사용하세요: .\gradlew.bat bundleRelease. 서명된 번들은 다음 경로에 저장됩니다: android/app/build/outputs/bundle/release/app-release.aab.

adb로 직접 설치할 APK가 필요하신가요? ./gradlew assembleRelease 생성합니다 app-release.apk 하위 outputs/apk/release/. 다음 명령어로 설치하세요: adb install; adb install 가이드 예외 케이스까지 다룹니다.

5) 서명 확인

$ANDROID_HOME/build-tools/36.0.0/apksigner verify --print-certs app/build/outputs/apk/release/app-release.apk

AAB의 경우, jarsigner -verify -verbose app-release.aab 서명과 인증서 지문(fingerprint)을 확인합니다. Play Console의 앱 무결성(App integrity) 섹션에 표시된 SHA-256 값과 비교하세요.

6) CLI로 Google Play에 업로드하기

Play Console을 통한 수동 업로드도 가능합니다. 자동화를 원한다면 Google Cloud에서 서비스 계정을 생성하고, Play Console의 '사용자 및 권한'에서 액세스 권한을 부여한 뒤 JSON 키를 다운로드하세요. 그 다음 Google Play Developer API 또는 fastlane supply 같은 도구를 사용하여 업로드하면 됩니다:

bundle exec fastlane supply --aab android/app/build/outputs/bundle/release/app-release.aab \
  --track internal --json_key play-service-account.json --package_name com.example.app

새 앱의 첫 번째 업로드는 Play Console에서 수동으로 진행해야 합니다. API는 이미 존재하는 앱의 빌드만 수락하기 때문입니다.

7) 클라우드 대안: Capgo Build for Android

위의 방법들은 모두 작동하지만, 빌드하는 모든 머신에 keystore가 남게 됩니다. Capgo Build는 keystore를 암호화된 vault에 보관하며, 업로드한 android/ 준비된 프로젝트로부터 빌드하여 AAB를 Play 트랙으로 푸시할 수 있습니다.

자격 증명(credentials)을 한 번만 저장하세요:

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./release.jks \
  --keystore-alias "release" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

또는 bunx @capgo/cli@latest build init --platform android 가 가이드를 제공합니다. 그러면 모든 릴리스는 다음과 같습니다:

bun run build
bunx cap sync android
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release

로그가 터미널로 스트리밍됩니다. AAB 또는 APK의 --output-upload 다운로드 링크를 받으려면 다음을 추가하고, --ai-analytics 빌드 실패 원인을 자동으로 파악하려면 다음을 추가하세요. 동일한 명령어를 Windows, Linux, macOS 및 CI에서 실행할 수 있습니다. GitHub Actions 예제는 Android 빌드 가이드에서 확인할 수 있습니다..

Capgo는 준비된 native project만 전달받으므로, 프라이빗 npm 레지스트리와 web build secrets는 사용자의 환경에 안전하게 유지됩니다.

8) 웹 변경 사항을 위한 재빌드 중단하기

플러그인, 권한, 아이콘 및 Capacitor 업그레이드를 위해서는 서명된 Native Build가 필요합니다. 하지만 dist/, Capgo Live Updates 설치된 앱에 새 웹 번들을 직접 푸시하면 다음과 같은 작업을 수행할 수 있습니다:

bunx @capgo/cli@latest bundle upload --channel production

이를 통해 한 주 동안 반복되는 대부분의 Gradle 실행 시간을 줄일 수 있습니다.

문제 해결

• SDK location not found: 설정 ANDROID_HOME 또는 다음을 생성하세요 android/local.properties.
• Keystore was tampered with, or password was incorrect: 스토어 비밀번호가 틀렸거나, Git의 CRLF 변환으로 인해 파일이 손상되었습니다. 다음 항목을 *.jks 에서 바이너리로 표시하세요 .gitattributes 버전 관리가 꼭 필요한 경우에만 그렇게 하세요. 가급적이면 하지 않는 것이 좋습니다.
• Unsupported class file major version: JDK 버전이 21보다 높거나 낮습니다.
• Play Store의 AAB 거부: “signed with a different key”: Play App Signing이 업로드 키를 요구합니다. Play Console에 등록된 keystore를 사용하거나 업로드 키 재설정을 요청하세요.
• Windows에서 빌드 속도가 느린 경우: 제외 ~/.gradle 및 Defender에서 SDK를 제외하고, 프로젝트를 짧은 로컬 경로에 두세요.
• Gradle 메모리 부족(Out of memory): 추가 org.gradle.jvmargs=-Xmx4g 대상 android/gradle.properties.

요약

Capacitor Android release 빌드에는 Android Studio 대신 JDK, SDK, Gradle wrapper가 필요합니다. 다음 명령어로 keystore를 생성하고 keytool, 다음을 통해 서명하세요 keystore.properties, 다음으로 빌드하세요 bundleRelease, 그리고 Play API를 통해 upload 하세요. 노트북에서 keystore를 분리하고 모든 OS에서 동일한 명령어를 사용하고 싶다면, Capgo Build가 준비된 프로젝트로부터 signing과 upload를 모두 처리합니다.