软件版本标签规范设计

幂简官方

39 浏览

3 试用

0 购买

Dec 13, 2025更新

本提示词专门用于为各类软件项目设计科学合理的版本标签规范。通过分析项目类型、发布规模、变更性质等关键因素，提供符合行业标准的版本命名方案。能够帮助开发团队建立统一的版本管理标准，确保版本标识的清晰性和可追溯性，支持敏捷开发、持续集成等多种开发模式下的版本控制需求，提升软件发布管理的专业性和效率。

版本控制策略概述

采用语义化版本控制（SemVer 2.0.0），全部发布以 Git 注释标签（annotated tag）为准，统一使用前缀 v。
针对 Web 应用的“常规发布、功能增强”为主的节奏：功能增强默认触发次版本（MINOR）升级；不破坏兼容性。
单产品统一版本（前后端一起发版）。如后续拆为多服务，推荐每个服务独立遵循同一规范。
分支与发布流：
- main：持续集成下一轮功能。
- release/X.Y：从 main 切出发布分支，仅接受修复与发布所需改动；在该分支上迭代 RC。
- 热修分支 hotfix/X.Y.Z：从稳定标签切分，仅修复紧急问题。
- 标签策略：RC 贴在 release 分支；最终稳定版标签贴在合并回 main 的发布提交上。

版本号组成结构说明

统一格式：vMAJOR.MINOR.PATCH[-rc.N][+BUILD]
- MAJOR：不兼容变更
- MINOR：向后兼容的功能增强
- PATCH：向后兼容的问题修复
- -rc.N：发布候选（Release Candidate），N 为从 1 起递增的正整数
- +BUILD：构建元数据，不影响版本排序，建议仅用于制品命名与可追溯，不用于 Git 标签
推荐构建元数据格式（用于制品名、镜像标签等，不用于 Git tag）：
- +build.YYYYMMDDhhmm.sha.SSSSSSS（UTC 时间 + 短 SHA）
- 例：v1.4.0-rc.2+build.20251212T0830.sha.a1b2c3d

版本递增规则详解

MAJOR 递增（X+1.0.0）：
- 对外 API/协议不兼容；前端公共接口/URL 变更；必须停机或强制迁移的数据库模式更改；删除已公告弃用的能力。
MINOR 递增（x.Y+1.0）：
- 向后兼容的“功能增强/新增”；
- 新增 API/页面/能力；可选配置项；向后兼容的性能改进；标记“弃用但仍可用”。
PATCH 递增（x.y.Z+1）：
- 修复缺陷/安全补丁；向后兼容的小型优化；不改变外部行为的依赖更新。
与提交规范映射（可选但推荐）：
- feat → MINOR；feat! 或含 BREAKING CHANGE → MAJOR；fix → PATCH；perf/docs/chore/refactor（无行为变更）→ PATCH 或不发版（视影响）。

特殊场景处理方案

预发布（RC）流程
- 命名：vX.Y.0-rc.N（N 从 1 递增，修复一次加 1）
- 使用场景：发布分支上的候选版本，仅修复阻断问题与回归；禁止新增功能与架构性变更。
- 结束条件：RC 验证通过后打稳定标签 vX.Y.0，并发布到生产。
- 若 RC 阶段出现不兼容改动需求：终止当前 release 分支，重新规划版本号（可能升级为 MAJOR）。
构建元数据
- 不写入 Git 标签，避免同一版本多个不同构建的混淆。
- 用于制品与镜像名：app:v1.4.0-rc.2-build.20251212T0830.sha.a1b2c3d（仅供部署/回滚定位）。
热修流程
- 生产出现紧急问题：从稳定标签 vX.Y.Z 切出 hotfix，修复后发布 vX.Y.(Z+1)；
- 若并行存在下一次 MINOR 的 RC，不相互影响，按分支独立推进。
回滚策略
- 回滚到既有稳定标签（如 v1.4.0），禁止创造“v1.4.0a”等变体；
- 如需修正，按 PATCH 递增发 v1.4.1。
数据库与前端缓存
- 数据库迁移：MINOR 仅允许向后兼容（双写/可回退）；要求停机或破坏兼容时升级 MAJOR。
- 前端资源缓存：确保产物指纹化，不影响版本号判断。
容器/镜像标签（非 Git 标签）
- 固定标签：1.4.0、1.4、1、latest（可选）。注意 1.4、1、latest 为“移动标签”，仅用于分发便利，不作为追溯依据。
- 推荐同时推送不可变标签：1.4.0-rc.2-build.20251212T0830.sha.a1b2c3d。

