Android Studio는 훌륭한 IDE이지만, 스토어에 올릴 Android 빌드를 만드는 데 꼭 필요한 건 아닙니다. 생성된 android/ Capacitor 프로젝트의 폴더에는 어떤 터미널에서든 빌드와 서명을 처리하는 Gradle 래퍼가 들어 있습니다. 디스플레이가 없는 Linux 서버, Studio가 느린 Windows 머신, 그리고 CI에서 특히 중요합니다.
이 가이드에서는 명령줄만으로 서명된 AAB를 빌드한 다음, Capgo 빌드 를 사용해 키스토어를 노트북에 두지 않으려는 팀을 위한 클라우드 방식을 소개합니다.
사전 요구사항
- JDK 21(
java -version21이 출력됩니다). - Android command line SDK와 함께
platform-tools,build-tools그리고 Capacitor 버전에 맞는 플랫폼(API 36은 Capacitor 8, API 35는 Capacitor 7). 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 (gitignore됨):
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 설치 가이드 엣지 케이스를 다룹니다.
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 서명 및 인증서 지문을 확인합니다. SHA-256 값을 Play Console의 앱 무결성(App integrity) 섹션에 표시된 값과 비교하세요.
6) 명령줄에서 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) 클라우드 대안: Android용 Capgo Build
위 방법들은 모두 작동하지만, 빌드를 수행하는 모든 머신에 keystore가 남게 됩니다. Capgo Build는 keystore를 암호화된 볼트에 보관하고, 업로드한 준비된 android/ 프로젝트에서 빌드를 수행하며, AAB를 Play 트랙에 푸시할 수 있습니다.
자격 증명을 한 번만 저장하세요:
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
로그가 터미널에 스트리밍됩니다. --output-upload 을 추가하여 AAB 또는 APK의 다운로드 링크를 얻고, --ai-analytics 빌드 실패 원인을 자동으로 설명받으세요. 동일한 명령어는 Windows, Linux, macOS, CI에서 모두 실행됩니다. GitHub Actions 예제는 Android 빌드 가이드.
Capgo는 준비된 네이티브 프로젝트만 받으므로, 비공개 npm 레지스트리와 웹 빌드 시크릿은 사용자 환경에 그대로 유지됩니다.
8) 웹 변경 사항으로 다시 빌드하지 않기
플러그인, 권한, 아이콘 및 Capacitor 업그레이드에는 서명된 네이티브 빌드가 필요합니다. 모든 dist/, Capgo Live Update 새 웹 번들을 설치된 앱에 직접 푸시하세요:
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에서 AAB 거부: “signed with a different key”: Play App Signing은 업로드 키를 요구합니다. Play Console에 등록된 keystore를 사용하거나 업로드 키 재설정을 요청하세요.
- Windows에서 빌드가 느릴 때: 제외
~/.gradleDefender에서 SDK도 제외하고, 프로젝트는 짧은 로컬 경로에 두세요. - Gradle 메모리 부족: 추가
org.gradle.jvmargs=-Xmx4g대상android/gradle.properties.
요약
Capacitor Android release에는 Android Studio가 아니라 JDK, SDK, Gradle wrapper가 필요합니다. keystore는 다음으로 생성하고, keytool, 다음을 통해 서명하고, keystore.properties, 다음으로 빌드하세요. bundleRelease, 그리고 Play API로 업로드합니다. 키스토어를 노트북에 두지 않고 모든 OS에서 같은 명령을 쓰려면, Capgo Build가 준비된 프로젝트에서 서명과 업로드를 처리합니다.