App版本号命名规范

修订记录

版本号	日期	描述
1.0.0	2025-06-19	初始发布

版本号命名规范

1. 语义化版本号（Semantic Versioning）

格式: 主版本.次版本.修订版本 (例: 2.1.3)

主版本 (Major): 重大功能更新、架构变更、不兼容的API变更（Breaking Changes）
次版本 (Minor): 新功能添加、向后兼容的功能性更新（Backward Compatible）
修订版本 (Patch): 向后兼容的Bug修复、安全补丁、性能优化等（Backward-compatible bug fixes and non-functional improvements）

2. 预发布版本标识

格式: 主版本.次版本.修订版本-标识.序号 (例: 2.1.0-alpha.1)

说明: 预发布版本号由一个连字符和一系列点号分隔的标识符构成。标识符必须仅包含ASCII字母数字和连字符 [0-9A-Za-z-]。此外，还可以附加构建元数据，通过在预发布版本之后追加一个加号和一系列点号分隔的标识符来表示 (例: 2.1.0-alpha.1+build.123)。构建元数据在版本比较时通常被忽略。

2.1.0-alpha.1 - 内部测试版本（Internal Testing）
2.1.0-beta.2 - 公开测试版本（Public Beta）
2.1.0-rc.1 - 发布候选版本（Release Candidate）

注意：预发布标识符应使用点号(.)分隔序号，符合SemVer 2.0规范

内部构建号规范

Android Version Code 规则

计算公式:

// 确保版本号在整数范围内且保持唯一性
// buildSequence 代表当天的构建次序或一个全局递增的构建序号
val versionCode = major * 1000000 + minor * 10000 + patch * 100 + buildSequence

示例:

2.1.3 第5次构建 → 2010305
3.0.0 第1次构建 → 3000001

优势:

严格递增，满足Google Play要求
版本信息可逆向解析
预留足够的版本空间

iOS Build Number 规则

计算公式:

// 确保构建号在整数范围内且保持唯一性
// buildSequence 代表当天的构建次序或一个全局递增的构建序号
let buildNumber = major * 1000000 + minor * 10000 + patch * 100 + buildSequence

示例:

2.1.3 第5次构建 → 2010305
8.47.1 第一次构建 → 8470101
3.0.0 第1次构建 → 3000001

优势:

严格递增，满足AppStore Testflight要求
版本信息可逆向解析
预留足够的版本空间

便于版本追踪和问题定位。

完整版本规范文档

1. 版本发布策略

发布分支策略

main - 生产环境代码
develop - 开发环境代码
release/x.y.z - 发布准备分支
hotfix/x.y.z - 紧急修复分支

版本号递增规则

变更类型	主版本	次版本	修订版本	示例
重大更新	+1	0	0	1.0.0 → 2.0.0
新功能	0	+1	0	1.0.0 → 1.1.0
Bug修复	0	0	+1	1.0.0 → 1.0.1
紧急修复	0	0	+1	1.0.0 → 1.0.1

2. 平台特定规范

Android 特殊要求

versionCode 必须严格递增，是Google Play商店的强制要求
支持APK分包（App Bundle）时的版本码管理
考虑Google Play的64位要求和应用签名方案v2/v3
在build.gradle中正确配置versionCode和versionName

iOS 特殊要求

CFBundleShortVersionString (Marketing Version) - 用户可见版本，遵循语义化版本规范
CFBundleVersion (Build Number) - 构建号，每次提交App Store Connect必须唯一且递增
支持TestFlight的版本管理和内部/外部测试轨道
在Xcode项目的Info.plist或项目设置中正确配置版本信息

3. 自动化版本管理

CI/CD 集成

# 版本号自动生成流程 (GitHub Actions示例)
name: Auto Version Bump

on:
  pull_request:
    types: [closed]
    branches: [main, develop]

jobs:
  version-bump:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Determine Version Bump Type
        id: bump-type
        run: |
          # 从PR标题或提交信息分析变更类型
          if echo "$PR_TITLE" | grep -q "BREAKING CHANGE"; then
            echo "::set-output name=type::major"
          elif echo "$PR_TITLE" | grep -q "feat:"; then
            echo "::set-output name=type::minor"
          else
            echo "::set-output name=type::patch"
          fi
        env:
          PR_TITLE: ${{ github.event.pull_request.title }}
      
      - name: Bump Version and Push Tag
        uses: mathieudutour/[email protected]
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          default_bump: ${{ steps.bump-type.outputs.type }}
          tag_prefix: 'v'