实施建议和注意事项

统一使用带 v 前缀的注释标签：v1.4.0、v1.4.0-rc.1
Git 标签命名校验（CI 正则）：
- ^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-rc\.(0|[1-9]\d*))?(\+[0-9A-Za-z.-]+)?$
版本唯一性与不可变性：同一标签严禁重打；严禁在 Git 标签中加入构建元数据。
自动化与变更日志
- 结合 Conventional Commits 与 Release Notes 自动生成；
- 在 RC→稳定发布间仅允许 fix、revert、docs、chore 类改动。
弃用策略
- 在 MINOR 版本引入 deprecate 提示，至少保留一个 MAJOR 周期后再移除。
权限与合规
- 只有发布经理/CI 机器人可打稳定与 RC 标签；标签保护与审计开启。
环境对齐
- 测试/预发环境部署 RC；生产仅部署稳定标签版本。

示例说明

功能增强常规发布（本次用户需求）
- 从 v1.3.5 提升到 v1.4.0：
  - 切分支：release/1.4
  - 候选版本：v1.4.0-rc.1 → 验证 → 修复 → v1.4.0-rc.2
  - 最终：v1.4.0（合并回 main 后打标签）
紧急修复
- 生产发现缺陷：从 v1.4.0 切 hotfix 分支 → 发布 v1.4.1
标签与制品命名
- Git 标签：v1.4.0-rc.2、v1.4.0、v1.4.1
- 构建产物文件：webapp-1.4.0-rc.2+build.20251212T0830.sha.a1b2c3d.zip
- 容器镜像：app:1.4.0、app:1.4.0-rc.2-build.20251212T0830.sha.a1b2c3d、app:1.4

该方案遵循语义化版本控制，确保发布标签清晰、可追溯、可自动化，兼顾 RC 流程与日常功能增强发布的高频需求。

版本控制策略概述

采用语义化版本控制（SemVer 2.0.0）作为统一标准：MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
面向“移动应用 + 紧急缺陷修复 + 需要测试版本”的场景：
- 生产发布：仅递增 PATCH，生成稳定版本标签 vX.Y.Z
- 预发布测试：在即将发布的 PATCH 版本上使用 -rc.N（release candidate）标识测试版本
同时满足移动平台生态差异：
- Git 仓库统一使用带前缀的标签 vX.Y.Z[-rc.N][+BUILD]
- iOS：CFBundleShortVersionString = X.Y.Z[-rc.N]；CFBundleVersion = 递增的构建号
- Android：versionName = X.Y.Z[-rc.N]；versionCode = 单调递增整数（含版本位与构建位）
发布分支与热修流程（简单、可落地）：
- 从上一次稳定发布标签打出 hotfix/X.Y.Z 分支
- 在 hotfix 分支上生成 -rc.N 预发布测试包
- 测试通过后打最终稳定标签 vX.Y.Z，合入主干与相关发布分支

版本号组成结构说明

基本结构：MAJOR.MINOR.PATCH
- MAJOR：不兼容变更（紧急修复场景不涉及）
- MINOR：向后兼容的新功能（紧急修复场景不涉及）
- PATCH：向后兼容的缺陷修复（本次场景使用）
预发布标识（PRERELEASE）：-rc.N
- rc = release-candidate；N 从 0 递增（0, 1, 2, …）
- 用于测试阶段，仅在候选发布周期使用
构建元数据（BUILD）：+
.
.
- 例：+android.20401071.a1b2c3 或 +ios.20401071.a1b2c3
- 只用于可追溯，不影响排序与兼容性判断
标签与应用版本对应
- Git Tag：vMAJOR.MINOR.PATCH[-rc.N][+BUILD]
- iOS：
  - CFBundleShortVersionString = MAJOR.MINOR.PATCH[-rc.N]
  - CFBundleVersion = BUILD_SEQ（仅递增数字）
