必须在 go.mod 中声明与 import 路径完全一致的 module 路径，如 import "github.com/yourname/lib/v2" 则 module 必须为 github.com/yourname/lib/v2；主版本≥2 时路径末尾须带 /v2（非 /v2.0 或 /v2），大小写、下划线、连字符均需严格匹配；tag 必须用 git tag -a v2.1.0 创建并单独推送；发布前需在干净环境中验证 go mod download 和 go list -m。
必须在 go.mod 中声明与实际 import 路径完全一致的 module 路径，否则下游用户 go get 会失败或静默 fallback 到最新 commit。
module 声明路径必须和 import 路径一字不差
Go 工具链不校验“语义等价”，只做字符串精确匹配。比如你在代码里写 import "github.com/yourname/lib/v2"，但 go.mod 里写的是 module github.com/yourname/lib 或 module github.com/yourname/lib/v2.0，都会导致 go build 报错：找不到包，或 go list -m 显示路径不一致。
常见错误现象：go get github.com/yourname/lib@v2.1.0 成功，但用户代码里 import "github.com/yourname/lib/v2" 仍报错 no required module provides package——本质就是 go.mod 里没写 /v2。
- 主版本 ≥2 时，
module行末尾必须带/v2、/v3等（不能是/v2.0或/V2） - 路径大小写敏感：GitHub 组织名是
YourName，就别写成yourname；下划线、连字符也必须原样保留 - 不要为了“好看”把模块路径改成
example.com/lib，除非你真能控制这个域名且已配置好重定向
tag 必须用 git tag -a 创建并单独推送
Go 模块索引器只认带注解的 tag，轻量 tag（git tag v1.2.3）不会被识别。更关键的是，git push --tags 容易把本地残留的测试 tag（如 v1.2.3-rc1）一并推上去，污染下游依赖解析。
- 正确流程：先
git tag -a v2.1.0 -m "release v2.1.0"，再git push origin v2.1.0 - tag 名必须严格为
vX.Y.Z格式（如v2.1.0），不能是1.2.3、release-v2.1.0或v2.1.0-beta - 推送后立即验证：
go list -m -json github.com/yourname/lib/v2@v2.1.0应返回有效 JSON；若报unknown revision，说明 tag 未生效或格式错误
发布前必须验证 go mod download 和 go list -m
很多问题只有别人 go get 才暴露，但你可以用两条命令提前拦截：
-
go mod download github.com/yourname/lib/v2@v2.1.0：模拟下游下载行为，失败说明 tag 未推、网络不可达或私有仓库缺认证 -
go list -m -json github.com/yourname/lib/v2@v2.1.0：检查模块元信息是否可读，返回中Path字段必须等于你的module声明，Version必须是v2.1.0 - 这两步要在干净环境（如新 Docker 容器）里跑，避免本地缓存掩盖问题
别用 replace 模拟多版本发布
replace 是开发期调试手段，不是发布方案。你在 go.mod 里写 replace github.com/yourname/lib => ./local-lib，对本地 go run 有效，但一旦推送到 GitHub，别人 go get 时根本看不到这个 replace，只会按 require 行去远程拉取——而那个远程路径如果没对应 tag，就彻底断链。
- 真正兼容多版本的方式：v1 和 v2 分属不同 module 路径（
/v1vs/v2），各自维护独立分支和 tag - 不要试图在同一个
go.mod里通过replace“绕过”版本规则，这会让下游构建不可重现 - 如果你正在开发 v2，就新建一个
lib/v2目录，里面放自己的go.mod，module 声明为github.com/yourname/lib/v2
最容易被忽略的是：模块路径声明、import 语句、git tag 名、go list 返回值，这四者必须完全一致。少一个 v、多一个空格、错一个大小写，下游用户就会陷入“明明装了却用不了”的困境。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
