Version Name：参数的本质和设置

什么是 Version Name

Version Name — 是一个语义字符串，用于为用户标识应用程序的发布。与技术构建设标识符不同，此参数带有含义：用户根据它来评估新更新与之前更新的差异程度。

Version Name 显示在 Google Play 和 App Store 的应用程序卡片中、设备上的“关于应用程序”部分以及系统更新对话框中。开发人员在构建发布版本之前将其指定在项目配置文件中。

根据 Semantic Versioning 2.0 (2023)，Major.Minor.Patch 格式在 78% 的移动应用程序中使用。主版本在 API 不兼容变更时更改，次版本 — 在添加功能时，补丁 — 在修复错误时。

使用 Version Name 与用户沟通：他们应立即了解所提供更新的规模 — 主版本、次版本或修正版本。

语义版本的结构

语义版本由三个用点分隔的数字组成：Major.Minor.Patch。每个组件负责应用程序中特定级别的更改。

主版本 (Major) 在引入破坏向后兼容性的根本性更改时增加。次版本 (Minor) 在不影响现有功能的情况下添加新功能。补丁仅包含错误修复。

例如，版本 3.2.1 表示：第三个主版本，第二个次更新，第一个补丁。这个系统对开发人员和用户都易于理解。

Version Name 显示在哪里

Version Name 在几个关键位置对用户可见。在应用商店中，它显示在应用程序卡片的标题中和更新列表中。在设备上 — 在系统设置的“关于应用程序”部分。

在 Google Play 中，Version Name 显示在应用程序名称下方，影响用户的更新决定。在 App Store 中，版本字符串在查看应用程序页面时显示在同一位置。

根据 Apptentive (2024) 的研究，67% 的用户在更新前检查应用程序版本，可理解的语义使安装转化率提高 23%。

Android 上的 Version Name

在 Android 上，Version Name 通过 build.gradle 文件（模块级别）中的 versionName 参数设置。此参数是一个字符串，可以包含任何字符，包括点、连字符和字母。

该参数在 android.defaultConfig 块内与必需参数 versionCode 一起声明。Android 不对字符串格式施加限制，但 Google Play 建议使用语义格式。

根据 Android Developers (2025)，Google Play 使用 versionName 在商店界面上显示，但不会以编程方式分析其内容 — 只有 versionCode 影响更新逻辑。

以 Major.Minor.Patch 格式指定 Version Name，并将其与版本控制系统中的标签同步，以便精确标识发布。

Gradle 中 versionName 的特性

Gradle 允许在 build.gradle 中静态设置 versionName，或通过构建脚本动态设置。动态生成对于自动夜间构建和 CI/CD 流水线非常有用。

在 build.gradle 中，您可以使用环境变量、命令行参数或 shell 脚本调用来形成 versionName。典型的方法是从 version.properties 文件中读取版本。

这种灵活性使团队能够自动化版本控制过程，并消除发布准备中的人为因素。

iOS 上的 Version Name

在 iOS 上，Version Name 通过 Info.plist 文件中的 CFBundleShortVersionString 键设置。这是在 App Store 发布应用程序的必需参数，并且严格类型化为字符串。

与 Android 不同，App Store Connect 检查 Version Name 的格式，并要求符合点分隔数字的模式。字符串的最大长度为 18 个字符，每个版本组件不能超过 255。

根据 Apple Developer Documentation (2025)，CFBundleShortVersionString 被 App Store 用于在商店界面和用户设备上的系统对话框中显示版本。

在将构建上传到 App Store Connect 时，确保 Version Name 与营销材料中列出的版本一致 — 这简化了与用户的沟通。

与 Xcode 的集成

Xcode 提供图形界面用于在目标设置中更改 Version Name。“Marketing Version”字段位于 General 选项卡的 Identity 部分。更改会自动保存到 Info.plist。

对于自动化，您可以使用 Xcode Build Phases 中的构建脚本或 agvtool (Apple Generic Version Tool) 工具。agvtool 允许从命令行管理版本并与 CI/CD 集成。

这种方法在使用 fastlane 或 Jenkins 自动构建和交付应用程序时特别方便。

Version Name 与 Build Number 的区别

Version Name 和 Build Number 在开发过程中执行不同的任务。Version Name 是用户字符串，而 Build Number 是唯一标识每个构建的内部数字标识符。

Build Number（Android 中的 versionCode，iOS 中的 CFBundleVersion）必须随着每个新构建而增加，并被应用商店用于确定哪个版本更新。Version Name 可以保持同一版本的多个构建不变。

根据 Google Play Policy (2025)，两个具有相同 versionCode 的应用程序被视为同一版本 — versionCode 对于每个 APK 必须是唯一的。Version Name 不参与此检查。

始终在每次构建时增加 Build Number，仅在功能更改时更改 Version Name — 这可以防止发布时的冲突。

如何选择 Version Name

选择 Version Name 取决于团队的版本控制策略。最常见的方法是语义版本控制 (SemVer)，但也有其他替代方案，如日历版本控制或基于发布日期的版本控制。

Semantic Versioning 2.0 推荐使用 Major.Minor.Patch 格式，带有可选的预发布后缀。对于移动应用程序，Major.Minor 方案也很流行，其中省略补丁以简化理解。

日历版本控制 (CalVer) 使用发布日期作为版本号 — 例如 25.06（年份和月份）。这种方法适用于频繁发布的应用程序，其中语义不重要。

选择方案的建议

语义版本控制适用于具有公共 API 的应用程序，其中向后兼容性很重要。用户和集成商了解更新时预期的更改。

日历版本控制适用于用户更关心的发布的时效性而非更改规模的应用程序。例如，新闻聚合器或天气应用程序。

混合方案结合了两种方法：Major.Minor.RC，其中 RC 是特定发布候选版本的版本号。这种方案在活跃的 Beta 测试中很方便。

Version Name 配置示例

下面的代码示例展示了如何在 Android 和 iOS 上设置 Version Name。对于 Android 使用 Gradle，对于 iOS 使用 agvtool 配合 Xcode Build Settings。

在 Android 中配置 versionName

在 Android 中，版本在 app/build.gradle 文件的 defaultConfig 块内设置。versionName 参数接受字符串值。

android {
    defaultConfig {
        versionCode 3
        versionName "2.1.0"
    }
}

versionName 也可以从外部文件读取，或使用 Gradle Script 动态生成。

动态生成 versionName

动态版本由 CI/CD 系统的环境变量形成。这确保每个构建获得正确的版本号。

def getVersionName = {
    return System.getenv("VERSION_NAME") ?:
            "2.1.0"
}

android {
    defaultConfig {
        versionName getVersionName()
    }
}

这种方法自动化了版本控制，消除了构建与存储库中标签不匹配的风险。

在 iOS 中配置 CFBundleShortVersionString

在 iOS 中，可以通过 Xcode 或通过命令行使用 agvtool 设置版本。

# 设置营销版本
xcrun agvtool new-marketing-version 2.1.0

# 读取当前版本
xcrun agvtool what-marketing-version

agvtool 自动更新 Info.plist，并在 Xcode 项目的所有目标之间同步版本。