Flutter项目怎么配置多环境打包

文章导读
Flutter 配多环境打包,核心是把“环境差异”拆成两类:一类需要在编译期注入到 Dart 代码里的常量(接口地址、环境名、开关),另一类是必须落到原生工程上的差异(包名/Bundle ID、应用名、图标、签名、推送与第三方 SDK 的 key)。前者用 --dart-define 或 --dart-define-from-file 就能解决,后者才需要 Android 的 productFla
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

Flutter 配多环境打包,核心是把“环境差异”拆成两类:一类需要在编译期注入到 Dart 代码里的常量(接口地址、环境名、开关),另一类是必须落到原生工程上的差异(包名/Bundle ID、应用名、图标、签名、推送与第三方 SDK 的 key)。前者用 --dart-define 或 --dart-define-from-file 就能解决,后者才需要 Android 的 productFlavors 和 iOS 的 scheme / xcconfig。先判断自己落在哪一类,再决定要不要动原生工程,能少改很多。

如果当前只是接口地址和调试开关不同,先用 --dart-define-from-file 加一份 env/*.json,配合 String.fromEnvironment 读取即可,不必改 Android/iOS 工程;一旦需要 dev 包和正式包同时装在一台机器上、或应用名/图标/推送证书不同,再引入 flavor,让包名后缀与签名区分开。两种方式都要在真机或模拟器上跑一次 flutter run 验证读到的值,并检查 release 产物里的域名与包名是否正确。

先确认当前场景和目标

动手前先把三件事确认清楚,否则配置做完还会返工。

  • 环境数量和差异项:通常至少 dev、staging、prod 三套。列一张表,写清每套的接口域名、环境名、是否开日志、第三方 key 是否不同。只有确实不同的项才值得配,其余保持一份默认值。
  • 产物是否需要共存与区分:开发和正式包要装在同一台手机上,就必须改 applicationId / Bundle ID 后缀;如果不需要共存,只改 Dart 常量和应用名就够了。
  • 目标平台:flavor 只在 Android、iOS、macOS 这类有原生工程的目标上生效;Web、Windows、Linux 没有 flavor 概念,只能靠 dart-define 或构建脚本区分。

同时确认团队现在的打包方式:是手动执行 flutter build,还是 CI 里跑脚本。CI 用的是脚本里固定的命令,改配置时要把命令一起更新,否则线上仍按老参数出包。

Flutter项目怎么配置多环境打包

按这个顺序处理

  1. 先建配置读取层。在 lib 下放一个统一入口,所有环境值只从这里取,避免各处散落硬编码。示例可直接替换:
    // lib/config/app_env.dart
    class AppEnv {
      static const String name = String.fromEnvironment('ENV', defaultValue: 'dev');
      static const String apiBase =
          String.fromEnvironment('API_BASE', defaultValue: 'https://dev.example.com');
      static bool get isProd => name == 'prod';
    }
    放在 lib/config/ 下,业务代码统一引用 AppEnv.apiBase。
  2. 按环境写 json 配置文件。在工程根目录建 env/ 目录,每个环境一份,键名与上面的常量一一对应:
    // env/dev.json
    {
      "ENV": "dev",
      "API_BASE": "https://dev.example.com",
      "APP_NAME": "Demo Dev"
    }
    prod.json 同理,只改值。这类文件里的值会在编译期写入产物,不要放服务端密钥。
  3. Android 侧加 flavor(只有需要区分包名时再做)。在 android/app/build.gradle 的 android 块里:
    flavorDimensions "env"
    productFlavors {
      dev {
        dimension "env"
        applicationIdSuffix ".dev"
        resValue "string", "app_name", "Demo Dev"
      }
      prod {
        dimension "env"
        resValue "string", "app_name", "Demo"
      }
    }
    再把 AndroidManifest.xml 的 android:label 改成 @string/app_name。flavor 名要与后续命令里的 --flavor 一致。
  4. iOS 侧建对应 scheme。在 Xcode 里以现有 Runner 配置为基础复制出 dev、prod 两个 scheme,并为每个 scheme 关联各自的 xcconfig 或 Build Configuration,在其中设置 Bundle Identifier 与 Display Name。这一步必须在 Xcode 里完成,仅靠命令行参数改不了 iOS 包名。
  5. 统一打包命令。日常调试和出包都用同一套参数:
    flutter run --flavor dev --dart-define-from-file=env/dev.json
    flutter build apk --release --flavor prod --dart-define-from-file=env/prod.json
    flutter build ipa --release --flavor prod --dart-define-from-file=env/prod.json
    如果不打算用 flavor,可以去掉 --flavor,只保留 --dart-define-from-file,其余不变。

顺序上建议先做第 1、2 步并跑通,再决定是否进入第 3、4 步。多数项目停在 dart-define 这一步就够用,flavor 属于需要区分安装包时才追加的成本。

改完后怎么验证

  • 运行期信号:带参数执行 flutter run,在首页或启动日志里打印 AppEnv.name 与 AppEnv.apiBase,确认输出与所选 env/*.json 一致。这是最直接的判断依据。
  • 产物名与包名:用 flavor 出包后,产物名通常带 flavor 前缀(如 app-dev-release.apk)。用 aapt dump badging 或 Android Studio 的 APK 分析查看 package 名,确认后缀为 .dev;iOS 则检查 ipa 的 Info.plist 里 CFBundleIdentifier 是否符合预期。
  • 安装共存:把 dev 与 prod 包先后装到同一台设备,两者能同时存在且应用名不同,说明 flavor 与 resValue 生效。
  • 默认构建仍可用:再执行一次不带 --flavor 的 flutter build apk --release。如果失败,说明项目里还有脚本或文档依赖旧命令,需要同步更新,否则他人本地构建会中断。
  • 敏感值检查:用 strings 或解压产物粗略检索域名,能搜到 dev 域名属正常现象,因为 dart-define 是编译期常量,这正好用来确认值是否真的注入了。

容易忽略的边界

  • dart-define 不是安全存储。值会保留在产物中,可被提取,接口密钥、签名盐值这类内容不要放进去,应走服务端下发或原生安全存储。
  • 包名后缀的连带影响。改 applicationId 或 Bundle ID 后,推送、深链、第三方登录回调、地图与支付 key 往往需要在新包名下重新登记,否则这些功能在 dev 包上会静默失败。
  • 版本号与覆盖安装。多环境共用同一 versionCode 且包名相同时,会互相覆盖。要么用包名后缀隔开,要么在命令里用 --build-number 区分。
  • 平台差异。Web 与桌面端没有 flavor,只能靠 dart-define 加构建脚本;macOS 需要额外配置,需结合当前 Flutter 版本确认支持情况。
  • 配置文件的存放。env/*.json 若含测试环境地址可提交仓库,含真实凭据的不要提交,改由 CI 变量在构建前生成文件。
  • 回退建议。若原生侧改动导致签名或 pod 依赖出问题,先退回只使用 --dart-define-from-file 的方案,保证调试与出包不中断,再单独排查 flavor 与 scheme 配置。