개발 중에는 서버 주소를 https://dev.example.com으로 쓰다가, 배포할 때 https://api.example.com으로 고치고 빌드하는 사람이 많다. 문제는 고치는 걸 깜빡하는 날이 온다는 것이다. 개발 서버 주소로 배포한 앱이 나가거나, 반대로 개발 중에 운영 서버에 테스트 데이터를 쓰고 지워버리는 사고가 난다.

또 하나의 불편이 있다. 개발용 앱을 폰에 설치한 상태에서 운영용 앱을 설치하면 같은 앱으로 취급되어 덮어씌워진다. 기기에 둘을 나란히 두고 비교해 볼 수가 없다.

class ApiConfig {
  // 배포 전에 이걸 바꿔야 함... 깜빡하면?
  static const baseUrl = 'https://dev.example.com';
}

원인: 환경이 코드 안에 하드코딩되어 있다

개발, 운영 같은 환경의 차이를 코드를 직접 고쳐서 맞추고 있다. 같은 코드에서 빌드할 때 환경을 고르는 방법이 필요하다. 이게 flavor다. 같은 소스에서 서로 다른 설정을 가진 앱을 여러 종류 만들어 낸다. 앱 이름, 앱 ID, 아이콘, 서버 주소가 환경마다 달라진다.

flavor가 바꾸는 것

• 앱 ID(패키지 이름): 개발용은 com.example.myapp.dev, 운영용은 com.example.myapp처럼 달라서 한 기기에 둘이 같이 설치된다
• 앱 이름과 아이콘: 홈 화면에서 "MyApp Dev"와 "MyApp"을 구분한다
• 서버 주소, 키 같은 설정값: Dart 코드에서 읽는다
• Firebase 프로젝트: 개발용 Firebase와 운영용 Firebase를 따로 쓴다

1단계: Android - productFlavors

android/app/build.gradle(또는 build.gradle.kts)의 android { } 안에 추가한다. Groovy 형식의 예시다.

android {
    // ...
    flavorDimensions "default"

    productFlavors {
        dev {
            dimension "default"
            applicationIdSuffix ".dev"
            versionNameSuffix "-dev"
            resValue "string", "app_name", "MyApp Dev"
        }
        prod {
            dimension "default"
            resValue "string", "app_name", "MyApp"
        }
    }
}

• flavorDimensions: flavor를 묶는 축이다. 지금은 하나면 된다
• applicationIdSuffix ".dev": 앱 ID 뒤에 .dev를 붙인다. 그래서 개발용과 운영용이 다른 앱으로 설치된다
• resValue "string", "app_name", ...: 앱 이름을 flavor마다 다르게 준다. AndroidManifest.xml의 android:label은 @string/app_name으로 바꿔 둔다

Kotlin 스크립트(build.gradle.kts)를 쓰는 프로젝트는 같은 구조를 코틀린 문법으로 적는다. 안드로이드의 빌드 변형(build variants)을 아는 사람이라면 익숙한 코드다.

2단계: iOS - 스킴과 빌드 설정

iOS 쪽이 더 손이 간다. Xcode에서 ios/Runner.xcworkspace를 열고 이렇게 한다.

• 빌드 설정(Configurations): 기존 Debug, Release를 복제해서 Debug-dev, Release-dev, Debug-prod, Release-prod처럼 flavor별로 만든다
• 스킴(Scheme): flavor 이름과 같은 이름의 스킴(dev, prod)을 만들어서, 각 스킴이 위의 빌드 설정을 쓰게 연결한다
• 앱 ID와 이름: 설정별로 PRODUCT_BUNDLE_IDENTIFIER(com.example.myapp.dev), PRODUCT_NAME을 다르게 준다

스킴 이름이 flutter run --flavor 이름의 이름과 정확히 같아야 한다. 이 설정을 손으로 하기 어려우면 flavorizr 같은 자동화 패키지가 두 플랫폼의 설정을 만들어준다. 다만 생성 결과가 무엇을 바꿨는지 한 번은 직접 확인해야 한다.