- Android：
  - versionName = MAJOR.MINOR.PATCH[-rc.N]
  - versionCode = MAJOR10000000 + MINOR100000 + PATCH*1000 + BUILD_SEQ（0–999）

建议的标签校验正则（机器可读）：^v(0|[1-9]\d*).(0|[1-9]\d*).(0|[1-9]\d*)(?:-(?:rc.(0|[1-9]\d*))){0,1}(?:+[0-9A-Za-z-]+(?:.[0-9A-Za-z-]+)*)?$

版本递增规则详解

紧急缺陷修复（本次场景）
- 若基线为 vX.Y.Z：目标稳定版本为 vX.Y.(Z+1)
- 预发布测试版本：vX.Y.(Z+1)-rc.0、vX.Y.(Z+1)-rc.1、…（按测试轮次递增 N）
- 每次重打包仅修改 BUILD 元数据与构建号（iOS/Android），不改变 rc.N，除非代码有变更或测试阶段切换
预发布到正式发布的切换
- vX.Y.(Z+1)-rc.N 测试通过后，打最终稳定标签 vX.Y.(Z+1)（去掉 -rc.N 与 +BUILD）
- iOS/Android 的构建号继续保持单调递增，可与稳定标签对应的新构建
再次紧急修复
- 在 vX.Y.(Z+1) 基础上继续递增 PATCH 到 vX.Y.(Z+2)
- 预发布仍采用 -rc.N 序列
仅因商店审核重传或合规变更（无代码差异）
- 不改变 SemVer（保持 vX.Y.Z 或 vX.Y.Z-rc.N）
- 仅增加 BUILD_SEQ（iOS CFBundleVersion/Android versionCode）和 BUILD 元数据中 buildId
并行维护旧版本线（如需）
- 为旧版本线维护独立 hotfix/X.Y.Z 分支与标签序列，遵循相同 PATCH 与 rc.N 规则

特殊场景处理方案

多平台唯一性与可追溯
- iOS 构建号与 Android versionCode 不共用，但都映射到 BUILD_SEQ，保证每个平台内部严格单调
- 通过 BUILD 元数据记录 platform/buildId/commit，确保快速定位构建来源
商店限制与通道
- iOS：生产上架必须为稳定版本（不可带 -rc），TestFlight 可分发 -rc 测试包
- Android：生产渠道必须为稳定版本；内部测试/封闭测试可分发 -rc
回滚与撤回
- 已对外发布的稳定标签不可删除或复用
- 回滚时以新补丁版本 vX.Y.(Z+1) 修复问题后再次发布（严禁复用旧版本号）
并行开发与热修穿插
- 热修基于最近生产稳定标签创建 hotfix 分支，避免将未完成功能带入
- 修复完成后双向合并：hotfix -> main 以及必要的 release 分支，确保版本线一致
安全修复与灰度
- 安全类或高风险修复仍走 -rc.N 测试，但可缩短测试轮次
- 灰度/分阶段放量通过商店分发策略控制，与版本号无强耦合

实施建议和注意事项

标签与分支规范
- Tag：vX.Y.Z、vX.Y.Z-rc.N（必要时 +BUILD）
- Branch：hotfix/X.Y.Z、release/X.Y
- 禁止使用 latest、stable、final 等模糊标签
自动化与校验
- CI 在创建构建时校验标签正则与“不可倒退”规则
- 自动计算 Android versionCode 与 iOS 构建号，确保每次构建单调递增
- 构建产物名中包含版本与简短 SHA，便于追溯
变更记录与触发
- 建议使用 Conventional Commits + 自动生成变更日志
- 对紧急修复仅允许 PATCH 类变更合入，防止引入不兼容风险
元数据最小化
- BUILD 元数据仅用于可追溯，避免过长或包含敏感信息（如内部服务器名）
版本可扩展性
- 若未来需要区分测试渠道，可在 rc 前增加一层通道标识（不建议在紧急修复中使用，保持简单）：-beta.N、-internal.N（二选一，团队统一即可）

示例说明

场景：当前线上稳定为 v2.4.0，需要紧急修复一个缺陷
目标版本线：v2.4.1

