이전 목록으로
#Flutter#Architecture

Flutter Flavor로 Dev·Stage·Prod 배포 환경 안전하게 분리하기

Android Product Flavor와 iOS Scheme·Build Configuration, Flutter 진입점을 함께 사용해 개발·스테이지·운영 앱의 식별자, 앱 이름, API 주소와 Firebase 설정을 분리하는 방법을 정리한다.

환경 분리는 API URL만 바꾸는 작업이 아니다. 운영 앱 위에 테스트 앱을 덮어쓰지 않도록 패키지 ID를 분리하고, 아이콘과 앱 이름만 보고도 환경을 식별할 수 있어야 한다.

Android와 iOS의 설정 방식은 다르지만 Flutter CLI에서 사용하는 Flavor 이름은 동일하게 맞춘다.

환경 Flutter Flavor Android applicationId iOS Bundle ID
개발 dev com.example.sample.dev com.example.sample.dev
검증 stage com.example.sample.stage com.example.sample.stage
운영 prod com.example.sample com.example.sample
flowchart TD
    A[하나의 Flutter 코드] --> B[Dev Flavor]
    A --> C[Stage Flavor]
    A --> D[Prod Flavor]
    B --> E[개발 API와 상세 로그]
    C --> F[검증 API와 테스터 배포]
    D --> G[운영 API와 최소 로그]

전체 구성

flowchart TD
    A[Flutter CLI --flavor] --> B{플랫폼}
    B --> C[Android Product Flavor]
    B --> D[iOS Shared Scheme]
    C --> E[applicationId·리소스·Firebase]
    D --> F[Build Configuration]
    F --> G[Bundle ID·Info.plist·Firebase]
    E --> H[Dart AppConfig]
    G --> H

Flavor 이름은 Android Product Flavor, iOS Scheme, Dart 환경 이름에서 모두 dev, stage, prod로 통일한다. stage와 staging, prod와 production을 섞으면 CI 명령과 네이티브 설정을 연결하기 어려워진다.

Android: Product Flavor 설정

// android/app/build.gradle.kts
android {
    namespace = "com.example.sample"
    flavorDimensions += "environment"

    productFlavors {
        create("dev") {
            dimension = "environment"
            applicationIdSuffix = ".dev"
            // 앱 이름은 src/dev/res/values/strings.xml에서 정의한다.
        }
        create("stage") {
            dimension = "environment"
            applicationIdSuffix = ".stage"
            // 앱 이름은 src/stage/res/values/strings.xml에서 정의한다.
        }
        create("prod") {
            dimension = "environment"
            // 앱 이름은 src/prod/res/values/strings.xml에서 정의한다.
        }
    }
}
<!-- android/app/src/main/AndroidManifest.xml -->
<application android:label="@string/app_name" />

각 Flavor의 strings.xml에는 같은 키로 앱 이름을 둔다. Flutter의 현재 Android Flavor 문서는 AGP 9 이상에서 resValue()를 기본 설정 그대로 사용할 수 없으므로 리소스 파일 방식을 안내한다.

<!-- android/app/src/dev/res/values/strings.xml -->
<resources>
    <string name="app_name">Sample Dev</string>
</resources>

applicationIdSuffix는 기본 applicationId 뒤에 환경 접미사를 붙인다. Dev·Stage·Prod를 한 기기에 동시에 설치하려면 최종 applicationId가 서로 달라야 한다. namespace는 코드 패키지 영역이므로 환경별 설치 ID를 만들 목적으로 바꾸지 않는다.

필요하면 Flavor별 Android 리소스와 Manifest도 분리할 수 있다.

android/app/src/main/AndroidManifest.xml
android/app/src/dev/res/values/strings.xml
android/app/src/stage/res/values/strings.xml
android/app/src/prod/res/values/strings.xml

iOS: Scheme과 Build Configuration 설정

iOS에는 Product Flavor라는 이름의 기능이 없다. Xcode의 Scheme을 Flutter Flavor로 사용하고, 각 Scheme을 환경별 Build Configuration에 연결한다.

1. Scheme 만들기

ios/Runner.xcworkspace를 Xcode로 연 다음 Product > Scheme > Manage Schemes에서 다음 Scheme을 생성한다.

  • dev
  • stage
  • prod

세 Scheme 모두 Shared를 활성화해야 Flutter CLI와 CI에서 인식할 수 있다. 공유된 Scheme 파일은 일반적으로 다음 경로에 저장되며 Git에 커밋한다.

ios/Runner.xcodeproj/xcshareddata/xcschemes/

2. 환경별 Build Configuration 만들기

Runner 프로젝트의 Info > Configurations에서 기존 Debug, Profile, Release를 복제한다. Flavor 접미사는 Flutter CLI가 인식할 수 있도록 소문자로 작성한다.

