Marketing Version：是什么，与 Build Number 的区别及安装

什么是 Marketing Version

Marketing Version — 是一个语义字符串，表示最终用户的应用程序版本。在 iOS 中通过 CFBundleShortVersionString 键设置，在 Android 中通过 versionName 参数设置。

“Marketing Version” 术语在 Xcode 中正式使用：在目标设置界面中，该字段名为 “Marketing Version”，在 Info.plist 中对应 CFBundleShortVersionString。在 Android 中，对应的是 versionName，尽管该术语使用较少。

根据 Apple Developer Documentation (2025)，Marketing Version 最多应由三个以点分隔的数字组成，不含空格和特殊字符。每个数字不应超过 255。

选择反映更改重要性的 Marketing Version：重大更改使用主版本更新，新功能使用次版本更新。

与内部 Build Number 的区别

Marketing Version 在目的上与 Build Number 有根本区别：前者通知用户，后者为商店标识构建。Build Number 可以增加而不改变 Marketing Version。

例如，在修复已发布版本中的关键错误时，团队可以使用相同的 Marketing Version (1.2.0) 但增加的 Build Number（从 15 到 16）重建应用程序。用户将看到相同的版本，但商店会理解构建是更新的。

这种灵活性允许开发人员在未通知用户版本更改的情况下发布修复。

Marketing Version 的显示位置

Marketing Version 在用户与应用程序交互的几个关键点显示。在应用商店中，它显示在应用程序卡片、更新说明和版本历史中。

在设备上，Marketing Version 显示在系统设置中（“关于应用”或“应用”部分），通过 App Store 或 Google Play 的更新对话框中，以及应用程序内部的“关于”屏幕上。

清晰的 Marketing Version 帮助用户评估已安装版本的新旧程度并决定是否更新。

iOS 上的 Marketing Version

在 iOS 中，Marketing Version 通过 Xcode 中目标设置 General 选项卡的 “Marketing Version” 字段设置。值存储在 Info.plist 中作为 CFBundleShortVersionString。

版本格式受 Apple 严格规定：字符串必须包含一到三个以点分隔的数字（例如，1、1.2 或 1.2.3）。最大长度 — 18 个字符。每个数字不超过 255。

根据 Apple App Store Review Guidelines (2025)，如果 Marketing Version 与先前发布的版本相差超过一个主版本或次版本值，App Store Connect 不允许上传构建 — 这可以保护用户免受遗漏更新的影响。

使用 agvtool 从命令行管理 Marketing Version — 这简化了与 CI/CD 系统的集成，并保证了与 Build Number 的同步。

Android 上的 Marketing Version

在 Android 中，Marketing Version 通过 build.gradle 文件中的 versionName 参数设置。与 iOS 不同，Android 对版本字符串格式没有严格限制。

versionName 可以包含任何字符：字母、数字、连字符和点。Google Play 在应用程序卡片和更新列表中显示此字符串，但不会检查其是否符合任何模板。

然而，Google Play 建议遵循语义格式 Major.Minor.Patch 以保持一致性。这简化了用户对版本的理解，并允许自动分析更新。

指定明确反映发布类型的 versionName — 主版本更新、次版本或补丁。这有助于用户快速评估更改的重要性。

versionName 的动态生成

versionName 在 Android 中可以基于 Git 标签或 CI/CD 变量动态生成。这简化了版本化过程，并消除了存储库与构建之间的差异。

典型方法 — 读取 Git 标签（例如 v2.1.0）并将其值用作 versionName。如果标签不存在，可以基于日期和提交号生成版本。

这种方法保证了 versionName 始终与源代码状态对应，无需手动更新。

Marketing Version 与 Build Number 的区别

Marketing Version 和 Build Number — 是两个独立的参数，解决不同的任务。Marketing Version 通知用户，Build Number 从技术上标识构建。

关键区别 — 唯一性。Build Number 对于每个构建必须是唯一的。Marketing Version 可以重复：同一版本的多个构建具有相同的 Marketing Version 但不同的 Build Number。

根据 Google Play Policy (2025)，如果上传两个具有相同 Marketing Version 但不同 Build Number 的 APK，Google Play 将接受它们作为同一版本的不同构建。对于 App Store 也适用类似规则。

请记住：Build Number — 为机器服务，Marketing Version — 为人服务。自动化前者，仔细规划后者。

版本化策略

选择策略取决于应用程序类型、受众和发布过程。三种主要方案 — 语义、日历和混合 — 覆盖大多数场景。

语义版本 (SemVer) 使用 Major.Minor.Patch 格式，并严格确定何时增加哪个组件。对于具有公共 API 和复杂集成的应用程序来说是理想选择。

根据 semver.org (2023)，SemVer 规范的 2.0.0 版本在 89% 的开源移动项目中使用，并得到所有包管理器的支持。

日历版本化

日历版本化 (CalVer) 使用发布日期作为版本 — 例如，25.06 代表 2025 年 6 月。这种方法在频繁更新的应用程序中很流行。

CalVer 不携带关于更改重要性的信息，但很好地显示了版本的新旧程度。用户立即理解版本 25.06 比 25.03 更新。

如果您的应用程序频繁更新，并且用户更看重数据的新鲜度而不是更改的数量，请选择日历版本化。

选择建议

对于 MVP 和初创公司，适用于不带补丁的简单语义版本 (Major.Minor)。对于具有长期支持的成熟产品 — 完整 SemVer。对于持续发布的应用程序 — CalVer。

切勿使用日期作为 Build Number — 这可能在每天多个构建时导致冲突。Build Number 应该是顺序或复合的，但始终单调递增。

选择 Marketing Version 时的错误

典型错误 — 在过渡到新的主版本线时跳过版本组件。例如，在版本 1.9.9 之后，下一个应该是 2.0.0，而不是 1.10.0。这违反了语义并让用户困惑。

另一个常见问题 — 代码中与应用商店中的 Marketing Version 不一致。在提交构建审核之前，始终检查 build.gradle 中的 versionName 是否与 Google Play Console 或 App Store Connect 中指定的版本匹配。

Marketing Version 配置示例

代码示例展示了如何在两个平台上设置 Marketing Version 并自动化其更新。

在 Android Gradle 中设置 versionName

在 Android 中，versionName 在 build.gradle 中设置。值可以是静态的，也可以从环境变量中读取。

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

// 从 Git 标签读取版本
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName 从 Git 标签中提取，保证了存储库中的版本与编译后的应用程序之间的对应关系。

在 Xcode 中管理 Marketing Version

在 iOS 中，Marketing Version 通过 Xcode 或 agvtool 设置。下面的命令设置一个新的营销版本。

# 设置 Marketing Version
xcrun agvtool new-marketing-version 2.1.0

# 自动增加
xcrun agvtool next-marketing-version

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

适用于两个平台的 Fastlane

Fastlane 允许从一个脚本管理两个平台上的 Marketing Version，从而简化跨平台项目的支持。

# 设置营销版本
increment_version_number(
    version_number: "2.1.0"
)

# 自动增加次版本
increment_version_number(
    bump_type: "minor"
)

Fastlane 在两个平台上都能运行，并受到大多数 CI/CD 服务的支持。