首个测试版本（候选）

Git Tag：v2.4.1-rc.0+android.20401001.a1b2c3
- 说明：rc.0 为第一轮候选；BUILD 元数据含平台、构建序号 20401001、commit a1b2c3
Android
- versionName：2.4.1-rc.0
- versionCode：210000000 + 4100000 + 1*1000 + 1 = 20401001
iOS
- CFBundleShortVersionString：2.4.1-rc.0
- CFBundleVersion：20401001

第二个测试版本（修复测试问题后）

Git Tag：v2.4.1-rc.1+ios.20401005.d4e5f6
Android
- versionName：2.4.1-rc.1
- versionCode：20401002（仅构建号递增）
iOS
- CFBundleShortVersionString：2.4.1-rc.1
- CFBundleVersion：20401005

最终发布版本

Git Tag：v2.4.1
Android
- versionName：2.4.1
- versionCode：20401010（新的构建号，保证单调递增）
iOS
- CFBundleShortVersionString：2.4.1
- CFBundleVersion：20401010

若商店审核被拒仅需重传（无代码改动）

Git Tag 仍为 v2.4.1（不变）
仅递增构建号与元数据：
- Android versionCode：20401011
- iOS CFBundleVersion：20401011
- 构建产物元数据示例：+android.20401011.d7e8f9

通过以上规范，既满足语义化版本控制的严谨性，又兼顾移动应用分发生态的实际约束；同时提供清晰的预发布测试标识、可追溯的构建元数据，以及简单易维护的递增规则。

版本控制策略概述
- 采用语义化版本控制（SemVer 2.0.0）：MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
- 面向开源库的重大版本发布，因“架构调整”预计存在破坏性变更，目标稳定版本为 2.0.0
- 标签统一使用 Git 注释标签、带 v 前缀：vMAJOR.MINOR.PATCH…（v 仅作为标签前缀，版本字符串仍符合 SemVer）
- 引入预发布阶段：snapshot → alpha → beta → rc → 正式版
- 为保证可比性与排序正确性，预发布标识采用“阶段序号.阶段名.序号”的稳定模式（示例：-0.snapshot.5、-1.alpha.1、-2.beta.1、-3.rc.1）
- 快照版本（snapshot）面向频繁集成与验证，自动化生成，默认不可视为稳定发布、不进入长期保留仓库
- 分支与发布：
  - main：下一主线开发（2.x）
  - release/2.x：候选与稳定发布维护
  - 支持上一主版本的长期维护分支（如 release/1.x）以便必要时回补安全修复
版本号组成结构说明
- 基本结构：MAJOR.MINOR.PATCH
- 预发布（可选）：-
  .
  .
  [.][.]
  
  stageIndex：数值，用于严格排序，约定为 0=snapshot, 1=alpha, 2=beta, 3=rc
  
  stageName：snapshot | alpha | beta | rc
  
  iteration：从 1 起的阶段内递增编号
  
  yyyymmddHHMM（可选）：UTC 时间戳，便于追溯
  
  sanitizedBranch（可选）：仅用于 snapshot；将分支名中非 [0-9A-Za-z-] 字符替换为 -（确保 SemVer 合规）
- 构建元数据（可选）：+sha.
  [.ci.
  ]
  - 比较时忽略，仅用于追溯构建来源（推荐保留短 SHA 与 CI 运行号）
- 示例结构
  - v2.0.0-0.snapshot.27.20250115T1423.main+sha.ab12cd3
  - v2.0.0-1.alpha.1+sha.ab12cd3
  - v2.0.0-3.rc.2+sha.bf45e01
  - v2.0.0
- 机器可读正则（匹配去掉前缀 v 的 SemVer 核心形态）：
```
^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$
```
版本递增规则详解
- MAJOR（X.y.z）：任何破坏性变更（公共 API 变更、默认行为改变、框架/架构调整引发的不兼容），如 1.9.5 → 2.0.0
- MINOR（x.Y.z）：向后兼容的新功能（新增 API、可选能力、性能增强且不破坏现有契约），如 2.0.0 → 2.1.0
- PATCH（x.y.Z）：向后兼容的问题修复（Bugfix、安全修复、内部优化不影响外部契约），如 2.0.0 → 2.0.1
- 推荐与提交信息约定配合（如 Conventional Commits）：
  - feat!: MAJOR
  - feat: MINOR
  - fix/chore/docs/refactor/test/perf 等（不破坏接口）: PATCH
  - 任何破坏性变更必须显式标注（如 BREAKING CHANGE）
