Go工具链需协同配置GOPRIVATE、Git凭据和模块路径语义才能拉取私有模块：设GOPRIVATE跳过代理校验，配Git HTTPS Token或SSH密钥确保认证，模块路径须与Git地址一致或用replace映射。
Go 模块默认从公共代理（如 proxy.golang.org）拉取依赖，但私有代码不能公开上传。要让 go build 或 go get 正确解析并拉取公司内网或 GitHub 私有仓库的模块，关键不是“创建私有模块”，而是“让 Go 工具链信任并正确访问私有源”。这涉及 GOPRIVATE、Git 凭据、SSH 配置和模块路径语义三者的协同。
设置 GOPRIVATE 跳过代理和校验
Go 1.13+ 强制对所有非私有模块启用 checksum 验证和代理转发。若你的私有模块路径含公司域名（如 git.company.com/team/project），必须显式告知 Go：“这个前缀不走代理、不查 sum.golang.org”。否则会报错：verifying git.company.com/team/project@v0.1.0: checksum mismatch 或 failed to fetch。
执行以下任一方式（推荐全局设置）：
- 终端临时生效：
export GOPRIVATE=git.company.com/* - 写入 shell 配置（如
~/.zshrc）：export GOPRIVATE="git.company.com/*,github.com/myorg/*" - 项目级（只影响当前目录及子目录）：
go env -w GOPRIVATE=git.company.com/*
注意：GOPRIVATE 值是 glob 模式，* 匹配任意字符（不含 /），所以 git.company.com/* 覆盖 git.company.com/a 和 git.company.com/a/b；但 git.company.com/** 无效。
立即学习“go语言免费学习笔记（深入）”；
确保 Git 能无密码克隆私有仓库
Go 在拉取私有模块时底层调用 git clone。如果 Git 无法认证，就会卡在 Cloning into ... 或报错 fatal: could not read Username。这不是 Go 的问题，而是 Git 凭据没配好。
根据你私有仓库的协议选择对应方案：
- HTTPS 方式（需用户名+Token）：
运行git config --global credential.helper store，然后首次手动git clone https://git.company.com/team/project，输入用户名和 Personal Access Token（PAT），Git 会缓存凭据 - SSH 方式（推荐）：
确保~/.ssh/id_rsa.pub已添加到 Git 服务器（如 GitHub/GitLab）的 SSH Keys；且git@github.com:myorg/private-module.git能成功git clone；Go 会自动复用 SSH 配置
验证方法：git ls-remote git@github.com:myorg/private-module.git 或 git ls-remote https://git.company.com/team/project.git 应返回 ref 列表，而非权限错误。
模块路径必须与 Git 远程地址可推导
Go 不允许“随意命名”模块路径。当你在私有仓库中执行 go mod init example.com/foo，后续 go get example.com/foo@v1.2.3 时，Go 会尝试解析 example.com/foo 对应的 Git 地址。它默认按规则拼接：https://example.com/foo（HTTP）或 git@example.com:foo（SSH），但多数私有 Git 服务并不托管在根域名下。
解决办法：在模块根目录放一个 .git/config，或更可靠地——在模块的 go.mod 文件顶部添加 replace 或使用 go get 时指定完整 URL：
go get git.company.com/team/project@v0.5.0
或者，在 go.mod 中显式声明模块路径为实际 Git 地址（Go 1.18+ 支持）：
module git.company.com/team/project
这样 go get git.company.com/team/project 就能直连，无需额外 replace。但如果模块路径和 Git 地址不一致（比如模块名是 company.com/project，但 Git 地址是 git.company.com/team/project），就必须用 replace：
replace company.com/project => git.company.com/team/project v0.5.0
CI/CD 环境中常见失败点
本地能跑通，CI（如 GitHub Actions、GitLab CI）却拉不到私有模块？大概率是环境缺失凭据或 GOPRIVATE 未生效。
- GitHub Actions：必须在
steps中显式设置GOPRIVATE，且不能依赖用户 shell 配置：env: { GOPRIVATE: 'git.company.com/*' } - GitLab CI：在
.gitlab-ci.yml的variables下添加GOPRIVATE: "git.company.com/*" - 所有 CI：避免用 HTTPS + 用户名密码（不安全），改用 SSH key（通过
ssh-agent注入）或 GitHub Token（配合git config --global url."https://x-token-auth:${GITHUB_TOKEN}@github.com".insteadOf "https://github.com"）
最容易被忽略的是：GOPRIVATE 必须包含模块路径的**最左前缀**，且大小写敏感；而 Git 凭据缓存只对当前用户有效，CI runner 往往是全新环境，必须每次重配。
