如何使用Golang发布私有模块_Golang私有仓库版本控制与发布技巧

私有模块发布必须配置GOPRIVATE并确保go.mod路径与仓库URL一致。需设置export GOPRIVATE="git.example.com/internal/,github.com/myorg/"，模块路径须严格匹配仓库地址（如git.example.com/internal/auth），且tag需为annotated、符合vX.Y.Z格式，CI中应设GOPROXY=direct或proxy.golang.org,direct及GOSUMDB=sum.golang.org配合GOPRIVATE。

Go私有模块发布必须配置GOPRIVATE

不设GOPRIVATE，go get会默认走代理（如proxy.golang.org）并校验 checksum，导致私有仓库 404 或 checksum mismatch 错误。这不是权限问题，是 Go 工具链的默认安全策略。

必须在 shell 环境中设置：

export GOPRIVATE="git.example.com/internal/*,github.com/myorg/private-*"

支持通配符，但注意：*只匹配一级路径（如git.example.com/internal/mymodule匹配，git.example.com/internal/foo/mymodule不匹配），多级需写成git.example.com/internal/**（Go 1.19+ 支持）。

• 推荐用~/.bashrc或~/.zshrc持久化，避免 CI/CD 中漏设
• 若用 GitHub/GitLab 私有库，域名必须精确——github.com/myorg/private和github.com/myorg/private-go需分别列出或用github.com/myorg/*
• 设置后执行go env GOPRIVATE验证是否生效

私有模块的go.mod模块路径必须与仓库地址一致

Go 不靠import路径推断源码位置，而是严格按module声明的路径匹配go get目标。比如你的 Git 仓库地址是https://git.example.com/internal/auth，那go.mod第一行必须是：

module git.example.com/internal/auth

否则go get git.example.com/internal/auth@v0.1.0会失败，报错类似unknown revision v0.1.0或invalid version: unknown revision。

• 模块路径不能以./、../开头，也不能是本地文件路径
• 如果用 SSH 克隆（如git@git.example.com:internal/auth.git），模块路径仍应为 HTTPS 风格（git.example.com/internal/auth），Go 会自动尝试 SSH fallback（前提是git config --global url."git@git.example.com:".insteadOf "https://git.example.com/"已配置）
• 模块路径区分大小写，Git.Example.Com和git.example.com被视为不同模块

打 tag 前必须确保go mod tidy无变更且go build通过

私有模块版本由 Git tag 控制（如v1.2.0），但 Go 不校验 tag 内容合法性。如果 tag 指向的 commit 中go.mod依赖未清理、或引入了本地 replace、或存在语法错误，下游go get可能静默失败或构建报错。

• 发布前务必运行：go mod tidy && go build ./...，确认无 error 且无go.mod变动
• 避免使用轻量 tag（lightweight tag），用 annotated tag：git tag -a v0.3.1 -m "release auth module"，便于后续审计
• tag 名称必须符合语义化版本格式（vX.Y.Z），否则go list -m -versions无法识别
• push tag 到远程：先git push代码，再git push origin v0.3.1

CI/CD 中发布私有模块要绕过 GOPROXY 和 GOSUMDB

在 GitHub Actions / GitLab CI 等环境中，系统默认启用GOPROXY和GOSUMDB，这会导致私有模块构建时尝试从公共代理拉取自身依赖，或校验失败。

必须显式禁用：

env:
  GOPROXY: "direct"
  GOSUMDB: "off"

或者更安全地组合设置：

env:
  GOPROXY: "https://proxy.golang.org,direct"
  GOSUMDB: "sum.golang.org"  # 仅对公共模块校验
  GOPRIVATE: "git.example.com/internal/*"

• GOPROXY=direct强制所有模块直连源，适合纯私有环境；混合环境建议用proxy.golang.org,direct回退机制
• GOSUMDB=off虽快但放弃校验，生产发布建议保留GOSUMDB，靠GOPRIVATE让私有模块跳过校验，而非全局关闭
• CI 脚本中应在go mod download前就设置好这些变量，否则缓存可能已污染

私有模块发布最常卡在GOPRIVATE漏配或模块路径与仓库 URL 不一致——这两处一旦出错，现象都是“找不到包”或“未知 revision”，但实际原因和调试路径完全不同。先确认环境变量，再核对go.mod，比反复重推 tag 更省时间。