Debug-dev       Profile-dev       Release-dev
Debug-stage     Profile-stage     Release-stage
Debug-prod      Profile-prod      Release-prod

각 Configuration의 Base Configuration은 Pods-Runner.xcconfig가 아니라 Flutter의 Debug.xcconfig 또는 Release.xcconfig 계열을 기준으로 연결한다.

Scheme의 실행 동작은 다음과 같이 매핑한다.

Scheme 작업 dev stage prod
Run·Test·Analyze Debug-dev Debug-stage Debug-prod
Profile Profile-dev Profile-stage Profile-prod
Archive Release-dev Release-stage Release-prod

3. Bundle ID와 앱 이름 분리

Runner Target의 Build Settings에 사용자 정의 값 APP_DISPLAY_NAME을 추가하고 Configuration별 값을 지정한다.

Configuration 접미사 PRODUCT_BUNDLE_IDENTIFIER APP_DISPLAY_NAME
-dev com.example.sample.dev Sample Dev
-stage com.example.sample.stage Sample Stage
-prod com.example.sample Sample

ios/Runner/Info.plist에서는 하드코딩 대신 Build Setting을 참조한다.

<key>CFBundleDisplayName</key>
<string>$(APP_DISPLAY_NAME)</string>

서로 다른 Bundle ID를 사용하면 Dev·Stage·Prod 앱을 한 iPhone에 동시에 설치할 수 있다. Apple Developer의 App ID, Provisioning Profile, Push Notification·Associated Domains 같은 Capability도 Bundle ID별로 등록해야 한다.

4. CocoaPods Configuration 매핑

기존 프로젝트에 Podfile이 있다면 추가한 Build Configuration을 Debug 또는 Release 계열로 알려준다.

# ios/Podfile
project 'Runner', {
  'Debug' => :debug,
  'Debug-dev' => :debug,
  'Debug-stage' => :debug,
  'Debug-prod' => :debug,
  'Profile' => :release,
  'Profile-dev' => :release,
  'Profile-stage' => :release,
  'Profile-prod' => :release,
  'Release' => :release,
  'Release-dev' => :release,
  'Release-stage' => :release,
  'Release-prod' => :release,
}

변경 후 ios 디렉터리에서 pod install을 실행하거나 Flutter 빌드를 다시 수행한다.

Dart 설정을 타입으로 관리하기

enum AppEnvironment { dev, stage, prod }

final class AppConfig {
  const AppConfig({
    required this.environment,
    required this.apiBaseUrl,
    required this.enableVerboseLog,
  });

  final AppEnvironment environment;
  final Uri apiBaseUrl;
  final bool enableVerboseLog;
}
// lib/main_stage.dart
import 'bootstrap.dart';

void main() {
  bootstrap(
    AppConfig(
      environment: AppEnvironment.stage,
      apiBaseUrl: Uri.https('stage-api.example.com'),
      enableVerboseLog: true,
    ),
  );
}
// lib/main_prod.dart
import 'bootstrap.dart';

void main() {
  bootstrap(
    AppConfig(
      environment: AppEnvironment.prod,
      apiBaseUrl: Uri.https('api.example.com'),
      enableVerboseLog: false,
    ),
  );
}

실행과 빌드

# Android 또는 iOS 실행
flutter run --flavor dev -t lib/main_dev.dart
flutter run --flavor stage -t lib/main_stage.dart

# Android 배포 파일
flutter build appbundle --flavor prod -t lib/main_prod.dart

# iOS 배포 파일
flutter build ipa --flavor prod -t lib/main_prod.dart

Android에서는 --flavor가 Product Flavor를, iOS에서는 같은 이름의 Xcode Scheme을 선택한다. iOS Scheme 이름과 Android Product Flavor 이름이 같아야 한 명령 체계를 CI에서도 공통으로 사용할 수 있다.

Flutter의 appFlavor를 사용하면 현재 선택된 Flavor를 Dart에서 확인할 수도 있다. Flavor 없이 빌드하면 null일 수 있으므로 운영 환경으로 조용히 대체하기보다 즉시 실패시키는 편이 안전하다.

import 'package:flutter/services.dart';

AppEnvironment currentEnvironment() {
  return switch (appFlavor) {
    'dev' => AppEnvironment.dev,
    'stage' => AppEnvironment.stage,
    'prod' => AppEnvironment.prod,
    _ => throw StateError('빌드 Flavor가 지정되지 않았습니다: $appFlavor'),
  };
}

--dart-define은 공개되어도 문제가 없는 환경 값에 적합하다. API Secret이나 서명 키를 넣어 앱에 숨기는 용도로 사용해서는 안 된다. 모바일 앱에 포함된 값은 결국 추출될 수 있다.

