플러터, 구글에 배포할 때 주의할 점

Flutter로 개발한 앱을 구글 플레이 콘솔에 배포하려면, 사소해 보이지만 놓치면 크게 막히는 여러 가지 요소들을 사전에 체크해야 합니다. Android App Bundle(AAB) 업로드나 패키지 이름, 서명 관련 설정이 잘못되면 빌드가 거부되거나 이전 버전으로 업데이트가 불가할 수 있어요. 특히 협업 중이거나 CI/CD를 사용하는 프로젝트라면, 모든 설정의 일관성이 핵심입니다. 이 글에서는 세 가지 중요한 배포 포인트—버전 관리, 서명 & SHA‑1, 패키지 이름—을 중심으로 설명드릴게요.

 

 

버전 코드 & 이름 관리

구글 플레이는 AAB 또는 APK의 버전 코드(versionCode)가 중복되거나 낮아지면 업로드를 막습니다.

 

앱 업그레이드가 원활히 이루어지려면 versionCode는 반드시 이전 버전보다 커야 하고, versionName은 사용자에게 보여지는 버전 정보로 혼동되지 않도록 관리해야 합니다. Flutter에서는 android/app/build.gradle 파일에서 다음과 같이 설정합니다.

defaultConfig {
  applicationId "com.example.myapp"
  minSdkVersion 21
  targetSdkVersion 34
  versionCode 3          // 반드시 증가시킬 것
  versionName "1.0.2"    // 읽기 쉬운 버전 문자열
}

 

이 설정이 잘못돼 versionCode가 낮거나 versionName만 바꾸면, 플레이 콘솔에서 “버전코드가 이미 존재합니다” 또는 “이전 버전이 최신입니다” 같은 에러 메시지를 만나게 됩니다.

 

따라서 배포 전 항상 이전 빌드의 versionCode를 확인하고 증가시키기를 추천합니다.

 

 

서명 키와 SHA-1 설정

구글 플레이 콘솔에서 AAB(Android App Bundle) 파일을 업로드하려면, 릴리즈용 서명 키가 반드시 포함되어 있어야 합니다. Flutter 프로젝트의 경우, Android에서 서명 키 설정은 android/key.properties와 android/app/build.gradle 파일을 통해 진행하게 됩니다. 이 키스토어는 앱이 정식으로 배포되는 것을 보장하는 중요한 보안 요소예요.

 

예를 들어, key.properties에는 다음과 같은 정보가 포함됩니다.

storePassword=mypassword
keyPassword=mykeypassword
keyAlias=mykey
storeFile=/Users/yourname/key.jks

 

그리고 build.gradle에는 이 정보를 읽어 서명 설정을 자동으로 적용하도록 구성하죠.

signingConfigs {
    release {
        def keystoreProperties = new Properties()
        def keystoreFile = rootProject.file("key.properties")
        if (keystoreFile.exists()) {
            keystoreProperties.load(new FileInputStream(keystoreFile))
        }

        keyAlias keystoreProperties['keyAlias']
        keyPassword keystoreProperties['keyPassword']
        storeFile file(keystoreProperties['storeFile'])
        storePassword keystoreProperties['storePassword']
    }
}

 

이 외에도 Firebase와 같은 외부 서비스를 연동하기 위해서는 SHA-1 인증서 지문이 필요합니다. 이 SHA-1 값은 keystore 기반으로 생성되며, 구글 클라우드 콘솔이나 Firebase에 앱을 등록할 때 꼭 입력해야 여러 기능이 제대로 작동합니다.

 

배포 전에 서명 키가 정확히 설정돼 있고, SHA-1 지문이 Firebase 등에 연동되어 있는지 꼭 확인하세요. 앱이 정상 설치되더라도 인증이나 알림, 앱 링크 기능이 동작하지 않을 수 있어요.

 

 

패키지 이름과 번들 ID의 일관성

플러터 앱을 구글 플레이 콘솔에 배포할 때 또 하나 중요한 포인트는 패키지 이름(package name)입니다. 안드로이드에서는 이 패키지 이름이 앱의 고유한 식별자 역할을 하기 때문에, 한 번 등록된 앱은 동일한 패키지 이름을 유지해야 합니다. 만약 실수로 개발 단계에서 사용하던 임시 패키지 이름(com.example.test)으로 AAB를 빌드해서 업로드하면, 나중에 실제 앱명과 맞지 않아 앱을 새로 등록해야 하는 낭비가 발생할 수 있습니다.

 

패키지 이름은 android/app/src/main/AndroidManifest.xml에 정의되어 있으며, build.gradle에서도 함께 관리됩니다. 앱을 릴리즈하기 전에는 반드시 이 값이 실제 프로젝트 명과 브랜드에 맞게 잘 설정되어 있는지 확인해야 합니다. 또한 Firebase나 Supabase 등 외부 연동 서비스들도 패키지 이름을 기준으로 인증 연동을 하기 때문에, 도중에 바꾸게 되면 여러 서비스 설정을 다시 해야 하는 번거로움도 생길 수 있어요.

 

 

마치며...

Flutter 앱을 구글 플레이에 배포하는 과정은 처음에는 다소 복잡하게 느껴질 수 있습니다. 하지만 핵심 포인트 몇 가지만 잘 기억하면, 반복적으로 효율적인 배포를 진행할 수 있습니다.

 

가장 중요한 건 버전 코드 관리, 서명 키 및 SHA-1 설정, 그리고 패키지 이름의 일관성입니다. 이 세 가지를 신경 쓰지 않으면, 앱이 정상적으로 빌드되었더라도 플레이 콘솔 업로드 단계에서 막히거나, 추후 외부 서비스와의 연동이 꼬이는 상황이 생길 수 있어요.

 

한 번 경험을 쌓고 나면, 다음 배포는 훨씬 수월해집니다. 안정적인 앱 배포를 위해 위의 항목들을 체크리스트처럼 활용해 보세요.