---
source: ../../../core/versioning.md
source_version: 1.2.0
translation_version: 1.2.0
last_synced: 2026-01-08
status: current
---

> **语言**: [English](../../../core/versioning.md) | [简体中文](../../zh-TW/core/versioning.md) | 简体中文

# 语义化版本标准

**版本**: 1.0.0
**最后更新**: 2025-12-30
**适用范围**: 所有有版本发布的软件项目

---

## 目的

本标准定义如何使用语义化版本 (SemVer) 为软件发布编号，以清楚地向用户和维护者传达变更。

---

## 语义化版本格式

```
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

示例:
2.3.1
1.0.0-alpha.1
3.2.0-beta.2+20250112
```

### 组成说明

| 组成 | 用途 | 递增时机 |
|------|------|---------|
| **MAJOR** | 破坏性变更 | 不兼容的 API 变更 |
| **MINOR** | 新功能 | 向后兼容的功能 |
| **PATCH** | 错误修复 | 向后兼容的修复 |
| **PRERELEASE** | 预发布标识 | Alpha、Beta、RC 版本 |
| **BUILD** | 构建元数据 | 构建号、提交哈希 |

---

## 递增规则

### MAJOR 版本 (X.0.0)

**递增时机**:
- 破坏性 API 变更
- 移除已弃用功能
- 重大架构变更
- 不兼容的行为变更

### MINOR 版本 (x.Y.0)

**递增时机**:
- 添加新功能（向后兼容）
- 弃用功能（非移除）
- 实质性内部改进
- 新的公开 API

### PATCH 版本 (x.y.Z)

**递增时机**:
- 错误修复（无新功能）
- 安全补丁
- 文档更正
- 内部重构（无 API 变更）

---

## API 版本化策略

| 策略 | 格式 | 优点 | 缺点 |
|------|------|------|------|
| URL 路径 | `/api/v1/users` | 清晰、易于路由 | URL 污染 |
| 查询参数 | `/api/users?version=1` | 可选版本 | 缓存问题 |
| 标头 | `Accept: application/vnd.api.v1+json` | URL 干净 | 不可见 |

**推荐**: 大多数 API 使用 URL 路径版本化。

---

## 弃用时间线

```
v1.0.0 - 功能引入
v1.5.0 - 添加弃用警告（至少 N-1 版本）
v2.0.0 - 移除功能（记录在迁移指南中）
```

### 弃用期限指南

| API 类型 | 最短弃用期限 |
|----------|-------------|
| 内部 API | 1 个次要版本 |
| 合作伙伴 API | 2 个次要版本 + 3 个月 |
| 公开 API | 2 个次要版本 + 6 个月 |
| 关键基础设施 | 最少 1 年 |

---

## 向后兼容性检查清单

**不要破坏（不升级主版本号）**:
- [ ] 移除公开 API 端点
- [ ] 移除必填请求字段
- [ ] 添加必填请求字段
- [ ] 更改响应字段类型
- [ ] 更改错误码含义

**安全变更（次要/补丁版本）**:
- [ ] 添加可选请求字段
- [ ] 添加新响应字段
- [ ] 添加新端点
- [ ] 添加新错误码
- [ ] 改进错误消息

---

## 预发布版本

### 预发布标识符

| 标识符 | 用途 | 稳定性 | 受众 |
|-------|------|-------|-----|
| alpha | 早期测试 | 不稳定 | 内部团队 |
| beta | 功能完成 | 基本稳定 | 早期采用者 |
| rc | 最终测试 | 稳定 | Beta 测试者 |

### 示例

```
1.0.0-alpha.1       # 第一个 alpha 版本
1.0.0-beta.1        # 第一个 beta 版本
1.0.0-rc.1          # 候选版本 1
1.0.0               # 稳定版本
```

---

## 快速参考卡

### 版本递增

| 做了什么？ | 递增 |
|-----------|-----|
| 破坏性变更 | MAJOR |
| 新功能 | MINOR |
| 错误修复 | PATCH |

### 版本格式

```
MAJOR.MINOR.PATCH
  │     │     └── 错误修复
  │     └──────── 新功能
  └────────────── 破坏性变更
```

---

## 相关标准

- [变更日志标准](changelog-standards.md)
- [Git 工作流程](git-workflow.md)
- [提交消息指南](commit-message-guide.md)

---

## 许可证

本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。