3단계: 실행과 빌드

flutter run --flavor dev
flutter run --flavor prod
flutter build appbundle --flavor prod
flutter build ipa --flavor prod

--flavor 이름이 Android는 productFlavors의 이름을, iOS는 스킴의 이름을 가리킨다.

설정이 빠졌을 때 나오는 에러가 이 단계의 단골이다.

• Android에 flavor를 정의했는데 --flavor 없이 실행하면, flavor를 지정하라는 취지의 에러가 난다
• iOS에 스킴이 없는데 --flavor를 주면, 사용자 지정 스킴이 없어서 --flavor를 쓸 수 없다는 취지의 에러가 난다

에러 메시지가 어느 플랫폼에 설정이 없는지 알려주니 메시지를 읽고 해당 쪽을 확인한다.

4단계: Dart 코드에서 환경 읽기 - dart-define

네이티브 설정은 앱 ID와 이름을 바꿀 뿐이고, 서버 주소 같은 값은 Dart 코드가 알아야 한다. 빌드할 때 값을 넘기는 --dart-define을 쓴다.

flutter run --flavor dev --dart-define=FLAVOR=dev
flutter run --flavor prod --dart-define=FLAVOR=prod

enum Flavor { dev, prod }

class AppConfig {
  final Flavor flavor;
  final String baseUrl;
  const AppConfig({required this.flavor, required this.baseUrl});

  static AppConfig fromEnvironment() {
    const name = String.fromEnvironment('FLAVOR', defaultValue: 'prod');
    return switch (name) {
      'dev' => const AppConfig(
          flavor: Flavor.dev,
          baseUrl: 'https://dev.example.com',
        ),
      _ => const AppConfig(
          flavor: Flavor.prod,
          baseUrl: 'https://api.example.com',
        ),
    };
  }
}

String.fromEnvironment('FLAVOR', defaultValue: 'prod')는 컴파일 때 들어온 값을 읽는다. 값이 없을 때를 위해 기본값을 둔다. 기본값을 prod로 두면 실수로 --dart-define을 빠뜨려도 개발용 서버가 아니라 운영 설정으로 가므로, 배포 사고 쪽으로는 안전하다. 반대 방향 실수(개발 중 운영 서버 데이터를 건드리는 것)는 defaultValue를 dev로 두는 편이 안전하다. 어느 사고가 더 무서운지 팀에서 정하자.

값이 여러 개면 파일로 묶어서 넘길 수 있다.

flutter run --flavor dev --dart-define-from-file=config/dev.json

{
  "FLAVOR": "dev",
  "BASE_URL": "https://dev.example.com"
}

이렇게 만든 AppConfig는 의존성 주입 글의 방식으로 앱 전체에 내려준다.

final appConfigProvider = Provider<AppConfig>(
  (ref) => throw UnimplementedError(), // main에서 바꿔 끼운다
);

void main() {
  final config = AppConfig.fromEnvironment();
  runApp(
    ProviderScope(
      overrides: [appConfigProvider.overrideWithValue(config)],
      child: const MyApp(),
    ),
  );
}

final dioProvider = Provider<Dio>(
  (ref) => Dio(BaseOptions(baseUrl: ref.watch(appConfigProvider).baseUrl)),
);

Dio를 만드는 곳이 appConfigProvider에서 서버 주소를 받으니, 환경이 바뀌어도 Dio를 만드는 코드는 그대로다. 시험할 때는 같은 방식으로 가짜 설정을 끼운다.

진입점을 나누는 방법도 있다

--dart-define 대신 lib/main_dev.dart, lib/main_prod.dart처럼 flavor별 main 파일을 두는 방식도 많이 쓴다.

// lib/main_dev.dart
void main() => bootstrap(AppConfig.dev);

