문제 상황
Google Play Console에 Flutter 앱을 업로드하려고 할 때 다음과 같은 오류가 발생했습니다:
디버그 모드로 서명한 APK 또는 Android App Bundle을 업로드했습니다.
출시 모드로 APK 또는 Android App Bundle에 서명해야 합니다.
이 오류는 앱이 디버그 키로 서명되어 있어서 발생하는 문제입니다.
Play Store에 업로드하려면 반드시 **출시용 키(Release Key)**로 서명된 앱이 필요합니다.
해결 방법
1단계: Keystore 생성
먼저 앱 서명에 사용할 키스토어(Keystore) 파일을 생성해야 합니다.
프로젝트 루트 디렉토리에서 터미널을 열고 다음 명령어를 실행합니다:
cd android/app
keytool -genkey -v -keystore upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload명령어를 실행하면 다음 정보를 입력하라는 프롬프트가 나타납니다:
1. 키스토어 비밀번호: 안전한 비밀번호를 입력하세요 (이 비밀번호는 꼭 기억해야 합니다!)
2. 이름 및 조직 정보: 이름, 조직 단위, 조직명, 도시, 주/도, 국가 코드 등을 입력합니다
3. 키 비밀번호: 키스토어 비밀번호와 동일하게 하려면 Enter를 누릅니다
===== 예시
이름과 성: (예: 홍길동)
조직 단위: (예: 개발팀)
조직: (예: Magic Spells App)
구/군/시: (예: 서울)
시/도: (예: 서울)
국가 코드: KR
완료되면 `android/app` 디렉토리에 `upload-keystore.jks` 파일이 생성됩니다.
2단계: key.properties 파일 생성
프로젝트의 `android/key.properties` 파일을 새로 생성하고 다음 내용을 작성합니다:
# 키스토어 비밀번호
storePassword=여기에_입력한_키스토어_비밀번호
# 키 비밀번호
keyPassword=여기에_입력한_키_비밀번호
# 키 별칭
keyAlias=upload
# 키스토어 파일 경로
storeFile=upload-keystore.jks⚠️ **주의**: 실제 비밀번호로 바꿔서 입력하세요!
3단계: .gitignore 설정 (중요!)
보안을 위해 키스토어 파일과 비밀번호 정보가 Git에 커밋되지 않도록 해야 합니다.
`android/.gitignore` 파일에 다음 내용을 추가하세요:
key.properties
*.jks
*.keystore만약 `android/.gitignore` 파일이 없다면 새로 만들어서 위 내용을 추가합니다.
4단계: build.gradle.kts 수정
`android/app/build.gradle.kts` 파일을 수정하여 릴리즈 빌드 시 생성한 키스토어로 서명하도록 설정합니다.
파일 상단 부분을 다음과 같이 수정합니다:
plugins {
id("com.android.application")
id("kotlin-android")
id("dev.flutter.flutter-gradle-plugin")
}
// key.properties 파일 로드
val keystoreProperties = Properties()
val keystorePropertiesFile = rootProject.file("key.properties")
if (keystorePropertiesFile.exists()) {
keystoreProperties.load(keystorePropertiesFile.inputStream())
}
android {
namespace = "cohttp://m.magicspells.app" // 본인의 네임스페이스
compileSdk = flutter.compileSdkVersion
ndkVersion = flutter.ndkVersion
compileOptions {
sourceCompatibility = JavaVersion.VERSION_11
targetCompatibility = JavaVersion.VERSION_11
}
kotlinOptions {
jvmTarget = JavaVersion.VERSION_11.toString()
}
defaultConfig {
applicationId = "cohttp://m.magicspells.app" // 본인의 앱 ID
minSdk = flutter.minSdkVersion
targetSdk = flutter.targetSdkVersion
versionCode = 1
versionName = "1.0.0"
}
// Release 서명 설정
signingConfigs {
create("release") {
keyAlias = keystoreProperties["keyAlias"] as String
keyPassword = keystoreProperties["keyPassword"] as String
storeFile = file(keystoreProperties["storeFile"] as String)
storePassword = keystoreProperties["storePassword"] as String
}
}
buildTypes {
release {
signingConfig = signingConfigs.getByName("release")
}
}
}
flutter {
source = "../.."
}주요 변경 사항:
- `key.properties` 파일을 로드하는 코드 추가
- `signingConfigs` 블록에서 release 서명 설정 추가
- `buildTypes.release` 블록에서 디버그 서명을 release 서명으로 변경
5단계: Release 빌드 생성
이제 출시용 앱을 빌드할 준비가 되었습니다.
AAB 빌드 (Google Play Store 업로드용, 권장):
flutter build appbundle --release빌드가 완료되면 다음 경로에 파일이 생성됩니다:
- `build/app/outputs/bundle/release/app-release.aab`
APK 빌드 (직접 배포용):
flutter build apk --release빌드가 완료되면 다음 경로에 파일이 생성됩니다:
- `build/app/outputs/flutter-apk/app-release.apk`
6단계: Google Play Console에 업로드
생성된 AAB 파일을 Google Play Console의 프로덕션, 비공개 테스트, 내부 테스트 트랙에 업로드합니다.
이제 "디버그 모드로 서명" 오류 없이 정상적으로 업로드할 수 있습니다! ✅
중요한 보안 주의사항
🔐 **반드시 백업하고 안전하게 보관해야 할 파일:**
- `upload-keystore.jks`
- `key.properties`
이 파일들을 분실하면 앱 업데이트가 불가능해집니다!
❌ 절대 하지 말아야 할 것:
- 키스토어 파일을 Git에 커밋하기
- 비밀번호를 공개 저장소에 올리기
- 키스토어 파일을 다른 사람과 공유하기
💡 권장 사항:
- 키스토어 파일을 여러 곳에 안전하게 백업
- 비밀번호를 안전한 비밀번호 관리 도구에 저장
- 필요하다면 암호화된 클라우드 스토리지에 저장
마무리
Flutter 앱을 Google Play Store에 출시할 때 가장 많이 겪는 오류 중 하나인 디버그 서명 문제를 해결하는 방법을 알아보았습니다.
핵심은 출시용 키스토어를 생성하고, build.gradle.kts 파일에 서명 설정을 추가하는 것입니다. 한 번 설정해두면 이후 빌드할 때마다 자동으로 출시용 키로 서명됩니다.
