跨平台开发 / 系统课时
生成可追踪的构建版本
生成可追踪的构建版本
线上出现问题时,团队需要快速回答“这个包由哪次代码生成、使用了什么配置、对应哪个提交”。本篇介绍如何在 Flutter 发布流程中绑定 Git commit、构建号和版本信息,让每个安装包都具备可追踪能力。
学习目标
- 理解构建版本需要记录哪些关键元数据。
- 使用 Flutter 构建参数和代码生成方式关联版本信息。
- 建立可用于排查线上问题的版本追踪流程。
为什么需要构建版本追踪
移动应用发布后,用户设备上可能同时存在多个版本。如果没有额外信息,仅通过应用版本号很难确认某个问题来自哪次代码提交。
一个可追踪版本通常包含三类信息:用户可见版本、内部构建号和源码标识。
| 信息 | 作用 |
|---|---|
| versionName | 展示给用户的版本,例如 1.2.0 |
| buildNumber | 区分同版本多次构建 |
| Git commit | 定位具体源码状态 |
配置 Flutter 构建版本信息
Flutter 项目中的版本通常来自 pubspec.yaml。持续集成环境可以在构建时替换版本号,并将 Git 信息注入应用。
下面示例展示一种简单做法:在构建脚本中读取 Git commit,并通过 Dart 定义版本常量。
bash
#!/usr/bin/env bash
COMMIT=$(git rev-parse --short HEAD)
BUILD_NUMBER=<BUILD_NUMBER>
flutter build apk \
--build-name=1.2.0 \
--build-number=$BUILD_NUMBER \
--dart-define=GIT_COMMIT=$COMMIT预期输出
text
Building APK with version 1.2.0+<BUILD_NUMBER>
Dart define contains GIT_COMMIT=<commit><BUILD_NUMBER> 和 commit 值会随实际流水线变化,示例中的占位符需要由 CI 环境替换。
在应用中读取版本信息
应用可以通过 String.fromEnvironment 读取构建时注入的值,用于错误日志或诊断页面。
dart
const gitCommit = String.fromEnvironment('GIT_COMMIT', defaultValue: 'unknown');
void printBuildInfo() {
print('Running commit: $gitCommit');
}预期结果
text
Running commit: a1b2c3d实际输出取决于构建时传入的 Git commit。
发布流程中的使用方式
稳定流程通常是在构建阶段生成唯一标识,在发布阶段保留对应关系。出现线上异常时,可以根据用户反馈的版本号查询构建记录,再定位到源码提交、依赖版本和构建参数。
不要只依赖应用版本号。版本号适合用户沟通,commit 和构建号才适合工程排查。
按自己的节奏,确认真正理解。