Firebase 설정 분리

Android의 패키지 이름과 iOS의 Bundle ID마다 Firebase 앱을 각각 등록한다. 운영 데이터 보호가 중요하다면 Dev·Stage·Prod를 서로 다른 Firebase 프로젝트로 분리하는 것이 안전하다.

Android

android/app/src/dev/google-services.json
android/app/src/stage/google-services.json
android/app/src/prod/google-services.json

각 Firebase 앱의 Android Package Name이 Flavor의 실제 applicationId와 일치해야 한다.

iOS

iOS의 GoogleService-Info.plist도 Scheme이 선택한 Bundle ID와 일치해야 한다. 다음과 같이 원본 파일을 환경별로 보관한 뒤, Xcode Build Phase에서 선택된 Configuration에 맞는 파일 하나만 앱 번들에 GoogleService-Info.plist라는 이름으로 복사하는 방식을 사용할 수 있다.

ios/config/dev/GoogleService-Info.plist
ios/config/stage/GoogleService-Info.plist
ios/config/prod/GoogleService-Info.plist
# Xcode Run Script Build Phase 예시
case "${CONFIGURATION}" in
  *-dev)   FIREBASE_ENV="dev" ;;
  *-stage) FIREBASE_ENV="stage" ;;
  *-prod)  FIREBASE_ENV="prod" ;;
  *) echo "Unknown configuration: ${CONFIGURATION}"; exit 1 ;;
esac

cp "${PROJECT_DIR}/config/${FIREBASE_ENV}/GoogleService-Info.plist" \
   "${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/GoogleService-Info.plist"

FlutterFire CLI의 firebase_options.dart를 환경별로 생성해 Firebase.initializeApp(options: ...)에 명시적으로 전달하는 방식도 사용할 수 있다. 어느 방식을 선택하든 패키지명·Bundle ID·Firebase App ID가 같은 환경을 가리키는지 CI에서 검증한다.

환경 매핑 체크표

항목 Dev Stage Prod
Android Flavor dev stage prod
iOS Scheme dev stage prod
Dart target main_dev.dart main_stage.dart main_prod.dart
설치 식별자 .dev .stage 접미사 없음
API 개발 검증 운영
Firebase 개발용 검증용 운영용
로그 상세 상세 또는 제한 최소

흔한 실수

  • Stage와 Prod가 같은 앱 이름·아이콘을 사용한다.
  • 진입점은 Stage인데 --flavor prod로 빌드한다.
  • Android Flavor 이름과 iOS Scheme 이름이 다르다.
  • iOS Scheme을 Shared로 설정하거나 Scheme 파일을 Git에 커밋하지 않는다.
  • Debug-stage만 만들고 Profile-stage, Release-stage를 빠뜨린다.
  • Podfile에 사용자 정의 iOS Configuration을 매핑하지 않는다.
  • Bundle ID별 Signing·Capability 설정을 누락한다.
  • Flavor별 Firebase 앱 등록을 누락한다.
  • Stage Firebase 설정이 운영 프로젝트나 운영 Analytics를 가리킨다.
  • 운영 API 주소가 공용 상수에 하드코딩되어 있다.
  • 로그와 디버그 메뉴가 운영 빌드에도 노출된다.
  • Shorebird Release와 Patch에서 서로 다른 Flavor·Target을 사용한다.

관련 문서

목록으로 돌아가기

다른 게시글

#Android#Flutter

현장 Flutter 앱 디버깅에 자주 쓴 ADB 명령어

기기 지정, Logcat, APK 설치, 파일 복사, 포트 reverse를 실기기 점검 흐름으로 정리한다.

#Android#Kotlin

Android 입력 장치 목록 조회하기: 키보드·마우스·HID 스캐너 구분

Android `InputManager`와 `InputDevice` API로 연결된 입력 장치를 조회하고, 키보드·포인터·외부 장치 여부를 판별하는 방법을 정리한다. USB·Bluetooth HID 바코드 스캐너를 일반 키보드와 구분할 때의 한계와 연결 변경 감지 방법도 함께 살펴본다.

#Android#Kotlin

Android 위치 권한과 FusedLocationProvider 실전 정리: 현재 위치·지속 추적·GPS 설정

Jetpack Compose 앱에서 Android 위치 권한을 요청하고, Fused Location Provider로 캐시 위치·일회성 현재 위치·지속 위치 업데이트를 처리하는 흐름을 정리한다. Android 12의 대략적·정확한 위치 선택, 백그라운드 위치 정책, GPS 설정 확인과 생명주기 연동까지 예제 코드로 살펴본다.