FlutterのFlavor設定完全ガイド：iOS/Android対応のマルチ環境を構築する

モバイルアプリ開発では、開発・ステージング・本番など複数の環境を切り替えて運用することがあります。
Flutterでのアプリ開発において、その運用に役立つのがFlavorです。

Flavorは、アプリを複数の環境ごとに設定を切り替えるための仕組みです。
例えば「開発環境ではテスト用API、本番環境では本番APIを使いたい」といった場合に、Flavorを使うことでビルド時に環境を選択し、自動的に異なる設定を適用することができます。

この記事では、そんな便利なFlavorの設定方法をご紹介します。iOS/Androidの両方に対応しているので、マルチプラットフォーム向けアプリの開発に役立ててください。

この記事はこんな人向けです

Flutterで複数環境のアプリビルドを構築したい方
iOS/Android両方のFlavor設定を網羅的に知りたい方
Firebase等の外部サービスを環境ごとに切り替えたい方

1. 概要：Flavorとは

Flutterでは「Flavor」という仕組みを使って、同一コードベースから異なる設定のアプリをビルドできます。

Flavorを使うことで、例えばこういった設定を環境ごとに切り替えられます：

アプリ名・アイコン：開発版と本番版を異なる見た目にすることで視覚的に区別できます
Bundle ID / Application ID：同一端末に複数環境のアプリを共存させることができます
APIエンドポイント：環境ごとに接続先の自動切り替えが可能です
Firebase設定：環境ごとに異なるFirebaseプロジェクトを使用できます

プラットフォームごとの実現方法

AndroidとiOSそれぞれにおいて、Flavorを定義する方法は下記のとおりです。

Android：Gradleの productFlavors 機能を使用
iOS：XcodeのSchemeとBuild Configurationを使用

それぞれ、詳しいやり方は記事中で説明していきます。

本記事で構築する環境(Flavor)

本記事では、Flutter公式ドキュメントを参考に、4環境（local、development、sandbox、production）のFlavor設定手順を解説します。

Flavor	用途	アプリ名	Bundle ID / Application ID
local	ローカル開発	[LOC] アプリ名	*.local
development	開発サーバー接続	[DEV] アプリ名	*.development
sandbox	ステージング環境	[SAN] アプリ名	*.sandbox
production	本番リリース	アプリ名	(サフィックスなし)

では、具体的な手順を紹介していきましょう。

2. Android側のFlavor設定

まずはAndroidでの構成方法です。
Gradleの productFlavors 機能を使用し、シンプルに定義できます。

build.gradleの設定

android/app/build.gradle に flavorDimensions と productFlavors を追加します。

android {
   // ... 既存の設定

   flavorDimensions += "default"

   productFlavors {
       create("local") {
           dimension = "default"
           manifestPlaceholders = [
               appName: "[LOC] アプリ名",
           ]
           applicationIdSuffix = ".local"
       }
       create("development") {
           dimension = "default"
           manifestPlaceholders = [
               appName: "[DEV] アプリ名",
           ]
           applicationIdSuffix = ".development"
       }
       create("sandbox") {
           dimension = "default"
           manifestPlaceholders = [
               appName: "[SAN] アプリ名",
           ]
           applicationIdSuffix = ".sandbox"
       }
       create("production") {
           dimension = "default"
           manifestPlaceholders = [
               appName: "アプリ名",
           ]
           applicationIdSuffix = ""
       }
   }
}

ポイント解説

flavorDimensions：Flavorのグループを定義します。複数の軸でFlavorを管理する場合に使用します（例：有料版/無料版 × 環境）
applicationIdSuffix：ベースのApplicationIDに追加されるサフィックスです。これにより同一端末に複数環境のアプリをインストール可能にできます。
manifestPlaceholders：次に説明するAndroidManifest.xmlで参照するための変数を定義します。

AndroidManifest.xmlでの変数参照

くわえて、android/app/src/main/AndroidManifest.xml でplaceholderを参照します。

<application
   android:label="${appName}"
   android:name="${applicationName}"
   android:icon="@mipmap/ic_launcher">
   <!-- ... -->
</application>

Android側の設定手順は以上です！

