版本命名规范示例的核心，是把版本号拆成“主版本.次版本.修订号”三段，再用可选后缀标记预发布与构建信息，例如 2.4.0-rc.1+build.20261019。主版本表示不兼容变更，次版本表示向后兼容的新增能力，修订号表示向后兼容的缺陷修复；预发布后缀按 alpha→beta→rc 顺序递进，构建号只用于追溯、不参与比较。下面以一款按迭代节奏持续发布的软件产品为演示情景，给出一套可直接套用的规则、六个已填版本号和配套版本记录表。
要点总览（TL;DR）
- 版本号采用“主版本.次版本.修订号”三段结构，可选后缀标记预发布与构建信息，例如 2.4.0-rc.1+build.20261019。
- 主版本对应不兼容变更，次版本对应向后兼容的新增能力，修订号对应向后兼容的缺陷修复；升级后需要使用方改动才能正常工作，就升主版本。
- 预发布标识按 alpha→beta→rc 递进，rc 阶段功能冻结、只修阻断发布的问题；构建元数据只用于追溯，不参与版本比较。
- 热修复可递增修订号（如 2.0.1），也可增加第四位（如 2.0.0.1）与常规修订区分，按团队是否需要版本号层面区分来选择。
- 规范落地要配套版本记录表，写清版本号、变更类型、发布范围、冻结时间和回滚点，并把版本号与分支、标签、发布记录保持同一字符串。
示例要解决什么：版本号要能被读懂和比较
版本号在发布管理中同时承担三项职责：说明这次改了什么、标明发布的先后顺序、留下可追溯的构建线索。三项职责对应三个问题——变更的性质是什么，两个版本谁更新，某个版本对应哪一次构建。如果版本号只体现其中一项，比如只递增数字而不区分变更性质，读者就需要翻发布说明才能判断升级风险；如果只写日期，又无法表达兼容性变化。
本示例的假设前提如下，均为演示情景，非真实客户案例：
- 产品形态：一款持续迭代的软件产品，有明确的对外发布节奏。
- 发布节奏：按迭代发布，每个迭代可能包含功能新增、缺陷修复或不兼容调整。
- 维护方式：已发布版本需要保留维护分支，支持缺陷修复与热修复。
- 追溯要求：每个对外版本都能对应到一次具体构建，便于排查问题。
在这些前提下，版本号需要做到：一眼看出变更级别，按字符串或语义规则正确排序，并能通过构建元数据回溯到发布制品。示例围绕这三点展开，不涉及产品功能版本规划和制品本体的存储分发。
完整示例：一套版本命名规则与六个已填版本号
先给出命名规则表，再给出六个覆盖典型场景的版本号，最后用版本记录表把版本号与发布信息逐条对应。
命名规则表
| 组成部分 | 写法 | 含义 | 是否参与比较 |
|---|---|---|---|
| 主版本 | 非负整数 | 不兼容变更，升级后旧用法可能失效 | 是，优先级最高 |
| 次版本 | 非负整数 | 向后兼容的新增能力 | 是 |
| 修订号 | 非负整数 | 向后兼容的缺陷修复 | 是 |
| 预发布标识 | -alpha.N / -beta.N / -rc.N | 正式发布前的测试版本，按 alpha→beta→rc 递进 | 是，且低于同段正式版 |
| 构建元数据 | +build.YYYYMMDD 或 +build.序号 | 标识具体构建，用于追溯 | 否 |
完整格式为：主版本.次版本.修订号[-预发布标识][+构建元数据]。方括号内为可选项，按需启用。
版本号样例清单
| 序号 | 版本号 | 场景 | 变更说明 |
|---|---|---|---|
| 1 | 1.0.0 | 首发 | 首个正式对外版本，功能基线确立 |
| 2 | 1.1.0 | 功能新增 | 新增导出能力，兼容旧版本 |
| 3 | 1.1.1 | 缺陷修复 | 修复导出文件编码错误 |
| 4 | 2.0.0 | 不兼容变更 | 接口参数结构调整，旧调用方式失效 |
| 5 | 2.1.0-rc.1+build.20261019 | 预发布 | 2.1.0 的候选发布版本，进入验收 |
| 6 | 2.0.1 | 热修复 | 2.0.0 线上问题的紧急修复 |
配套版本记录表
| 版本号 | 变更类型 | 发布范围 | 冻结时间 | 回滚点 |
|---|---|---|---|---|
| 1.0.0 | 首发 | 全量用户 | 2026-03-02 | 无（首个版本） |
| 1.1.0 | 功能新增 | 全量用户 | 2026-05-11 | 1.0.0 |
| 1.1.1 | 缺陷修复 | 全量用户 | 2026-05-25 | 1.1.0 |
| 2.0.0 | 不兼容变更 | 全量用户，附迁移说明 | 2026-08-17 | 1.1.1 |
| 2.1.0-rc.1+build.20261019 | 预发布 | 内部验收与小范围试用 | 2026-10-19 | 2.0.1 |
| 2.0.1 | 热修复 | 全量用户 | 2026-10-12 | 2.0.0 |
记录表中的版本号与样例清单逐条对应，冻结时间表示该版本停止接受变更、进入发布准备的时间点，回滚点表示出问题时退回的上一稳定版本。表中日期为演示数据。
逐项解释：每个版本号为什么这样写
样例中的每个版本号都对应一次明确的判断，理解判断依据比记住数字更重要。
1.0.0 与 1.1.0：首发与功能新增
1.0.0 作为首个正式版本，主版本取 1 表示功能基线确立，次版本和修订号归零。1.1.0 新增导出能力且保持旧用法可用，属于向后兼容的新增，因此次版本递增、修订号归零。判断依据是：旧版本的调用方式和数据格式在新版本中仍然有效。
1.1.1：缺陷修复只动修订号
修复导出文件编码错误不改变对外能力，也不破坏兼容性，因此只递增修订号。修订号递增意味着“行为更正确，用法不变”，使用者可以放心升级。
2.0.0：不兼容变更触发主版本递增
接口参数结构调整后，旧的调用方式失效，使用者必须修改代码或配置才能升级。这类变更的代价落在使用方，必须在版本号上给出最强信号，因此主版本从 1 升到 2，次版本和修订号归零。判断标准可以归纳为一句：升级后是否需要使用方改动才能正常工作，若是，则升主版本。
2.1.0-rc.1+build.20261019：预发布与构建元数据
预发布标识按 alpha→beta→rc 递进，含义逐级收紧：alpha 阶段功能尚在开发、接口可能变动；beta 阶段功能基本完整、以找缺陷为主；rc（release candidate）阶段功能冻结、只修阻断发布的问题，通过验收即可转为正式版。2.1.0 已进入验收，因此用 rc.1 而非 beta。
构建元数据 +build.20261019 只标识这次构建的日期或序号，用于把版本号对应到具体制品。它不参与版本比较：2.1.0-rc.1+build.20261019 与 2.1.0-rc.1+build.20261020 在排序上视为同一预发布版本，区别只在构建批次。这样比较逻辑保持简单，追溯信息又不丢失。
2.0.1：热修复的两种写法
热修复常见两种写法。第一种是递增修订号，如 2.0.1，表示在 2.0.0 基础上做兼容性修复，适用于修复范围小、不引入新能力的情况。第二种是在修订号之外增加第四位，如 2.0.0.1，专门标记紧急补丁，便于与常规修订区分。本示例选择 2.0.1，理由是修复内容属于常规缺陷修复，且三段式版本号在排序和工具兼容上更通用；如果团队需要把热修复与常规修订在版本号层面区分开，再启用第四位。
版本记录表各字段的填写理由
- 版本号：与制品、标签、发布单保持同一字符串，避免对不上。
- 变更类型：记录判断结果，便于回溯“为什么升的是主版本”。
- 发布范围：区分全量、灰度、内部验收，决定通知和验证范围。
- 冻结时间：标记停止变更的时间点，是发布准备和回滚决策的基准。
- 回滚点：提前写明退回哪个版本，出问题时不需要临时讨论。
可迁移规律：换到自己的产品怎么改
示例中的三段式语义化版本可以作为通用骨架直接沿用，因为它把兼容性变化编码进了数字位置，读者无需额外文档就能判断升级风险。以下部分可按团队情况调整。
- 骨架直接沿用：主版本.次版本.修订号的三段结构，以及“不兼容升主、新增升次、修复升修订”的判断规则，适用于大多数持续迭代的软件产品。
- 后缀按需启用：预发布标识和构建元数据都是可选项。只有存在对外测试或需要追溯构建时才启用，不必追求齐全；启用后要固定写法，避免 -RC1、-rc-1、-rc.1 混用。
- 与分支、标签、发布记录对应：每个版本号应能对应到一条发布分支或标签，并在发布记录中留痕。版本号、标签名、制品名使用同一字符串，是减少发布事故的低成本做法。
- 书面化并纳入发布检查：把规则写成简短文档，在发布检查清单中加入“版本号是否符合规则”“记录表是否填写完整”两项，规范才会被执行。
调整时优先改后缀和记录字段，谨慎改动三段式的判断规则。判断规则一旦松动，版本号的可比较性就会下降，后续维护成本随之上升。
版本记录表落地到协作工具时，可以把每个版本作为一个发布工作项，版本号、变更类型、发布范围、冻结时间、回滚点作为字段维护，发布单关联对应的需求与缺陷。ONES 支持在工作项中自定义字段并关联发布记录，适合把上述表格转为可查询、可交接的记录；具体字段配置可按团队流程设定。
适用边界：这些情况需要另定规则
本示例适用于有明确迭代节奏、需要表达兼容性变化的软件产品。以下情形需要另定规则或补充约定。
- 面向终端用户的消费级产品：用户更关注功能卖点而非兼容性，可能需要更易读的营销版本号，如“2026 夏季版”，此时语义化版本可作为内部构建号并行使用。
- 多产品线并行：同一组织下有多条产品线时，版本号前需要加产品标识或使用独立命名空间，避免 2.0.0 指向不同产品造成混淆。
- 对外交付与内部构建口径不同：对外交付版本强调稳定与可追溯，内部构建可以更频繁地递增构建号；两套口径要明确对应关系，避免交付时拿错制品。
- 与相邻工作的分工：版本命名规范只解决“版本号怎么写、怎么记”，产品功能版本规划解决“每个版本做什么”，制品管理解决“制品怎么存、怎么发”。三者边界清晰，规范才不会承担超出职责的期待。
当团队规模、发布频率或交付对象发生明显变化时，建议重新审视一次规则，把新增场景补进示例和记录表，保持规范与实际情况一致。
常见问题
预发布版本什么时候用 alpha、beta、rc，能不能直接跳到 rc？
三种标识对应不同的质量状态：alpha 阶段功能尚在开发、接口可能变动；beta 阶段功能基本完整、以找缺陷为主；rc 阶段功能冻结、只修阻断发布的问题。是否跳过取决于风险：内部验证充分、变更范围小的版本可以直接进入 rc；面向外部用户、改动面大的版本建议保留 beta 阶段收集反馈。关键是同一产品内保持写法一致，避免 -RC1、-rc-1、-rc.1 混用导致排序混乱。
热修复用 2.0.1 还是 2.0.0.1，两种写法怎么选？
2.0.1 表示在 2.0.0 基础上做兼容性修复，三段式结构在排序和工具兼容上更通用；2.0.0.1 增加第四位，专门标记紧急补丁，便于在版本号层面与常规修订区分。选择依据是团队是否需要这种区分：如果发布记录表已经能标明变更类型，用 2.0.1 即可；如果热修复频繁、需要快速识别，再启用第四位，并在规范中固定下来。
构建元数据会不会影响版本排序，同一预发布版本多次构建怎么记？
构建元数据不参与版本比较，2.1.0-rc.1+build.20261019 与 2.1.0-rc.1+build.20261020 在排序上视为同一预发布版本，区别只在构建批次。多次构建时保持预发布标识不变，只更新构建号，并在版本记录表中记录每次构建对应的验收结果。这样比较逻辑保持简单，追溯信息又不丢失。
多产品线并行时，版本号需要加产品标识吗？
需要。同一组织下有多条产品线时，2.0.0 可能指向不同产品，造成沟通和制品取用混淆。常见做法是在版本号前加产品标识，或为每条产品线使用独立的命名空间与标签前缀。无论选哪种，都要保证版本号、标签名、制品名使用同一字符串，并在发布记录中写明所属产品线。
版本命名规范写好后，怎么保证团队持续执行？
把规则写成简短文档，并在发布检查清单中加入两项检查：版本号是否符合规则、版本记录表是否填写完整。同时让版本号与分支、标签、发布记录保持对应，发布单关联对应的需求与缺陷。规则执行一段时间后，结合新增场景回看一次，把遗漏的情形补进示例和记录表，规范才能与实际情况保持一致。