版本配置文件

此配置文件（例如 version.json 或集成到 package.json）应作为版本信息的“单一事实来源”(Single Source of Truth)。

{
  "version": {
    "name": "2.1.3", // 完整的语义化版本号
    "major": 2,
    "minor": 1,
    "patch": 3,
    "preRelease": null, // 例如 "alpha.1", "beta.2"
    "buildMetadata": null // 例如 "build.123"
  },
  "build": {
    "android": {
      "versionCode": 2010305,
      "versionName": "2.1.3"
    },
    "ios": {
      "buildNumber": "2010305",
      "marketingVersion": "2.1.3"
    },
    "timestamp": "2024-12-15T14:30:00Z",
    "commitHash": "a1b2c3d4e5f6g7h8i9j0"
  },
  "release": {
    "type": "stable",
    "channel": "production",
    "notesUrl": "https://releases.example.com/v2.1.3/notes",
    "isForcedUpdate": false, // 是否强制用户更新到此版本
    "minCompatibleVersion": "2.0.0" // 支持此版本的最低客户端版本
  }
}

提示：考虑使用如 commitizen、standard-version (JavaScript生态) 或 fastlane (移动端) 等工具来辅助自动化版本管理和变更日志生成。

4. 版本追踪和监控

版本数据库

记录所有发布版本的详细信息（版本号、构建号、发布日期、变更日志）
跟踪版本的生命周期状态（开发中、测试中、已发布、已弃用、已强制更新）
监控版本的用户采用率和关键性能指标（KPI）
集成崩溃报告和用户反馈系统，关联到特定版本

版本兼容性矩阵

API兼容性: 详细记录每个版本对外暴露API的变更，明确向前兼容性 (Newer client with older server) 和向后兼容性 (Older client with newer server)。
数据结构/数据库迁移: 跟踪数据库Schema变更，确保迁移脚本的正确性和覆盖所有升级路径 (例如使用Room/CoreData的迁移辅助类)。
第三方依赖: 列出核心第三方库及其版本，定期审查安全漏洞 (如使用OWASP Dependency-Check) 和兼容性问题。
操作系统支持: 明确应用支持的最低和推荐操作系统版本 (例如 Android API Level 21+ / iOS 13+)。
功能兼容性: 对于逐步推出的功能（Feature Flags），记录哪些版本包含哪些功能的不同阶段。

5. 团队协作规范

版本发布检查清单

版本号符合语义化规范且正确反映变更程度
构建号正确递增且平台特定配置已更新
发布说明完整且面向用户友好（用户价值导向）
自动化测试套件全部通过（单元测试、集成测试、UI测试）
安全扫描通过（OWASP依赖检查、代码安全分析）
性能基准测试通过（启动时间、内存占用、电池消耗）
无障碍功能合规性验证
数据隐私合规性检查
应用商店元数据和截图已更新

紧急发布流程

快速通道审批机制（关键利益相关者清单和责任矩阵）
简化的测试流程（关键路径测试和回归测试自动化）
自动回滚机制（版本降级策略和数据兼容性保障）
用户分组发布策略（金丝雀发布/灰度发布）
事后分析和预防措施文档化

实施建议

第一阶段：基础规范建立

制定版本号命名规范文档
建立版本配置管理系统
培训团队成员

第二阶段：自动化集成

开发版本管理工具
集成到CI/CD流程
建立监控和告警机制

第三阶段：优化和扩展

版本分析和优化
跨平台版本同步策略
版本回滚和灾难恢复

这套规范旨在提供一个全面且实用的App版本管理框架，确保版本管理的一致性、可追溯性和自动化程度，同时兼顾Android和iOS平台的特殊要求。通过严格遵循和持续优化这些最佳实践，开发团队能够显著提高发布质量，降低版本相关的风险，提升开发效率，并最终为用户提供更加稳定、可靠和透明的应用更新体验。