3. iOS側のFlavor設定

iOSのFlavor設定はAndroidより少し複雑です。
XcodeのSchemeとBuild Configurationを使用します。まずBuild ConfigurationとSchemeを作成し、それぞれを紐づけたあと、具体的な設定を定義していく流れです。

Build Configurationの作成

Xcodeで`Runner.xcodeproj`を開き、以下の手順でBuild Configurationを作成します。

プロジェクトナビゲータで Runner プロジェクトを選択
Info タブ → Configurations セクションを開く
「+」ボタンで以下のConfigurationを追加：

Configuration名	複製元
Debug-local	Debug
Debug-development	Debug
Debug-sandbox	Debug
Debug-production	Debug
Release-local	Release
Release-development	Release
Release-sandbox	Release
Release-production	Release
Profile-local	Release
Profile-development	Release
Profile-sandbox	Release
Profile-production	Release

重要：Configuration名は必ず {BuildType}-{flavor名} の形式にしてください。Flutterがこの命名規則でFlavorを識別します。

Schemeの作成

次に、各FlavorごとにSchemeを作成します。

Product → Scheme → New Scheme… を選択
Scheme名を入力（例：local、development、sandbox、production ）

重要：Scheme名は小文字で、Flavor名と完全に一致させるようにしてください。

SchemeとConfigurationの紐付け

作成したSchemeを、Configurationに割り当てていきます。

Product → Scheme → Manage Schemes… を開く
各Schemeを選択し「Edit...」をクリック
以下のように各アクションにConfigurationを割り当て：

localスキームの例：

アクション	Build Configuration
Run	Debug-local
Test	Debug-local
Profile	Profile-local
Analyze	Debug-local
Archive	Release-local

重要：全てのSchemeで「Shared」にチェックを入れてください。これにより.xcscheme ファイルがリポジトリにコミットされ、チームで共有できます。

作成されたSchemeファイル（ ios/Runner.xcodeproj/xcshareddata/xcschemes/ 配下）の例：

<?xml version="1.0" encoding="UTF-8"?>
<Scheme version = "1.7">
  <BuildAction parallelizeBuildables = "YES" buildImplicitDependencies = "YES">
     <!-- 省略 -->
  </BuildAction>
  <TestAction buildConfiguration = "Debug-local">
     <!-- 省略 -->
  </TestAction>
  <LaunchAction buildConfiguration = "Debug-local">
     <!-- 省略 -->
  </LaunchAction>
  <ProfileAction buildConfiguration = "Profile-local">
     <!-- 省略 -->
  </ProfileAction>
  <AnalyzeAction buildConfiguration = "Debug-local">
  </AnalyzeAction>
  <ArchiveAction buildConfiguration = "Release-local" revealArchiveInOrganizer = "YES">
  </ArchiveAction>
</Scheme>

Build Settingsの設定

各ConfigurationでのBundle IDやアプリ表示名を設定します。

Runner ターゲット → Build Settingsタブを開く
「+」→「Add User-Defined Setting」で以下のカスタム設定を追加：

DISPLAY_PRODUCT_NAME_PREFIX（アプリ名のプレフィックス）：

Configuration	値
Debug-local	[LOC]
Debug-development	[DEV]
Debug-sandbox	[SAN]
Debug-production	(空)
Release-*	同上
Profile-*	同上

PRODUCT_BUNDLE_IDENTIFIER：

Configuration	値
*-local	com.example.app.local
*-development	com.example.app.development
*-sandbox	com.example.app.sandbox
*-production	com.example.app

Info.plistの設定

ios/Runner/Info.plist でBuild Settings変数を参照します。
これにより、アプリのビルド時にはConfigurationごとに設定した値が使用されるようになります。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <!-- アプリ表示名：プレフィックス + アプリ名 -->
   <key>CFBundleDisplayName</key>
   <string>$(DISPLAY_PRODUCT_NAME_PREFIX)アプリ名</string>

   <!-- Bundle IDはBuild Settingsから自動取得 -->
   <key>CFBundleIdentifier</key>
   <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>

   <!-- その他の設定... -->
</dict>
</plist>

iOS側の設定は以上で完了です！

