Golang发布公共模块前需要注意什么

Go模块发布需确保四点：模块路径与代码托管URL逐字符一致；必须打符合vX.Y.Z格式的语义化tag并推送；导出标识符首字母大写且命名规范；go.mod中不得含replace或exclude。

模块路径必须匹配代码托管地址

Go 模块的 module 声明（go.mod 文件首行）不是随意起的，它必须与你最终托管代码的 URL 路径完全一致。比如你把代码放在 GitHub 上的 github.com/yourname/mylib，那 go.mod 里就必须是：

module github.com/yourname/mylib

。如果写成 module mylib 或 module github.com/yourname/mylib/v2（但没实际打 v2 tag），下游 go get 会失败或拉到错误版本。

• 发布前务必检查 go.mod 中的模块路径是否和远程仓库 HTTPS 地址（不含 .git 后缀）逐字符一致
• 若计划支持 v2+ 版本，路径末尾需加 /v2，且对应分支/tag 必须存在；不加则默认为 v0/v1，不能混用
• 私有域名（如 git.example.com/team/lib）也必须可被 Go 工具链解析——可能需要配置 GOINSECURE 或 ~/.netrc

必须打语义化版本 tag 并推送

Go 不靠分支名识别版本，只认 Git tag。没有 tag，go get github.com/yourname/mylib 默认拉 main 分支最新提交，这不是可复现的发布状态。

• tag 名必须符合 vX.Y.Z 格式（如 v1.0.0），开头带 v，不能是 1.0.0 或 release-1.0
• 打完 tag 后必须 git push origin v1.0.0 —— 本地 tag 不会自动同步
• 如果模块路径含 /v2，tag 必须是 v2.0.0，否则 Go 会拒绝解析

导出标识符命名要符合 Go 习惯

Go 的公共 API 全靠首字母大写控制可见性。但光大写不够，名字本身还得清晰、无歧义、不缩写过度。

• 函数/类型/变量名以大写字母开头才对外暴露，例如 DoSomething() 可导出，doSomething() 不可导出
• 避免单字母变量（如 Func(x, y int) *T 中的 x）、模糊缩写（GetUsr() 应为 GetUser()）
• 接口名优先用名词或能表达能力的词，如 Reader、Writer、Stringer；避免 IReader 或 ReaderInterface

go.mod 里不能留 replace 或 exclude

replace 和 exclude 是开发期临时手段，一旦推送到公开仓库，它们会让所有下游用户构建失败或行为异常。

• replace github.com/some/dep => ../local-copy：别人没有 ../local-copy，go build 直接报错
• exclude github.com/bad/dep v1.2.3：可能掩盖真实依赖冲突，且 Go 1.17+ 在非主模块中 ignore exclude，导致行为不一致
• 发布前运行 go mod tidy，确认 go.mod 干净，无注释掉的 replace 行，也无 exclude 段

模块发布不是“提交代码 + 打个 tag”就完事。路径、tag、导出名、依赖声明这四点任一出错，都会让使用者卡在 go get 第一步，或者引入后 panic。尤其注意 vN 路径和 tag 的严格对应——这是最常被忽略、也最难排查的一环。