Go Modules 版本管理指南 #

语义化版本（SemVer） #

版本格式 #

Go Modules 严格遵循语义化版本规范（Semantic Versioning）：

text

vMAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

v1.2.3
v2.0.0-alpha.1
v1.0.0-beta+build.123

版本组成 #

组成部分	说明	示例
v	版本前缀（必需）	v
MAJOR	主版本号	1, 2, 3
MINOR	次版本号	0, 1, 2
PATCH	补丁版本号	0, 1, 2
PRERELEASE	预发布标识	alpha, beta, rc
BUILD	构建元数据	build.123

版本递增规则 #

text

MAJOR.MINOR.PATCH

MAJOR - 不兼容的 API 变更
  │
  ├── 删除或重命名导出的函数/类型
  ├── 修改函数签名
  ├── 修改接口定义
  └── 重大架构变更

MINOR - 向后兼容的功能新增
  │
  ├── 新增导出的函数/类型
  ├── 新增可选参数
  ├── 性能优化
  └── 功能增强

PATCH - 向后兼容的问题修复
  │
  ├── Bug 修复
  ├── 文档更新
  ├── 代码重构
  └── 小幅优化

版本示例 #

bash

# 正式版本
v1.0.0    # 首次正式发布
v1.0.1    # Bug 修复
v1.1.0    # 新增功能
v2.0.0    # 重大变更

# 预发布版本
v1.0.0-alpha.1    # 内部测试
v1.0.0-beta.1     # 公开测试
v1.0.0-rc.1       # 发布候选

# 带构建元数据
v1.0.0+build.123
v1.0.0-alpha.1+exp

预发布版本排序 #

text

预发布版本 < 正式版本

排序示例：
v1.0.0-alpha < v1.0.0-alpha.1 < v1.0.0-beta < v1.0.0-beta.2 < v1.0.0-rc.1 < v1.0.0

主版本与导入路径 #

导入路径规则 #

Go 2.0+ 规则：不同主版本必须有不同的导入路径

// v0.x 和 v1.x - 使用基础路径
import "github.com/myuser/mylib"

// v2.x 及以上 - 必须在路径中包含 /v2
import "github.com/myuser/mylib/v2"

// v3.x
import "github.com/myuser/mylib/v3"

模块定义 #

// v1.x - go.mod
module github.com/myuser/mylib

go 1.21

// v2.x - go.mod（注意 module 路径）
module github.com/myuser/mylib/v2

go 1.21

多版本共存 #

// 可以同时使用不同主版本
package main

import (
    "github.com/myuser/mylib"      // v1.x
    mylibv2 "github.com/myuser/mylib/v2"  // v2.x
)

func main() {
    mylib.DoSomething()           // v1.x API
    mylibv2.DoSomething()         // v2.x API
}

go.mod 示例 #

module myproject

go 1.21

require (
    github.com/myuser/mylib v1.2.3      // v1.x
    github.com/myuser/mylib/v2 v2.0.0   // v2.x
    github.com/myuser/mylib/v3 v3.1.0   // v3.x
)

伪版本（Pseudo-version） #

什么是伪版本 #

当模块没有打版本标签时，Go 会生成伪版本：

text

vX.0.0-yyyymmddhhmmss-abcdefabcdef
│  │   │            │
│  │   │            └── 12位 commit hash
│  │   └── 提交时间（UTC）
│  └── 补丁版本（通常是 0）
└── 基础版本

伪版本格式 #

bash

# 基础格式
vX.0.0-yyyymmddhhmmss-abcdefabcdef

# 有前置版本时
vX.Y.(Z+1)-pre.0.yyyymmddhhmmss-abcdefabcdef

# 示例
v1.0.0-20240101120000-abc123def456
v1.2.4-0.20240101120000-abc123def456

伪版本生成 #

bash

# 直接使用 commit hash
go get github.com/myuser/mylib@abc123def456

# go.mod 中显示
require github.com/myuser/mylib v1.0.0-20240101120000-abc123def456

伪版本 vs 正式版本 #

特性	伪版本	正式版本
格式	v1.0.0-20240101…	v1.0.0
来源	未打标签的 commit	Git 标签
可读性	较差	好
推荐度	开发阶段	生产环境

版本选择算法 #

最小版本选择（MVS） #

Go 使用最小版本选择算法：

text

原则：选择满足所有依赖要求的最低版本

示例：
├── A 需要 pkg v1.2.0
├── B 需要 pkg v1.3.0
└── C 需要 pkg v1.1.0

选择结果：pkg v1.3.0（满足所有要求的最小版本）

MVS 工作原理 #

text

依赖图：
myproject
├── github.com/A v1.0.0
│   └── github.com/common v1.2.0
├── github.com/B v1.0.0
│   └── github.com/common v1.3.0
└── github.com/C v1.0.0
    └── github.com/common v1.1.0

