Git协议配置决定私有模块拉取成败，Go仅调用git命令，认证依赖SSH密钥、HTTPS Token或.gitconfig重写；GOPRIVATE须精确匹配模块路径前缀（如git.example.com/**），非域名通配。
Git协议配置决定私有模块能否拉取成功
Go 本身不处理 Git 协议，go get 或 go mod download 底层调用的是 git 命令。所以私有模块能不能拉下来，关键看当前环境的 git 配置是否能访问对应仓库。
常见错误现象：go build 报 permission denied (publickey) 或 fatal: could not read Username for 'https://git.example.com' —— 这不是 Go 的问题，是 git 没法认证。
- SSH 场景：确保
ssh -T git@git.example.com能通，且git config --global url."git@git.example.com:".insteadOf "https://git.example.com/"已设置（避免 HTTPS 提交互式账号） - HTTPS + Token 场景：用
git config --global credential.helper store缓存凭据，或在 URL 中嵌入 token：https://token:x-oauth-basic@git.example.com/owner/repo - 自签名证书场景：不能只靠
GOINSECURE，必须让git信任该证书：git config --global http."https://git.example.com/".sslCAInfo /path/to/ca.crt
GOPRIVATE 必须匹配模块路径前缀，不是域名通配符
GOPRIVATE 控制的是 Go 工具链对模块路径的“私有性判断”，它不解析 DNS，也不做域名匹配 —— 它只做字符串前缀匹配。
错误配置：GOPRIVATE=*.example.com 或 GOPRIVATE=example.com → 完全无效，go get git.example.com/repo 仍会走代理并失败。
立即学习“go语言免费学习笔记（深入）”；
- 正确写法：
GOPRIVATE=git.example.com/**（匹配任意深度子路径） - 多域名：
GOPRIVATE=git.example.com/**,gitee.com/my-org/*（注意逗号分隔，无空格） - 路径必须完整：如果模块 import 路径是
git.example.com/group/subgroup/lib，GOPRIVATE=git.example.com/group/*就不够，得写git.example.com/group/subgroup/**或更宽泛的git.example.com/**
git submodule update --init --recursive 不等于 go mod tidy
子模块更新了代码，但 go test 还在跑旧逻辑？大概率是忘了触发 Go 模块系统刷新。
Git 子模块操作只改工作区和 .gitmodules，对 go.mod、go.sum 和模块缓存完全无感。
- 子模块 commit 变更后，必须回到主项目根目录执行
go mod tidy - 子模块自身
go.mod有变更（比如加了新依赖），go mod tidy才会把那些新依赖同步进主项目的go.sum - CI 环境里仅
git clone --recursive不够，还得补一句git submodule sync && git submodule update --init --recursive，否则嵌套子模块可能没拉全
replace 指向子模块时，路径和 go.mod 必须同时满足
想用 replace 把远程模块临时指向本地子模块目录？两个硬条件缺一不可。
常见报错：go: github.com/yourorg/util@v1.2.0 used for replacement but not required 或 no required module provides package。
-
replace右侧路径必须是相对于当前go.mod的有效路径，不能是~/path或绝对路径（除非加/开头） - 子模块目录下必须存在
go.mod，且其module行声明的路径，必须和replace左侧完全一致（逐字匹配） - 如果子模块路径是
./submodules/myutil，但它的go.mod写的是module github.com/otherorg/myutil，那replace github.com/yourorg/myutil => ./submodules/myutil就会失败
最易被忽略的一点：子模块目录若由 git submodule add 创建，它默认没有 go.mod；必须手动进该目录运行 go mod init github.com/yourorg/myutil，否则 replace 无法生效。
