跨平台开发 / 系统课时
统一管理版本号和构建号
统一管理版本号和构建号
发布 Flutter 应用时,最容易出错的不是“版本号怎么写”,而是 Android、iOS 和 CI 各维护一份,最后彼此不一致。本节把 pubspec.yaml 作为默认版本源,并说明构建参数如何覆盖它,让两端发布信息保持可追踪、可递增。
学习目标
- 区分面向用户的版本号与用于区分构建产物的构建号
- 理解 Flutter 版本信息到 Android、iOS 原生字段的映射
- 能在本地与 CI 构建中验证实际写入的版本值
把版本信息放到一个源头
Flutter 项目通常在 pubspec.yaml 的 version 字段中维护默认版本,格式为 主版本.次版本.修订号+构建号。例如 2.3.0+47 中,2.3.0 是用户看到的发布版本,47 用来区分不同构建。
下面是配置文件片段示例,需放在项目根目录现有 pubspec.yaml 的顶层,与 name、environment 等字段同级。
version: 2.3.0+47Flutter 会把这两个值继续传给原生构建系统,不需要再在 Android Gradle 文件里手工维护同一组数字。这样可以减少“Dart 侧是 2.3.0,商店产物却还是 2.2.9”的漂移。
理解 Android 与 iOS 的映射
同一份 Flutter 版本信息会映射到两个平台的原生字段:Android 的版本号对应 versionName,构建号对应 versionCode;iOS 的版本号对应 CFBundleShortVersionString,构建号对应 CFBundleVersion。([Flutter Docs][1])

因此,日常开发只需决定两件事:对外发布版本是否变化,以及本次构建是否必须获得一个新的构建号。修复后重新上传同一发布版本时,可以保持 2.3.0 不变,只增加构建号。
在构建时覆盖版本
CI/CD 往往不希望提交代码时手工修改构建号。Flutter 构建命令可以使用 --build-name 和 --build-number 覆盖 pubspec.yaml 中的值,而且只影响本次构建,不会改写源文件。
下面构建一个 Android release APK:
flutter build apk --build-name=2.3.0 --build-number=47预期输出
Built build/app/outputs/flutter-apk/app-release.apk (<SIZE>)实际耗时与文件大小会随机器和依赖变化。若 Android SDK Command-Line Tools 的 apkanalyzer 已加入 PATH,可以直接检查 APK 中最终写入的版本:
apkanalyzer manifest version-name build/app/outputs/flutter-apk/app-release.apk
apkanalyzer manifest version-code build/app/outputs/flutter-apk/app-release.apk预期输出
2.3.0
47这一步比只看 pubspec.yaml 更可靠,因为它验证的是最终产物,而不是源配置。
建立可持续的发布规则
团队应把“发布版本”和“构建编号”分开管理。版本号用于表达对用户有意义的发布节奏;构建号应保证同一应用后续提交到商店的构建可以被区分,常见做法是让 CI 使用持续递增的流水线编号。
不要同时在 pubspec.yaml、android/app/build.gradle.kts 和 Xcode 中手工维护三套版本值。需要临时覆盖时交给构建参数,默认值仍保留在 pubspec.yaml,这样本地构建、CI 和两端商店产物才能围绕同一个版本源工作。