版本选择：
├── v1.1.0 ❌ 不满足 A 和 B
├── v1.2.0 ❌ 不满足 B
├── v1.3.0 ✅ 满足所有要求 ← 选择
└── v1.4.0 ✅ 满足但不是最小

与其他包管理器对比 #

包管理器	算法	说明
Go Modules	MVS	最小版本选择
npm	最大兼容	选择最新兼容版本
Cargo	最大兼容	选择最新兼容版本
pip	最新版本	选择最新可用版本

MVS 的优势 #

可重现构建：版本选择确定性
避免依赖地狱：不会选择意外的高版本
简单明了：算法易于理解

版本查询语法 #

基本语法 #

bash

# 指定版本
go get pkg@v1.2.3

# 最新版本
go get pkg@latest

# 特定分支
go get pkg@main
go get pkg@develop

# commit hash
go get pkg@abc123

# 版本范围（不推荐）
go get pkg@'>=1.0.0'

版本前缀匹配 #

bash

# 匹配主版本
go get pkg@v1          # 选择 v1.x.x 最新版
go get pkg@v1.2        # 选择 v1.2.x 最新版

# 示例
go get github.com/gin-gonic/gin@v1      # v1.9.1
go get github.com/gin-gonic/gin@v1.9    # v1.9.1

更新命令 #

bash

# 更新到最新补丁版本
go get -u=patch pkg

# 更新到最新次版本
go get -u pkg

# 更新到最新主版本（谨慎使用）
go get pkg@latest

版本发布流程 #

准备发布 #

bash

# 1. 确保代码质量
go test ./...
go vet ./...

# 2. 更新文档
# 更新 README.md
# 更新 CHANGELOG.md

# 3. 更新 go.mod
go mod tidy

打标签 #

bash

# 1. 提交代码
git add .
git commit -m "release v1.0.0"

# 2. 创建标签
git tag v1.0.0

# 3. 推送代码和标签
git push origin main
git push origin v1.0.0

发布 v2+ 版本 #

bash

# 1. 创建 v2 分支（可选）
git checkout -b v2
# 或使用主分支

# 2. 修改 go.mod
# module github.com/myuser/mylib/v2

# 3. 更新代码
# 修改 API

# 4. 打标签
git tag v2.0.0
git push origin v2.0.0

版本发布检查清单 #

markdown

## 发布前检查

- [ ] 所有测试通过
- [ ] 代码审查完成
- [ ] 文档更新
- [ ] CHANGELOG 更新
- [ ] go.mod 整理
- [ ] 版本号正确
- [ ] 标签推送成功

## 发布后验证

- [ ] go get 新版本成功
- [ ] 新项目可以正常使用
- [ ] 文档网站更新

预发布版本管理 #

创建预发布版本 #

bash

# Alpha 版本
git tag v1.0.0-alpha.1
git push origin v1.0.0-alpha.1

# Beta 版本
git tag v1.0.0-beta.1
git push origin v1.0.0-beta.1

# RC 版本
git tag v1.0.0-rc.1
git push origin v1.0.0-rc.1

使用预发布版本 #

bash

# 安装预发布版本
go get github.com/myuser/mylib@v1.0.0-beta.1

# @latest 不会选择预发布版本
go get github.com/myuser/mylib@latest  # 选择最新的正式版本

# 查看所有版本
go list -m -versions github.com/myuser/mylib

预发布版本命名规范 #

text

v1.0.0-alpha      # 内部测试
v1.0.0-alpha.1    # 内部测试第1次迭代
v1.0.0-beta       # 公开测试
v1.0.0-beta.2     # 公开测试第2次迭代
v1.0.0-rc.1       # 发布候选第1版

版本撤回 #

使用 retract #

// go.mod
module github.com/myuser/mylib

go 1.21

// 撤回单个版本
retract v1.0.0

// 撤回多个版本
retract (
    v1.0.0
    v1.0.1
)

// 带说明的撤回
retract v1.0.0 // 发现安全漏洞 CVE-2024-1234

撤回流程 #

bash

# 1. 在 go.mod 中添加 retract
# 2. 提交并打新标签
git add go.mod
git commit -m "retract v1.0.0"
git tag v1.0.2
git push origin main
git push origin v1.0.2

# 3. 用户更新时会看到警告
go get github.com/myuser/mylib@v1.0.0
# warning: github.com/myuser/mylib@v1.0.0: retracted by module author

撤回原因 #

retract v1.0.0 // 安全漏洞
retract v1.0.1 // 严重 Bug
retract v1.0.2 // 兼容性问题
retract v1.0.3 // 发布错误

版本兼容性 #

向后兼容原则 #

text

v1.0.0 → v1.0.1  ✅ 兼容（Bug 修复）
v1.0.0 → v1.1.0  ✅ 兼容（新增功能）
v1.0.0 → v2.0.0  ❌ 不兼容（重大变更）

兼容性检查 #

bash

