模块发布前必须设置正确的 go.mod 文件，其 module path 需与代码托管地址一致（如 github.com/yourname/yourmodule），打 tag 必须为 vX.Y.Z 格式，且需在全新环境验证 go get 和 go build 是否正常。
模块发布前必须设置正确的 go.mod 文件
Go 模块发布的核心是 go.mod 中的模块路径（module path）必须与代码托管地址一致，否则下游用户 go get 会失败或拉取到错误版本。例如你的代码托管在 GitHub，模块路径就得写成 github.com/yourname/yourmodule，不能是本地路径或自定义域名（除非你已配置了 GOPROXY 和 go.sum 验证机制）。
常见错误：用 go mod init mymodule 初始化后没改 module path，导致后续 go get 报错 unknown revision 或跳转到私有仓库地址。
- 初始化时直接指定正确路径：
go mod init github.com/yourname/yourmodule
- 如果已初始化错，手动编辑
go.mod第一行，把module xxx改为真实托管路径 - 确保所有
import语句中的包路径与go.mod的 module path 前缀一致
打 tag 必须符合 Go 版本语义（vX.Y.Z 格式）
Go 官方工具链只识别以 v 开头的语义化版本 tag，如 v1.0.0、v0.5.2。打成 1.0.0 或 release-1.0 会导致 go list -m -versions 查不到，go get 也拉不到该版本。
发布流程中这一步最容易被跳过或写错，尤其从其他语言迁移过来的开发者习惯不加 v。
立即学习“go语言免费学习笔记（深入）”；
- 本地提交完代码后，运行：
git tag v1.0.0
- 推送到远程（含 tag）：
git push origin main && git push origin v1.0.0
- 验证是否生效：
go list -m -versions github.com/yourname/yourmodule
应能列出v1.0.0
go get 能拉到，不代表别人能正常构建
模块可被 go get 下载，仅说明路径和 tag 可见；但下游项目 go build 失败，往往是因为：导出符号缺失、internal 包误暴露、测试文件里引用了未声明的依赖、或 replace / exclude 指令残留在 go.mod 中并被提交。
最稳妥的验证方式，是在全新环境模拟下游使用：
- 新建空目录，运行：
go mod init example.com/test
go get github.com/yourname/yourmodule@v1.0.0 - 写一个最小
main.go导入并使用你的包，再go build - 检查
go.mod是否引入了意外的间接依赖（比如 dev-only 工具被写进主模块）
私有模块或非 GitHub 托管需额外注意 GOINSECURE 和代理配置
如果你的模块托管在 GitLab、Gitee 或公司内网 Git，Go 默认拒绝从 HTTP 或未知 CA 的 HTTPS 地址拉取——会报错 invalid version: unknown revision 或 x509: certificate signed by unknown authority。
这不是模块本身的问题，而是客户端环境限制。发布者无法绕过，但必须提前告知使用者如何配置：
- 若走 HTTP（不推荐）：
export GOINSECURE="gitlab.example.com" - 若用自签名证书：
git config --global http."https://gitlab.example.com".sslCAInfo /path/to/cert.pem - 更可靠的做法：把模块镜像推送到支持 Go proxy 协议的公开服务（如 pkg.go.dev 会自动索引 GitHub/GitLab 公开库），或自行搭建
athens代理
真正容易被忽略的是：模块发布后，文档里没提这些环境前提，导致用户卡在第一步，反复怀疑是不是自己 go get 命令写错了。
