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 用的是脚本里固定的命令,改配置时要把命令一起更新,否则线上仍按老参数出包。

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