# 使用 go-apicheck 检查 API 兼容性
go install golang.org/x/exp/cmd/apidiff@latest

# 比较两个版本
apidiff github.com/myuser/mylib@v1.0.0 github.com/myuser/mylib@v1.1.0

常见兼容性问题 #

// ❌ 不兼容：删除导出函数
// func OldFunction() {} // 删除

// ❌ 不兼容：修改函数签名
// func Process(data string) error {}
func Process(data []byte) error {} // 签名变更

// ❌ 不兼容：修改接口
type Reader interface {
    Read(p []byte) (n int, err error)
    // Close() error // 新增方法
}

// ✅ 兼容：新增函数
func NewFunction() {}

// ✅ 兼容：新增可选参数（使用选项模式）
func Process(data string, opts ...Option) error {}

版本管理最佳实践 #

版本号选择 #

bash

# 开发阶段
v0.x.x  # 快速迭代，API 不稳定

# 正式发布
v1.0.0  # API 稳定

# 功能更新
v1.1.0  # 新增功能

# Bug 修复
v1.1.1  # 修复 Bug

# 重大变更
v2.0.0  # 不兼容的变更

CHANGELOG 维护 #

markdown

# Changelog

## [1.2.0] - 2024-01-15

### Added
- 新增 Feature A
- 新增 Feature B

### Changed
- 优化 Performance

### Fixed
- 修复 Bug #123

### Security
- 修复安全漏洞 CVE-2024-1234

## [1.1.0] - 2024-01-01
...

版本标签管理 #

bash

# 查看所有标签
git tag -l

# 删除本地标签
git tag -d v1.0.0

# 删除远程标签
git push origin --delete v1.0.0

# 查看标签信息
git show v1.0.0

实战案例 #

案例一：从 v1 升级到 v2 #

bash

# 1. 创建 v2 分支
git checkout -b v2

# 2. 修改 go.mod
sed -i 's|module github.com/myuser/mylib|module github.com/myuser/mylib/v2|' go.mod

# 3. 更新内部导入
# 将所有 "github.com/myuser/mylib" 改为 "github.com/myuser/mylib/v2"

# 4. 修改 API
# 进行不兼容的变更

# 5. 更新文档
# 说明迁移指南

# 6. 打标签
git commit -am "release v2.0.0"
git tag v2.0.0
git push origin v2
git push origin v2.0.0

案例二：同时维护多版本 #

bash

# 目录结构
mylib/
├── v1/              # v1.x 分支
│   └── go.mod       # module github.com/myuser/mylib
└── v2/              # v2.x 分支
    └── go.mod       # module github.com/myuser/mylib/v2

# 维护 v1.x
git checkout v1
# 修复 Bug
git commit -am "fix: bug in v1"
git tag v1.0.1
git push origin v1
git push origin v1.0.1

# 维护 v2.x
git checkout v2
# 修复 Bug
git commit -am "fix: bug in v2"
git tag v2.0.1
git push origin v2
git push origin v2.0.1

案例三：使用预发布版本测试 #

bash

# 1. 发布 beta 版本
git tag v2.0.0-beta.1
git push origin v2.0.0-beta.1

# 2. 用户测试
go get github.com/myuser/mylib/v2@v2.0.0-beta.1

# 3. 收集反馈并修复

# 4. 发布 RC 版本
git tag v2.0.0-rc.1
git push origin v2.0.0-rc.1

# 5. 正式发布
git tag v2.0.0
git push origin v2.0.0

下一步 #

继续深入学习：

常用命令速查 - 掌握更多命令
高级特性 - 工作区模式等
最佳实践 - 实战经验

Go Modules 版本管理指南 #

语义化版本（SemVer） #

版本格式 #

版本组成 #

版本递增规则 #

版本示例 #

预发布版本排序 #

主版本与导入路径 #

导入路径规则 #

模块定义 #

多版本共存 #

go.mod 示例 #

伪版本（Pseudo-version） #

什么是伪版本 #

伪版本格式 #

伪版本生成 #

伪版本 vs 正式版本 #

推荐做法 #

版本选择算法 #

最小版本选择（MVS） #

MVS 工作原理 #

与其他包管理器对比 #

MVS 的优势 #

版本查询语法 #

基本语法 #

版本前缀匹配 #

更新命令 #

版本发布流程 #

准备发布 #

打标签 #

发布 v2+ 版本 #

版本发布检查清单 #

预发布版本管理 #

创建预发布版本 #

使用预发布版本 #

预发布版本命名规范 #

版本撤回 #

使用 retract #

撤回流程 #

撤回原因 #

版本兼容性 #

向后兼容原则 #

兼容性检查 #

常见兼容性问题 #

版本管理最佳实践 #

版本号选择 #

CHANGELOG 维护 #

版本标签管理 #

实战案例 #

案例一：从 v1 升级到 v2 #

案例二：同时维护多版本 #

案例三：使用预发布版本测试 #

下一步 #