跨平台开发 / 系统课时

生成可追踪的构建版本

生成可追踪的构建版本

线上出现问题时,团队需要快速回答“这个包由哪次代码生成、使用了什么配置、对应哪个提交”。本篇介绍如何在 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 和构建号才适合工程排查。

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

目录与阅读设置

阅读设置

17

记录一个想法

生成可追踪的构建版本

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

登录哪都通