通过环境变量和 Flavor 机制，Flutter 项目可以灵活管理 dev/staging/prod 多套环境配置，实现一套代码多环境构建。

一、–dart-define 环境变量

1.1 传入环境变量

# 运行时传入
flutter run \
  --dart-define=API_BASE_URL=https://dev-api.example.com \
  --dart-define=APP_ENV=development \
  --dart-define=ENABLE_ANALYTICS=false

# 构建时传入
flutter build apk \
  --dart-define=API_BASE_URL=https://api.example.com \
  --dart-define=APP_ENV=production \
  --dart-define=ENABLE_ANALYTICS=true

# 使用配置文件（推荐）
flutter run --dart-define-from-file=.env.dev
flutter build apk --dart-define-from-file=.env.prod

1.2 .env 配置文件

// .env.dev
{
  "API_BASE_URL": "https://dev-api.example.com",
  "APP_ENV": "development",
  "ENABLE_ANALYTICS": "false",
  "SENTRY_DSN": ""
}

// .env.prod
{
  "API_BASE_URL": "https://api.example.com",
  "APP_ENV": "production",
  "ENABLE_ANALYTICS": "true",
  "SENTRY_DSN": "https://xxx@sentry.io/123"
}

1.3 在 Dart 代码中读取

class AppConfig {
  // const String.fromEnvironment 在编译时注入值
  static const String apiBaseUrl = String.fromEnvironment(
    'API_BASE_URL',
    defaultValue: 'https://api.example.com',
  );

  static const String appEnv = String.fromEnvironment(
    'APP_ENV',
    defaultValue: 'production',
  );

  static const bool enableAnalytics = bool.fromEnvironment(
    'ENABLE_ANALYTICS',
    defaultValue: true,
  );

  static const String sentryDsn = String.fromEnvironment('SENTRY_DSN');

  // 派生属性
  static bool get isDevelopment => appEnv == 'development';
  static bool get isProduction => appEnv == 'production';

  static void log() {
    if (isDevelopment) {
      print('Config: $apiBaseUrl ($appEnv)');
    }
  }
}

// 使用
final dio = Dio(BaseOptions(baseUrl: AppConfig.apiBaseUrl));

二、Flavor 配置

Flavor 让同一项目可以打出不同的 App（不同包名、图标、应用名）。

2.1 Android Flavor 配置

// android/app/build.gradle
android {
    flavorDimensions "environment"

    productFlavors {
        development {
            dimension "environment"
            applicationId "com.example.myapp.dev"
            versionNameSuffix "-dev"
            resValue "string", "app_name", "MyApp Dev"
        }
        staging {
            dimension "environment"
            applicationId "com.example.myapp.staging"
            versionNameSuffix "-staging"
            resValue "string", "app_name", "MyApp Staging"
        }
        production {
            dimension "environment"
            applicationId "com.example.myapp"
            resValue "string", "app_name", "MyApp"
        }
    }
}

2.2 iOS Flavor 配置（Scheme）

# 在 Xcode 中：
# 1. Product → Scheme → Manage Schemes
# 2. 创建 development、staging、production 三个 Scheme
# 3. 每个 Scheme 对应不同的 Build Configuration

# ios/Podfile 按 Configuration 区分
target 'Runner' do
  use_frameworks!

  if ENV['CONFIGURATION'] == 'Release-production'
    pod 'FirebaseAnalytics'
  end
end

2.3 运行 Flavor

# 运行特定 Flavor
flutter run --flavor development -t lib/main_dev.dart
flutter run --flavor production -t lib/main.dart

# 构建特定 Flavor
flutter build apk --flavor production -t lib/main.dart --release
flutter build ipa --flavor staging -t lib/main_staging.dart

2.4 Flavor 入口分离

// lib/main_dev.dart
void main() {
  AppConfig.init(
    environment: Environment.development,
    apiBaseUrl: 'https://dev-api.example.com',
  );
  runApp(const MyApp());
}

// lib/main_staging.dart
void main() {
  AppConfig.init(
    environment: Environment.staging,
    apiBaseUrl: 'https://staging-api.example.com',
  );
  runApp(const MyApp());
}

// lib/main.dart (production)
void main() {
  AppConfig.init(
    environment: Environment.production,
    apiBaseUrl: 'https://api.example.com',
  );
  runApp(const MyApp());
}

三、VS Code 启动配置

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Development",
      "request": "launch",
      "type": "dart",
      "program": "lib/main_dev.dart",
      "args": [
        "--flavor", "development",
        "--dart-define-from-file", ".env.dev"
      ]
    },
    {
      "name": "Production",
      "request": "launch",
      "type": "dart",
      "program": "lib/main.dart",
      "args": [
        "--flavor", "production",
        "--dart-define-from-file", ".env.prod"
      ]
    }
  ]
}

小结

👉 下一节：8.3 日志与调试