Go模块版本号必须用vX.Y.Z格式打tag，如v1.2.0；非v开头的标签（如1.2.0）不被go mod识别，会导致go get失败和go list查不到真实版本。
Go模块版本号必须用 vX.Y.Z 格式打 tag
Go 的 go mod 工具只识别以 v 开头的语义化版本 tag，比如 v1.2.0、v0.9.1。写成 1.2.0 或 release-1.2.0 会被完全忽略，go list -m -versions 查不到，下游也拉不到。
常见错误现象：
-
go get example.com/repo@1.2.0报错：unknown revision 1.2.0 -
go list -m -versions example.com/repo只显示v0.0.0-...伪版本，没有真实 tag
实操建议：
- 打 tag 前确保
go.mod中的 module 路径与仓库地址一致（如github.com/user/repo） - 使用
git tag v1.3.0 && git push origin v1.3.0，不要漏掉v和push - 预发布版本可加后缀，如
v1.3.0-beta.1或v1.3.0-rc.2，Go 支持排序（-beta-rc
go mod tidy 后再打 tag，否则依赖可能不一致
模块的版本快照必须反映实际可构建状态。如果在修改代码但没运行 go mod tidy 就打 tag，可能导致 go.sum 缺失校验项，或 go.mod 中存在未清理的间接依赖。
立即学习“go语言免费学习笔记（深入）”；
这会引发下游 go build 失败或校验失败，错误信息类似：verifying github.com/xxx@v1.2.0: checksum mismatch。
实操建议：
- 在目标 commit 上执行：
go mod tidy && git add go.mod go.sum && git commit -m "tidy deps for v1.2.0" - 再打 tag：
git tag v1.2.0（tag 必须指向这个 tidy 后的 commit） - CI 中建议加检查：
git status --porcelain | grep -q '^??' && exit 1 || true，防止遗漏生成文件
主版本升级（v2+）必须改 module 路径
Go 不支持同路径下多主版本共存。若要发布 v2.0.0，module 路径必须包含 /v2，例如从 github.com/user/lib 变为 github.com/user/lib/v2。
否则 go get github.com/user/lib@v2.0.0 会解析失败，报错：invalid version: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v2。
实操建议：
- 在新分支（如
v2）中修改go.mod第一行：module github.com/user/lib/v2 - 所有导出包路径（如
import "github.com/user/lib/v2/foo"）都要同步更新 - 旧版
v1.x继续维护，无需迁移；新版v2是独立模块，互不影响
私有模块或非 GitHub 仓库也要遵循相同规则
不管托管在哪（GitLab、Gitee、公司内网 Git、甚至本地 file://），只要用 go mod 管理，tag 规范和 go.mod 路径一致性要求完全一样。
容易被忽略的一点：私有域名模块（如 git.example.com/team/proj）如果启用了 Go Proxy（如 GOPROXY=https://proxy.golang.org,direct），需确保该域名能被 proxy 正确解析——多数自建 proxy 不默认支持非 public 域名，此时应设 GOPRIVATE=git.example.com/*，否则 go get 会跳过认证直连 proxy，返回 404 或 403。
实操建议：
- 始终用
git config --global url."https://token@server/".insteadOf "https://server/"避免凭据交互 - 验证是否生效：
go list -m -versions git.example.com/team/proj应列出 tag，而非报no matching versions - 本地测试可用
go install ./...@v1.2.0模拟下游行为
v 字母漏写、go.mod 路径没随主版本更新、或者 go.sum 没提交就推 tag —— 这三处一错，下游就拉不到干净版本。 
