跨平台开发 / 系统课时

拆分 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 的完整示例:

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 配置启动:

bash
flutter run --dart-define=APP_ENV=staging --dart-define=API_BASE_URL=https://staging.example.com

预期结果:

text
页面中央显示:
staging
https://staging.example.com

实际设备、端口和构建日志会因本机环境不同而变化,但页面中的环境名与地址应与命令传入值一致。

为不同构建固定参数

开发时手写命令可以接受,但持续集成或发布流程不应依赖人工记忆。应把每个环境对应的参数固定到脚本或 CI 配置中,使构建行为可以重复和审查。例如生产 APK 可以使用:

bash
flutter build apk --release --dart-define=APP_ENV=prod --dart-define=API_BASE_URL=https://api.example.com

预期结果:

text
生成 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,说明构建参数缺失或拼写错误,应先修正命令或流水线变量,而不是给代码增加静默回退。显式失败比带着错误环境继续运行更容易定位,也能减少误连服务的风险。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

拆分 dev、staging 和 prod 配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通