Go拉取私有仓库失败主因是认证缺失或GOPROXY干扰：需配置git凭据助手（HTTPS）或SSH密钥（SSH），并设置GOPRIVATE跳过代理直连，三者缺一不可。
Go 无法拉取私有仓库模块的典型错误
执行 go get 或构建时出现类似错误，基本可判定为认证失败或 GOPROXY 配置干扰：
go: module example.com/internal/pkg@v0.1.0: reading example.com/internal/pkg/go.mod at revision v0.1.0: 404 Not Found
或更隐蔽的：
go: example.com/internal/pkg@v0.1.0: invalid version: git ls-remote -q origin in /tmp/gopath/pkg/mod/cache/vcs/...: exit status 128: Host key verification failed. fatal: Could not read from remote repository.
关键点：Go 默认用 git 命令克隆私有仓库，而它不读取 ~/.netrc 或 IDE 内置凭据，也不自动转发 SSH agent —— 必须显式配置凭证或改用 HTTPS+token/SSH+key。
HTTPS 私有仓库：用 git config 设置凭据助手
适用于 GitLab、GitHub（启用 token）、自建 Gitea 等支持 HTTPS Basic Auth 的场景。Go 调用 git 时会触发系统级凭据管理器，但 Linux/macOS 默认不启用，需手动配。
立即学习“go语言免费学习笔记（深入）”；
- 确保已安装
git-credential-libsecret（GNOME）或git-credential-osxkeychain（macOS），或直接用store后端（凭据明文存本地，仅限开发机） - 运行：
git config --global credential.helper store
- 首次拉取时触发输入账号密码（GitHub/GitLab 推荐用 Personal Access Token 代替密码），之后
go get自动复用 - 验证是否生效：
git ls-remote https://example.com/internal/pkg.git
—— 不报 401 即成功
SSH 私有仓库：必须用 SSH URL 且确保 git 可无密访问
Go 模块路径如 git@example.com:org/repo.git 会被识别为 SSH 协议，此时 Go 会调用 git 执行 git clone git@example.com:org/repo.git。成败完全取决于本地 git 是否能连上。
- 模块导入路径必须以
git@开头，且与~/.ssh/config中 Host 别名匹配（例如 Hostexample.com→ Usergit） - 运行
ssh -T git@example.com
和git ls-remote git@example.com:org/repo.git
均需成功，否则go get必败 - 避免混用 HTTPS 和 SSH：若
go.mod里写的是https://example.com/org/repo，即使~/.ssh/config配了也无效 - CI 环境中需注入
SSH_PRIVATE_KEY并用ssh-add加载（注意权限：私钥文件 chmod 600）
绕过 GOPROXY 是最常被忽略的一步
国内用户习惯设 GOPROXY=https://goproxy.cn,direct，但该代理**只缓存公开模块**，遇到私有域名（如 example.com）会 fallback 到 direct —— 看似没问题，实则 fallback 时仍走默认 git 行为，未受 proxy 控制，也就没继承你的认证配置。
- 正确做法是显式排除私有域名：
export GOPROXY="https://goproxy.cn,direct" export GOPRIVATE="example.com,git.internal.company"
-
GOPRIVATE值是逗号分隔的域名通配符（支持*和**），匹配后 Go 会跳过 proxy 直连，并启用上述 git 凭据逻辑 - 验证方式：
go env GOPRIVATE
必须输出包含你的域名；再执行go list -m example.com/internal/pkg，观察是否还报 404 或权限错
私有模块不是“加个 token 就行”，而是 git 认证 + Go 协议路由 + 环境变量三者对齐。少一个环节，go mod tidy 就卡在 fetch 阶段不动。