- 预发布阶段递进规则
  - snapshot：-0.snapshot.N，N 为流水号（CI 自动递增或基于时间戳）
  - alpha/beta：在达成阶段质量门槛后，切换为 -1.alpha.1/-2.beta.1，并按发现问题递增 iteration
  - rc：功能冻结，仅修关键缺陷，-3.rc.1 起，若修复再发 -3.rc.2…
  - 正式版：移除预发布段与元数据，发布 v2.0.0
特殊场景处理方案
- 快照版本（SNAPSHOT）
  - 命名：v2.0.0-0.snapshot.[.][.]+sha.
  - 产出：CI 自动构建；默认不在长期仓库保留或标记为 pre-release（避免被误用为稳定依赖）
  - 适配包管理器：发布到专用快照通道/仓库（如私有/预发布 registry），避免污染稳定索引
- 候选与撤回
  - 若发现预发布严重问题：发布更高 iteration 的预发布版本（不可修改已有标签）
  - 已发布稳定版如需撤回，保持标签不可变，选择“yank/withdraw”能力（若仓库支持），并发布修复版（如 2.0.1）
- 热修复与回补
  - 最新稳定版问题：在 release/2.x 打补丁，发布 2.0.1、2.0.2…
  - 上一主版本 LTS：在 release/1.x 进行必要安全修复，如 1.9.6
- 构建可追溯性
  - 一律加 +sha.[.ci.] 元数据
  - 需生成 SBOM/产物签名时，可在 CI 附加工件但不改变版本号
- 多模块/多包发布
  - 同步对齐版本（推荐统一主版本），确保依赖关系明确；如果子模块可独立发版，严格遵守各自 SemVer 并在发布说明中标注兼容矩阵
- 分支命名清洗
  - sanitizedBranch = branch.toLowerCase().replace(/[^0-9A-Za-z-]/g, '-')
  - 避免出现斜杠、下划线等导致 SemVer 非法的字符
实施建议和注意事项
- 标签与不可变性
  - 使用签名的注释标签：git tag -s v2.0.0 -m "Release 2.0.0"
  - 所有标签一经发布不可重写；禁止同名重发
- CI/CD 集成
  - 仅当打标签时生成正式发布产物；预发布标签触发预发布流水线
  - 快照：按分支与提交自动编号；正式版：仅从 release/2.x 分支创建
  - 在构建时将版本号写入包元数据/二进制信息，严格与标签一致
- 发布门槛
  - 进入 rc 前：完成 API 审核、迁移指南、基准测试与兼容性验证
  - 正式版：无 P0/P1 缺陷，文档与变更日志齐全
- 兼容性与弃用
  - 对计划删除的 API 先在 2.y.z 中标记 deprecated 并提供替代；在下一个 MAJOR 再删除
  - 变更日志明确列出 BREAKING CHANGES 与迁移步骤
- 规范校验
  - 在 CI 加入版本字符串正则校验与阶段有序性校验（0 → 1 → 2 → 3 → release）
- 简化选项（如需）
  - 若团队认为阶段序号过于“显式”，可仅在 snapshot 使用 0.snapshot，其余沿用 alpha/beta/rc；但需接受少量消费者在排序上可能与预期不同的风险
示例说明
- 从 1.x 迈向 2.0.0 的完整路径
  - 每日快照：
    - v2.0.0-0.snapshot.27.20250115T1423.main+sha.ab12cd3
  - 开启 Alpha 轮：
    - v2.0.0-1.alpha.1+sha.0f1c2d3
    - v2.0.0-1.alpha.2+sha.1a2b3c4
  - 进入 Beta：
    - v2.0.0-2.beta.1+sha.55aa77b
  - 候选发布：
    - v2.0.0-3.rc.1+sha.88dd112
    - v2.0.0-3.rc.2+sha.99ee223
  - 正式发布：
    - v2.0.0
