go mod 无法拉取私有 git 仓库模块需设置 goprivate 环境变量跳过代理和校验，确保 ssh 配置正确，并使用符合 vx.y.z 格式的 tag。
go mod 无法拉取私有 Git 仓库模块？先检查 GOPRIVATE
Go 默认把所有以 https:// 开头的模块都当作公共模块，走 proxy（如 proxy.golang.org）和 checksum 验证。私有仓库（如 GitHub 私有库、GitLab 内网库）若未显式声明为“不经过代理”，go mod tidy 会直接失败，报错类似：verifying github.com/your-org/private-module@v0.1.0: github.com/your-org/private-module@v0.1.0: reading https://sum.golang.org/lookup/github.com/your-org/private-module@v0.1.0: 404 Not Found
解决方法是告诉 Go：这些域名下的模块跳过 proxy 和 sumdb 校验：
- 设置环境变量：
GOPRIVATE=github.com/your-org/*,gitlab.internal.company.com/* - 支持通配符（
*），但不支持**或正则 - 多个域名用英文逗号分隔，不能有空格
- 推荐写入 shell 配置（如
~/.zshrc）并重载：source ~/.zshrc
使用 SSH 地址拉取私有模块时，go get 报 “unknown revision”？确认 git URL 格式与 netrc 配置
Go 模块解析器对 Git URL 敏感。如果私有模块 go.mod 中写的是 git@gitlab.internal.company.com:team/repo.git，而本地 git 命令能 clone，go mod download 却失败，大概率是 Go 没走 SSH，而是尝试用 HTTPS 回退——结果因无凭据被拒。
- 确保
go.mod中 module 路径与你期望的 import 路径一致，例如：module gitlab.internal.company.com/team/repo - 在
~/.gitconfig中配置 URL 重写，强制 Go 使用 SSH：[url "git@gitlab.internal.company.com:"] insteadOf = "https://gitlab.internal.company.com/"
- 不要依赖
~/.netrc：Go 不读它；SSH 密钥需由系统 ssh-agent 管理，且ssh -T git@gitlab.internal.company.com能通
私有模块打了 tag 但 go mod tidy 仍拉不到最新版？检查语义化版本格式与 go.sum 行为
Go 要求私有模块的 tag 必须符合 vX.Y.Z 格式（开头带 v），否则 go list -m -versions 查不到，go get 也会 fallback 到 latest commit（可能不是你想要的发布点）。
立即学习“go语言免费学习笔记（深入）”；
- 错误 tag 示例：
1.2.0、release-1.2→ Go 忽略 - 正确 tag 示例：
v1.2.0、v0.9.1-beta（beta 版本可被识别，但需显式指定） -
go mod tidy默认只拉require中指定的版本；若想升级，需运行：go get gitlab.internal.company.com/team/repo@v1.2.0 - 私有模块不会写入
go.sum的校验行（因跳过 sumdb），但本地缓存仍会生成sum值，用于后续校验一致性
CI/CD 中构建失败：找不到私有模块？统一 GOPRIVATE + SSH 配置 + Git 凭据注入
本地能跑不代表 CI 环境能跑。常见断点在：CI runner 没配置 SSH key、没设 GOPRIVATE、或 Git 服务端启用了 strict host key checking。
- GitHub Actions 示例：用
webfactory/ssh-agent注入 deploy key，并设置GOPRIVATE在 job env 中 - GitLab CI：通过
before_script追加~/.gitconfig并启动 ssh-agent，再ssh-add - 关键验证命令（CI 中加入）：
go env GOPRIVATE、git ls-remote git@gitlab.internal.company.com:team/repo.git、go list -m -versions gitlab.internal.company.com/team/repo - 避免在
go.mod中硬编码replace指向本地路径——这会让 CI 构建彻底失效
私有模块最常卡在「环境不一致」：本地有 ssh-agent，CI 没有；本地设了 GOPRIVATE，CI 没设；tag 名字看似合法，其实缺了 v。每次出问题，优先查这三项。
