私有模块拉取失败必须同时启用GO111MODULE=on和GOPRIVATE：前者禁用GOPATH回退确保模块模式一致，后者显式豁免私有域名（如*.your-org.com）跳过代理直连，配合GOPROXY=https://goproxy.cn,direct兜底，三者缺一不可。
私有模块拉取失败：GO111MODULE=on 和 GOPRIVATE 必须同时生效
混合部署（比如开发机是 macOS、测试环境用 Linux 容器、生产跑在 Windows Server 上的 WSL2）下，go mod download 报 module github.com/your-org/internal-api: reading github.com/your-org/internal-api/go.mod: 404 Not Found 是最常见现象。这不是网络不通，而是 Go 模块系统默认把所有非官方域名的模块都扔给代理去查——而你的私有仓库根本不在 GOPROXY 范围内。
必须同时设置：
-
GO111MODULE=on：禁用 GOPATH fallback，否则 Windows 上某些旧脚本或 CI 工具会悄悄退回到 GOPATH 模式，导致go mod行为不一致 -
GOPRIVATE=*.your-org.com,git.internal：告诉 Go “这些域名下的模块一律不走代理，直接 git clone”，注意逗号分隔、不加协议、支持通配符 -
GOPROXY=https://goproxy.cn,direct：direct是兜底项，确保GOPRIVATE命中的域名跳过代理；不能只写direct，否则公共模块无法加速
验证方式：go env GOPRIVATE 输出应含你配置的域名，且 go list -m all 能列出私有模块而非报错。
SSH 认证失败：Git URL 必须统一用 ssh:// 格式，且 .gitconfig 不能依赖全局配置
混合环境里，Windows 开发者用 Git Bash、macOS 用 zsh、Linux 容器里可能压根没配 SSH key——这时 go get git.internal/project/foo 会卡在认证环节，错误信息常是 fatal: could not read Username for 'https://git.internal': No such device or address 或 ssh: connect to host git.internal port 22: Connection refused。
立即学习“go语言免费学习笔记（深入）”；
解决路径很窄，只能靠 URL 格式 + 环境隔离：
- 在
go.mod中声明私有模块时，**必须用ssh://git@git.internal/your-org/project.git这类完整 SSH URL**，不能用https://或省略协议的git.internal/project - 所有构建节点（包括 CI runner、Docker 构建容器）需预置
~/.ssh/id_rsa和~/.ssh/config，其中Host git.internal段要显式指定User git和IdentityFile ~/.ssh/id_rsa - 禁止依赖
git config --global url."ssh://git@git.internal/".insteadOf "https://git.internal/"，因为容器或临时构建环境里该配置常丢失
检查方法：go mod download -x 查看实际执行的 git 命令是否以 ssh:// 开头；若仍失败，进容器手动运行 ssh -T git@git.internal 验证连通性。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
跨平台构建时私有模块缓存污染：GOPATH 不隔离 = 二进制不可复现
混合架构下，开发者在 macOS 上 go build 成功，但 Jenkins 在 Linux 节点上跑同样命令却报 cannot find module github.com/your-org/internal-api——问题往往出在 $GOPATH/pkg/mod 缓存被多用户/多项目共享，且不同系统对符号链接、文件权限处理不一致。
关键动作不是清缓存，而是从源头隔离：
-
GOPATH必须设为项目级独立路径，例如export GOPATH=$(pwd)/.gopath，避免和团队其他项目或系统级 GOPATH 冲突 - Docker 构建时，在
Dockerfile中用ENV GOPATH=/app/.gopath，并确保COPY go.mod go.sum .后立即RUN go mod download，让缓存落在镜像层内 - 禁止在 CI 脚本里用
go clean -modcache，它会清掉整个$GOPATH/pkg/mod，影响并行任务；改用go clean -modcache -i（仅清理当前模块）或直接删.gopath/pkg/mod
副作用：首次构建稍慢，但每次 go build 输出的二进制哈希值稳定，这才是混合部署里真正需要的“可复现性”。
internal 包被误引用：模块边界失效的静默陷阱
大型私有项目拆成多个子模块（如 github.com/your-org/auth、github.com/your-org/billing）后，常出现 import "github.com/your-org/auth/internal/token" 在某个服务里编译通过，但在另一台机器上失败。这不是 Go 版本差异，而是 internal 的路径解析规则在混合环境下被绕过。
根本原因只有两个：
- 某台机器的
go.mod文件里，github.com/your-org/auth被replace成了本地路径（如replace github.com/your-org/auth => ../auth），而本地路径下internal规则不生效 - CI 构建时用了
go mod vendor，但 vendor 目录结构破坏了internal的父目录约束（例如 vendor 里github.com/your-org/auth/internal/token被平铺到顶层）
对策非常具体：
- 禁止在生产构建中使用
replace，开发阶段用go work use替代；上线前运行go list -deps -f '{{if (eq .Name "main")}}{{.ImportPath}}{{end}}' ./... | xargs go list -f '{{.ImportPath}} {{.Imports}}' | grep internal扫描非法导入 -
go mod vendor后，立刻检查vendor/github.com/your-org/auth/internal/token是否存在——如果存在，说明 vendor 破坏了internal边界，必须禁用 vendor 或改用go build -mod=readonly
这个坑不会报错，只会让本该隔离的内部实现意外泄露，等重构时才发现耦合已深。
