flutter-config

Flavor 架构

• 定义三个 Flavor：dev、staging、prod
• 所有 Flavor 共用**单个 main.dart**入口点
• 通过 --dart-define-from-file 传入各 Flavor 的专属配置：

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

• 绝不要创建单独的 main_dev.dart、main_staging.dart、main_prod.dart 入口点

JSON 配置结构

• 在项目根目录的 config/ 目录中存放各 Flavor 的 JSON 配置文件：

  config/
  ├── dev.json
  ├── staging.json
  └── prod.json
  

• config/dev.json 示例：

  {
    "FLAVOR": "dev",
    "BASE_URL": "https://api-dev.example.com",
    "APP_NAME": "MyApp Dev",
    "ENABLE_LOGGING": "true",
    "ENABLE_CRASHLYTICS": "false"
  }
  

• 绝不要将密钥（API 密钥、签名凭据）放入这些 JSON 文件中：请使用 CI 注入的环境变量或 flutter_secure_storage
• 如果 config/*.json 包含任何特定于环境的密钥，请将其添加到 .gitignore；否则，为了方便团队协作，请将其提交

入口点模式

// lib/main.dart
void main() {
  const flavor = String.fromEnvironment('FLAVOR', defaultValue: 'dev');
  AppConfig.init(flavor: Flavor.fromString(flavor));
  runApp(const App());
}

• 通过 String.fromEnvironment('KEY') 或 bool.fromEnvironment('KEY') 读取所有编译时值
• 使用密封的 Flavor 枚举：sealed class Flavor { dev, staging, prod }
• AppConfig 是一个单例，用于保存 Flavor、基础 URL、功能标志和 Firebase 配置

环境配置

• 在集中的 AppConfig 类中存放各 Flavor 的配置：
  • baseUrl：各环境对应的 API 端点
  • enableLogging：仅在 dev 环境启用详细日志记录
  • enableCrashlytics：在 dev 环境中禁用
  • appName：各 Flavor 的显示名称（例如，“MyApp Dev”、“MyApp”）
• 所有值都通过 --dart-define-from-file 从 JSON 文件中读取：Dart 代码中不得硬编码各 Flavor 的逻辑
• 绝不要将密钥放入 JSON 配置文件中：请使用 flutter_secure_storage 或 CI 注入的环境变量

平台专属 Flavor 设置

Android

• 在 android/app/build.gradle 中定义 flavorDimensions 和 productFlavors：

  flavorDimensions "environment"
  productFlavors {
      dev { dimension "environment"; applicationIdSuffix ".dev"; resValue "string", "app_name", "MyApp Dev" }
      staging { dimension "environment"; applicationIdSuffix ".staging"; resValue "string", "app_name", "MyApp Staging" }
      prod { dimension "environment"; resValue "string", "app_name", "MyApp" }
  }
  

iOS

• 为每个 Flavor（Dev、Staging、Prod）创建 Xcode 方案。
• 使用 xcconfig 文件设置各 Flavor 的 Bundle ID、显示名称和签名。
• 在 ios/Runner.xcodeproj 中将 Flutter Flavor 映射到 Xcode 方案。
• Swift Package Manager 集成：配置 iOS Flavor 时，Xcode 方案会自动映射软件包依赖配置。SPM 无需修改 CocoaPods Podfile。确保在 Xcode Runner 项目设置的 Package Dependencies 中定义所有依赖项覆盖。

各 Flavor 的 Firebase 配置

• 为每个 Flavor（dev、staging、prod）使用独立的 Firebase 项目
• 将 google-services.json（Android）和 GoogleService-Info.plist（iOS）放入各 Flavor 专属目录
• 对每个环境使用带有 --project 标志的 flutterfire configure

构建命令

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

# Staging
flutter run --flavor staging --dart-define-from-file=config/staging.json

# Production release
flutter build appbundle --flavor prod --dart-define-from-file=config/prod.json --release
flutter build ipa --flavor prod --dart-define-from-file=config/prod.json --release

规则

• 绝不要硬编码特定于环境的值（URL、API 密钥、功能标志）
• 绝不要将生产环境密钥提交到代码仓库
• 每位团队成员都必须能够通过单条命令在本地运行任意 Flavor
• CI/CD 流水线必须明确指定 --flavor 和 --dart-define-from-file
• 使用单个 main.dart：绝不要为各 Flavor 创建单独的入口点