- 后续修订与特性
  - 紧急修复：v2.0.1
  - 新功能（兼容）：v2.1.0
- 快照（特性分支）
  - v2.0.0-0.snapshot.41.20250120T0910.feature-async-io+sha.cafe123
- 非法/不推荐示例（避免）
  - v2.0.0-snap（预发布标识不规范，且排序不可控）
  - 2.0（缺少补丁号）
  - 重用已存在的 v2.0.0 标签（不可变性原则）

本方案在保证简洁度的同时，通过“阶段序号 + 阶段名”的预发布模式，确保快照、Alpha、Beta、RC 的比较与排序完全符合语义化版本原则，并满足开源库重大版本发布与快照迭代的需求。

解决的问题

帮助产品与研发团队在数分钟内建立一套可落地、可扩展、可复用的软件版本标签规范。基于项目类型、发布节奏、变更强度与预发布需求，自动生成清晰易懂的版本命名方案与递增规则，覆盖正式版、预发布版与构建标识等关键环节。让多团队、多仓库、多环境的版本标识统一可追溯，减少沟通成本与发布风险，支撑敏捷与持续交付的高频迭代。即刻获得“拿来就能用”的版本规范文档与示例，提升发布效率与专业度，助力规范落地与团队协作升级。

适用用户

研发负责人／技术总监

快速落地统一的版本命名与递增规则，明确何时升主版或小版，建立预发布与热修复策略，减少跨团队沟通成本，让新成员在短时间内掌握发版标准。

DevOps／发布经理

将版本规则融入发布流程校验，自动生成标签模板与示例，规范灰度、回滚、紧急修补命名，沉淀可复用的发版手册，显著降低发版出错率。

开源项目维护者

为贡献者提供一致的版本说明与提交流程，明确破坏性变更的升级条件，生成可读的版本示例与说明，让社区用户更易理解与追踪版本演进。

特征总结

• 一键生成符合行业规范的版本命名方案，确保各类项目发布命名统一清晰

• 基于项目类型与发布节奏自动给出递增规则，避免人工判断失误与争议

• 内置预发布与热修复标识策略，支持灰度、内测、紧急修补等多场景

• 提供变更影响分级与版本选择建议，降低上线风险并提升协同效率

• 输出可直接落地的团队规范与示例，缩短对齐成本，加速新成员上手

• 可按业务线与环境自定义标签格式，兼顾灵活扩展与长期可追溯

• 适配持续集成与发布流程，标签规则可被流程轻松调用与校验

• 提供版本历史整理与命名体检建议，及时发现混乱点并统一口径

• 支持多产品多仓库统一策略，避免跨团队版本冲突与客户沟通混乱

如何使用购买的提示词模板

1. 直接在外部 Chat 应用中使用

将模板生成的提示词复制粘贴到您常用的 Chat 应用（如 ChatGPT、Claude 等），即可直接对话使用，无需额外开发。适合个人快速体验和轻量使用场景。

2. 发布为 API 接口调用

把提示词模板转化为 API，您的程序可任意修改模板参数，通过接口直接调用，轻松实现自动化与批量处理。适合开发者集成与业务系统嵌入。

3. 在 MCP Client 中配置使用

在 MCP client 中配置对应的 server 地址，让您的 AI 应用自动调用提示词模板。适合高级用户和团队协作，让提示词在不同 AI 工具间无缝衔接。

AI 提示词价格

￥20.00元

先用后买，用好了再付款，超安全！

在线免费用提示词

您购买后可以获得什么

✓

获得完整提示词模板

- 共 558 tokens

- 4 个可调节参数

{ 项目类型 } { 发布规模 } { 变更性质 } { 预发布需求 }

✓

获得社区贡献内容的使用权

- 精选社区优质案例，助您快速上手提示词

购买

软件版本标签规范设计

版本控制策略概述

版本号组成结构说明

版本递增规则详解

特殊场景处理方案

实施建议和注意事项

示例说明

版本控制策略概述

版本号组成结构说明

版本递增规则详解

特殊场景处理方案

实施建议和注意事项

示例说明

解决的问题