4. Firebase設定（FlutterFire CLI）

複数の設定ファイルを生成することで、Flavorごとに異なるFirebaseプロジェクトを使用することができます。ここではその設定方法を紹介します。

事前に準備しておくこと

各Flavorに対応したFirebaseプロジェクトが作成済み
Firebase CLIとFlutterFire CLIがインストール済み

# Firebase CLIのインストール
npm install -g firebase-tools
firebase login

# FlutterFire CLIのインストール
dart pub global activate flutterfire_cli

Flavor別の設定ファイルを生成

各Flavorに対して flutterfire config コマンドを実行し、設定ファイルを生成します。
こうすることで、FlutterFire CLIはDart設定ファイルの生成に加えて、iOS/Android両方の設定ファイルを適切な場所に配置し、必要なBuild Phase設定も自動で行います。

# development環境の設定
flutterfire config \
 --project=your-project-development \
 --out=lib/config/firebase/firebase_options_development.dart \
 --ios-bundle-id=com.example.app.development \
 --ios-out=ios/flavors/development/GoogleService-Info.plist \
 --android-package-name=com.example.app.development \
 --android-out=android/app/src/development/google-services.json

# sandbox環境の設定
flutterfire config \
 --project=your-project-sandbox \
 --out=lib/config/firebase/firebase_options_sandbox.dart \
 --ios-bundle-id=com.example.app.sandbox \
 --ios-out=ios/flavors/sandbox/GoogleService-Info.plist \
 --android-package-name=com.example.app.sandbox \
 --android-out=android/app/src/sandbox/google-services.json

# production環境の設定
flutterfire config \
 --project=your-project-production \
 --out=lib/config/firebase/firebase_options_production.dart \
 --ios-bundle-id=com.example.app \
 --ios-out=ios/flavors/production/GoogleService-Info.plist \
 --android-package-name=com.example.app \
 --android-out=android/app/src/production/google-services.json

　
ここで使用する主要なオプション

オプション	説明
--project	FirebaseプロジェクトID
--out	Dart設定ファイルの出力先
--ios-bundle-id	iOSのBundle ID
--ios-out	GoogleService-Info.plistの出力先
--android-package-name	AndroidのパッケージID
--android-out	google-services.jsonの出力先

生成されるファイル構成

コマンド実行後、以下のファイルが生成されます：

lib/config/firebase/
├── firebase_options_development.dart
├── firebase_options_sandbox.dart
└── firebase_options_production.dart

ios/flavors/
├── development/
│   └── GoogleService-Info.plist
├── sandbox/
│   └── GoogleService-Info.plist
└── production/
   └── GoogleService-Info.plist

android/app/src/
├── development/
│   └── google-services.json
├── sandbox/
│   └── google-services.json
└── production/
   └── google-services.json

つづいて、各FirebaseプロジェクトをDartのコード内から扱うための設定をします。

Flavor enumの定義

lib/config/env/flavor.dart でFlavorを定義します。Dart 3以降ではenumに直接メソッドやgetterを定義できます。

import 'package:firebase_core/firebase_core.dart';
import 'package:your_app/config/firebase/firebase_options_development.dart'
   as development;
import 'package:your_app/config/firebase/firebase_options_production.dart'
   as production;
import 'package:your_app/config/firebase/firebase_options_sandbox.dart'
   as sandbox;

enum Flavor {
 local,
 development,
 sandbox,
 production;

 /// Dart define から Flavor を取得
 static const _flavorStr = String.fromEnvironment('FLAVOR');
 static Flavor get fromDartDefine => Flavor.values.byName(_flavorStr);

 /// Firebase設定
 FirebaseOptions get firebaseOptions {
   switch (this) {
     case Flavor.local:
     case Flavor.development:
       return development.DefaultFirebaseOptions.currentPlatform;
     case Flavor.sandbox:
       return sandbox.DefaultFirebaseOptions.currentPlatform;
     case Flavor.production:
       return production.DefaultFirebaseOptions.currentPlatform;
   }
 }
}

設定自体はこれで完了です。

main.dartでの使用例

実際にDartのコード内でFirebaseを扱うにはこのようにします。

