Go要求v2+模块路径必须包含版本号，以避免API不兼容问题。正确做法是修改go.mod中module为含/v2的路径，发布时打v2.0.0等标签，导入时使用带/v2的完整路径，否则会导致版本解析错误和编译失败。
在 Golang 中使用语义导入版本（Semantic Import Versioning）主要是为了在模块的主版本号大于等于 v2 时，正确管理包的导入路径，避免破坏现有代码。Go 的模块系统要求当模块发布 v2 或更高版本时，必须在模块路径中显式包含版本号。
为什么需要语义导入版本
Go 的默认行为是将模块的主版本 v0 和 v1 视为兼容的开发阶段，不强制在导入路径中包含版本号。但从 v2 开始，API 可能发生不兼容变更，因此 Go 要求在模块路径中加入版本后缀，以确保导入的是正确的版本。
关键点：如果你的模块发布了 v2 或更高版本，必须在 go.mod 文件中的 module 声明里包含版本号，如 module example.com/mypkg/v2。如何正确设置 v2+ 模块
要让你的 Go 模块支持语义导入版本，请按以下步骤操作：
- 修改 go.mod 文件中的模块名称，添加版本后缀：
module example.com/user/myproject/v2
立即学习“go语言免费学习笔记（深入）”；
- 确保所有导出的 API 在内部目录结构中保持一致，例如源码仍放在根目录或子包中，不需要移动文件到 v2/ 子目录（除非你希望同时维护多个主版本）。
- 发布新版本时打 git tag，如 v2.0.0、v2.1.0 等。tag 必须以 "v" 开头并符合语义化版本规范。
- 其他项目导入你的模块时，必须使用带版本的路径：
import "example.com/user/myproject/v2"
常见错误与注意事项
如果不遵循语义导入版本规则，用户在升级到 v2+ 时会遇到编译错误。
-
错误：未在模块路径中包含 /v2 —— 即使打了 v2.0.0 的 tag，如果 go.mod 还是
module example.com/mypkg，Go 会认为这是 v1 的延续，导致版本解析混乱。 - 错误：从 v1 到 v2 修改了导入路径但未更新文档 —— 用户不知道要改成 /v2，导致无法正确导入。
- 建议：使用 gorelease 工具检查版本兼容性 —— 它可以帮助你发现潜在的 API 不兼容问题。
同时维护多个主版本
如果你想在同一仓库中维护 v1 和 v2 两个主版本，可以采用以下结构：
根目录 (v2): go.mod 中声明 module example.com/mypkg/v2 分支方式：用 v1 分支保留旧版本代码，主分支开发 v2 或使用多版本目录（较少见）：将 v1 放在 /v1 目录，v2 在根目录或 /v2
通常推荐使用分支策略来维护老版本，主分支推进新版本。
基本上就这些。只要记住：v2+ 的模块路径必须包含 /vN，否则 Go 工具链不会正确识别版本。这不是可选项，而是强制要求。