// lib/main_prod.dart
void main() => bootstrap(AppConfig.prod);

flutter run --flavor dev -t lib/main_dev.dart

-t(--target)가 시작 파일을 정한다. 설정이 코드에 보이는 장점이 있지만, 매번 -t를 같이 써야 하는 번거로움이 있다. 둘 중 하나로 팀이 통일하면 된다.

삽질 포인트 1: dart-define은 비밀을 숨겨주지 않는다

--dart-define으로 넣은 값은 빌드된 앱 안에 그대로 들어간다. 앱을 분해하면 꺼내볼 수 있다. 그러니 서버 주소나 공개용 키는 괜찮지만, 서버의 비밀 키나 관리자 비밀번호는 넣으면 안 된다. 그런 값은 앱이 아니라 서버가 들고 있어야 한다.

삽질 포인트 2: Firebase는 flavor마다 설정 파일이 따로 필요하다

개발과 운영의 Firebase 프로젝트를 나누면 google-services.json(Android)과 GoogleService-Info.plist(iOS)도 둘이다. 안드로이드는 android/app/src/dev/google-services.json, android/app/src/prod/google-services.json처럼 flavor 폴더 안에 둔다. Firebase 글의 flutterfire configure도 flavor별로 따로 실행해서 firebase_options 파일을 나누거나 선택하게 해야 한다.

삽질 포인트 3: 아이콘과 이름으로 구별하지 않으면 헷갈린다

개발용과 운영용이 둘 다 설치되면 홈 화면에서 구별이 안 된다. 앱 이름에 "Dev"를 붙이고, 아이콘 모서리에 띠를 두르는 식으로 개발용을 눈에 띄게 만든다. 지난 글의 flutter_launcher_icons는 flutter_launcher_icons-dev.yaml처럼 flavor별 설정 파일을 지원한다.

Android, iOS와 비교하면

• Android: productFlavors와 buildTypes의 조합이 build variants가 된다. Flutter의 --flavor가 이 이름을 그대로 쓴다
• iOS: 스킴과 빌드 설정(xcconfig)이 같은 역할이다. Flutter의 --flavor는 스킴 이름을 가리킨다
• Compose, SwiftUI는 UI 프레임워크라서 환경 분리는 각 플랫폼의 빌드 설정을 쓴다

네이티브 개발에서 해온 build variants와 스킴이 그대로 쓰인다. Flutter가 더하는 건 --flavor 옵션으로 둘을 하나의 명령에 연결해 주는 것과, Dart 쪽에서 환경값을 읽는 --dart-define이다.

정리

• 서버 주소를 코드에서 고쳐가며 배포하면 개발용과 운영용이 뒤섞이는 사고가 나므로, 같은 코드에서 빌드할 때 환경을 고르는 flavor를 쓴다
• Android는 productFlavors(applicationIdSuffix로 앱 ID를 분리), iOS는 빌드 설정과 스킴을 만들고, 스킴 이름은 --flavor 이름과 같아야 한다
• flutter run --flavor dev처럼 실행하고, 설정이 빠졌을 때는 에러 메시지가 어느 플랫폼에서 빠졌는지 알려준다
• Dart에서 읽는 값은 --dart-define이나 --dart-define-from-file로 넘기고 String.fromEnvironment('FLAVOR', defaultValue: ...)로 읽으며, 기본값은 어느 쪽 사고가 더 무서운지 보고 정한다
• 읽은 설정은 AppConfig로 묶어서 provider로 내려주면, 환경이 바뀌어도 Dio 같은 코드는 고치지 않는다
• dart-define 값은 앱에 그대로 들어가므로 비밀 키를 넣지 않고, Firebase 설정 파일은 flavor 폴더에 따로 둔다

다음 글에서는 만든 앱을 실제로 사용자에게 내보내는 스토어 배포(Google Play, App Store)를 다뤄보겠다.