跨平台开发 / 系统课时
拆分 dev、staging 和 prod 配置
拆分 dev、staging 和 prod 配置
同一套 Flutter 代码通常需要连接开发、预发布和生产环境,但 API 地址、日志策略和功能开关不能靠手工改源码切换。本课使用编译期环境变量拆分 dev、staging 和 prod,并建立清晰的使用边界,避免把测试配置带入正式包。
学习目标
- 区分 dev、staging 和 prod 的职责边界
- 使用
--dart-define向 Flutter 应用注入环境配置 - 在启动阶段校验环境值,降低错连服务的风险
先定义三个环境的边界
dev 面向日常开发,可以连接开发后端并开启较多诊断信息;staging 用于发布前联调和验收,应尽量接近生产配置;prod 只连接正式服务,并关闭仅供开发使用的开关。
| 环境 | 主要用途 | 典型约束 |
|---|---|---|
| dev | 本地开发、接口联调 | 可使用开发服务和调试日志 |
| staging | 集成测试、发布验收 | 配置尽量模拟生产,但数据与生产隔离 |
| prod | 正式发布 | 只允许生产端点和正式功能策略 |
环境名应描述部署目的,不要用开发者姓名、临时分支名代替稳定环境。例如 alice、test2 很难形成长期可维护的发布规则。
用编译期配置代替手改源码
Flutter 可以通过 --dart-define 注入编译期键值,并用 String.fromEnvironment 读取。下面是一个可直接放入 lib/main.dart 的完整示例:
import 'package:flutter/material.dart';
enum AppEnvironment { dev, staging, prod }
const envName = String.fromEnvironment(
'APP_ENV',
defaultValue: 'dev',
);
const apiBaseUrl = String.fromEnvironment('API_BASE_URL');
AppEnvironment parseEnvironment(String value) {
return AppEnvironment.values.firstWhere(
(item) => item.name == value,
orElse: () => throw StateError('Unsupported APP_ENV: $value'),
);
}
void main() {
// 启动时立即拒绝缺失的关键配置,避免运行后才暴露错误环境。
if (apiBaseUrl.isEmpty) {
throw StateError('API_BASE_URL is required');
}
final environment = parseEnvironment(envName);
runApp(MyApp(environment: environment));
}
class MyApp extends StatelessWidget {
const MyApp({super.key, required this.environment});
final AppEnvironment environment;
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
body: Center(
child: Text('${environment.name}\n$apiBaseUrl'),
),
),
);
}
}使用 staging 配置启动:
flutter run --dart-define=APP_ENV=staging --dart-define=API_BASE_URL=https://staging.example.com预期结果:
页面中央显示:
staging
https://staging.example.com实际设备、端口和构建日志会因本机环境不同而变化,但页面中的环境名与地址应与命令传入值一致。
为不同构建固定参数
开发时手写命令可以接受,但持续集成或发布流程不应依赖人工记忆。应把每个环境对应的参数固定到脚本或 CI 配置中,使构建行为可以重复和审查。例如生产 APK 可以使用:
flutter build apk --release --dart-define=APP_ENV=prod --dart-define=API_BASE_URL=https://api.example.com预期结果:
生成 release APK;应用读取到 APP_ENV=prod 和对应的生产 API_BASE_URL。staging 和 prod 的参数应由发布流水线维护,并在构建记录中可追踪。这样切换环境是选择一组明确的构建配置,而不是修改源码之后再记得改回来。
不要把秘密放进 dart-define
--dart-define 适合环境名、服务地址和非敏感功能开关,但不适合 API 私钥、签名密钥或长期令牌。编译进客户端的值最终可能被分析或提取,不能把它当作安全存储。
真正的秘密应保留在服务端或受保护的发布系统中;移动端只保存运行所需、即使被读取也不会导致核心凭据泄露的配置。
在发布前验证环境
生产构建前至少检查两件事:APP_ENV 必须是 prod,API 地址必须属于生产环境。更稳定的做法是在 CI 中固定生产构建命令,并限制开发配置进入正式发布流程。
如果启动时出现 Unsupported APP_ENV 或 API_BASE_URL is required,说明构建参数缺失或拼写错误,应先修正命令或流水线变量,而不是给代码增加静默回退。显式失败比带着错误环境继续运行更容易定位,也能减少误连服务的风险。