void main() async {
 WidgetsFlutterBinding.ensureInitialized();

 final flavor = Flavor.fromDartDefine;

 // Flavorに応じたFirebase初期化
 await Firebase.initializeApp(
   options: flavor.firebaseOptions,
 );

 runApp(MyApp(flavor: flavor));
}

以上で、Firebaseに関する設定は完了です。

5. アプリアイコンの切り替え

flutter_launcher_icons パッケージを使用して、Flavor別のアイコンを生成することもできます。
各環境用のアプリを視覚的に区別できるようになり、便利です。

アイコン画像の配置

各Flavor用のアイコン画像を作成し、assets/app_icons/ ディレクトリに配置します。

assets/
└── app_icons/
   ├── app_icon_local.png
   ├── app_icon_development.png
   ├── app_icon_sandbox.png
   └── app_icon_production.png

アイコン画像は1024x1024px以上の正方形PNGファイルを推奨します。

設定ファイルの作成

各Flavor用の設定ファイルを、プロジェクトルートに作成します。

flutter_launcher_icons-local.yaml：

flutter_launcher_icons:
 image_path: "assets/app_icons/app_icon_local.png"
 android: true
 ios: true
 remove_alpha_ios: true

　
flutter_launcher_icons-development.yaml：

flutter_launcher_icons:
 image_path: "assets/app_icons/app_icon_development.png"
 android: true
 ios: true
 remove_alpha_ios: true

　
flutter_launcher_icons-sandbox.yaml：

flutter_launcher_icons:
 image_path: "assets/app_icons/app_icon_sandbox.png"
 android: true
 ios: true
 remove_alpha_ios: true

　
flutter_launcher_icons-production.yaml：

flutter_launcher_icons:
 image_path: "assets/app_icons/app_icon_production.png"
 android: true
 ios: true
 remove_alpha_ios: true

アイコン生成

最後に、下記のコマンドを実行するとアイコンの生成が行われます。

# 全Flavorのアイコンを生成
dart run flutter_launcher_icons

# 特定Flavorのみ生成
dart run flutter_launcher_icons --flavor development

以上で、全ての設定が完了しました。

7. 実行方法

最後に、ここまでで設定したFlavorを使い、実際にアプリを実行／ビルドする方法を紹介します。

コマンドラインから実行

# local環境で実行
flutter run --flavor local --dart-define=FLAVOR=local

# development環境で実行
flutter run --flavor development --dart-define=FLAVOR=development

# sandbox環境でリリースビルド
flutter run --flavor sandbox --dart-define=FLAVOR=sandbox --release

# production環境でアーカイブ
flutter build ios --flavor production --dart-define=FLAVOR=production
flutter build appbundle --flavor production --dart-define=FLAVOR=production

Makefileでの管理

毎回コマンドを打つのは面倒なので、Makefileにまとめると便利です。

run: ## Run app. Pass F={local,development,sandbox,production}, M={profile,release} (optional)
ifeq (${M},)
 flutter run --flavor ${F} --dart-define=FLAVOR=${F}
else
 flutter run --flavor ${F} --dart-define=FLAVOR=${F} --${M}
endif

　
使用例：

make run F=development        # デバッグモード
make run F=production M=release  # リリースモード

IDE（VS Code / Android Studio）での実行

各IDEで実行する場合は、それぞれ設定が必要です。

VS Code（設定）
.vscode/launch.json に設定を追加：

{
 "version": "0.2.0",
 "configurations": [
   {
     "name": "Local",
     "request": "launch",
     "type": "dart",
     "args": ["--flavor", "local", "--dart-define=FLAVOR=local"]
   },
   {
     "name": "Development",
     "request": "launch",
     "type": "dart",
     "args": ["--flavor", "development", "--dart-define=FLAVOR=development"]
   },
   {
     "name": "Sandbox",
     "request": "launch",
     "type": "dart",
     "args": ["--flavor", "sandbox", "--dart-define=FLAVOR=sandbox"]
   },
   {
     "name": "Production",
     "request": "launch",
     "type": "dart",
     "args": ["--flavor", "production", "--dart-define=FLAVOR=production"]
   }
 ]
}