Go语义导入版本控制是强制规则：v2+主版本必须在模块路径和import语句中显式包含/v2等版本后缀，否则编译失败；v0/v1除外，其中v1无需写/v1，而v2+需同步更新go.mod、import语句及Git标签。
Go 的语义导入版本控制（Semantic Import Versioning）不是可选项，而是强制规则——它直接决定代码能否编译通过，也决定了多个主版本能否安全共存。
核心逻辑：主版本号必须体现在导入路径里
当一个模块发布 v2.0.0 或更高版本时，Go 要求你把主版本号 显式写进模块路径和所有 import 语句中。这不是命名习惯，是工具链硬性约束。
- v1 版本路径：module github.com/user/lib → import "github.com/user/lib"
- v2 版本路径：module github.com/user/lib/v2 → import "github.com/user/lib/v2"
- v3 版本路径：module github.com/user/lib/v3 → import "github.com/user/lib/v3"
漏掉 /v2 就会报错：`cannot find module providing package github.com/user/lib`，因为 Go 工具链根本不会在 github.com/user/lib 下查找 v2 的代码。
为什么必须这样设计
目的是让不同主版本的包在同一个项目里“互不干扰”。比如你的项目同时用到：
-
github.com/user/lib（v1.x）处理旧逻辑 -
github.com/user/lib/v2（v2.x）用于新功能
Go 允许两者并存，各自独立构建、测试、升级。没有这个规则，v2 的不兼容变更就会直接破坏 v1 的调用方。
Convert Github Repository
下载
适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……
v0 和 v1 是例外，但有隐含约定
v0.x.y 属于开发阶段，API 不稳定，不保证兼容；v1.x.y 是第一个稳定版，也是唯一一个 不需要写 /v1 的主版本。
- 模块路径写
github.com/user/lib，go.mod 里写require github.com/user/lib v1.5.0 - import 语句仍是
import "github.com/user/lib"，不能写成/v1 - 一旦升到 v2，就必须改路径、改 import、改 go.mod 里的 require 行
实际操作中容易踩的坑
发布 v2+ 版本时，三处必须同步更新：
- Git 打标签：git tag v2.0.0
- go.mod 第一行 module 声明改成
module github.com/user/lib/v2 - 所有源文件中的 import 路径替换为
"github.com/user/lib/v2"
少改任何一处，go build 或 go mod tidy 都会失败或拉错版本。
基本上就这些。它不复杂，但容易忽略路径和 import 的一致性。
