go module v2+必须修改import path为/example.com/foo/v2，而非仅改go.mod中的version；否则工具链仍视其为v1，导致拉取失败、版本共存失效。
Go Module v2 必须改 import path，不是改 go.mod 里的 version
Go 的模块版本不是靠 go.mod 里写 version v2.0.0 就生效的——go mod 根本不读这个字段。v2+ 版本生效的唯一方式是：把模块的 import path 末尾加上 /v2（或 /v3 等）。否则所有 Go 工具（go get、go list、依赖解析）都当它是 v0/v1。
常见错误现象：
– go get example.com/foo@v2.0.0 报错 unknown revision v2.0.0
– go list -m all 里始终显示 example.com/foo v1.5.0，哪怕你打了 v2.0.0 tag
– 其他模块 import "example.com/foo" 依然拉到 v1，无法同时共存 v1 和 v2
- 正确做法：把模块根目录的
go.mod第一行改成module example.com/foo/v2 - 对应代码里所有
import "example.com/foo"都要同步改成import "example.com/foo/v2" - 发布前必须打 tag：
git tag v2.0.0 && git push origin v2.0.0（tag 名仍是v2.0.0，不用带/v2） - 如果模块有子包（如
/client），它们的 import path 也要跟着变成example.com/foo/v2/client
为什么不能只改 tag 而不改 import path
Go 的模块代理（proxy.golang.org）和 go 命令本身，都是靠 import path 做模块身份识别的。同一个 path 下的所有版本（v0.1.0、v1.9.0、v2.0.0）被视为同一个模块；而 example.com/foo 和 example.com/foo/v2 是两个完全独立的模块，可并存、可分别升级。
使用场景：
– 你要在新项目里用 v2 的 API，但老项目还卡在 v1，两者不能 break
– 第三方库依赖你的 v1，但你想让新用户直接上 v2，又不想强制迁移
- 不改 import path → Go 认为 v2 是 v1 的“破坏性更新”，会拒绝拉取（
go get报mismatched version） - 改了 import path → v1 和 v2 在
go.sum里是两条独立记录，go list -m all会同时出现example.com/foo v1.5.0和example.com/foo/v2 v2.0.0 - 兼容性影响：v2 模块对 Go 1.11+ 完全兼容，但旧工具链（如某些 CI 里硬编码的
go get example.com/foo）会继续走 v1，不会意外升级
go.mod 里 module 行改了，但本地 build 失败？检查 GOPATH 和 vendor
改完 go.mod 的 module 行后，常见报错是 cannot find package "example.com/foo/v2"，尤其在已有 vendor/ 或 GOPATH 模式残留的项目里。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
常见错误现象：
– go build 提示找不到 /v2 包，但 go list -m 显示正常
– go mod vendor 后 vendor/example.com/foo/ 下只有 v1 的代码，没有 v2/ 子目录
– 本地 go run main.go 成功，但 CI 上失败（环境没清理 GOPATH）
- 先运行
go mod tidy，确保go.sum和go.mod同步，且所有import路径已更新 - 删掉
vendor/目录重做：go mod vendor（v2 模块会生成vendor/example.com/foo/v2/） - 确认没在
GOPATH/src下开发：Go 1.13+ 默认关闭 GOPATH mode，但如果项目根目录外还有同名路径（如$GOPATH/src/example.com/foo），go命令可能优先读它 - CI 中加一句
go env -w GO111MODULE=on，避免旧脚本隐式启用 GOPATH mode
发布后别人 still can’t get v2？检查 proxy 和 checksum
即使你本地一切正常，外部用户执行 go get example.com/foo/v2@v2.0.0 仍可能失败，大概率是模块代理缓存或校验问题。
使用场景：
– 私有模块走自建 proxy（如 Athens）
– 模块刚发布，proxy.golang.org 还没抓取
– 你改过 tag（force-push）或重新打 tag
- 先直连源码库测试：
GO_PROXY=direct go get example.com/foo/v2@v2.0.0，排除 proxy 缓存干扰 - 如果 direct 成功，说明 proxy 没同步：等几分钟，或手动触发（Athens 可调
/invalidate）；public proxy 一般 30 分钟内自动抓取 - 如果 direct 也失败，检查
go.sum是否含该版本 checksum：运行go mod download -json example.com/foo/v2@v2.0.0，看输出里error字段 - 曾 force-push 过 tag？删掉本地
pkg/mod/cache/download/example.com/foo/v2并go clean -modcache，再试
最易被忽略的一点：v2 模块的 go.mod 文件里，go 指令声明的版本（如 go 1.18）必须 ≥ 依赖它的项目的最低 Go 版本，否则 go build 会静默跳过该模块——它根本不会出现在 go list 结果里。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
