根本原因是Docker构建时go mod download不继承宿主机Git凭据和GOPRIVATE配置，导致私有仓库401错误；需在builder阶段显式设置GOPRIVATE、HTTPS+Token认证、GOPROXY与GOPRIVATE成对配置，并确保go mod vendor完整且构建时启用-mod=vendor。
Go mod download 时认证失败：私有仓库返回 401
根本原因是 go mod download 在 Docker 构建阶段不继承宿主机的 Git 凭据或 GOPRIVATE 配置，所有对私有模块的请求都以匿名方式发起，Git 服务（如 GitHub/GitLab）直接拒绝。
常见错误现象：go: git.example.com/internal/pkg: reading https://git.example.com/internal/pkg/@v/list: 401 Unauthorized
- 必须显式告诉 Go 哪些域名属于私有模块——通过构建时注入
GOPRIVATE环境变量，例如GOPRIVATE=git.example.com - 不能只设一次：Docker 构建分阶段，
go mod download通常在 builder 阶段执行，需在该阶段ENV中设置，而非仅在最终镜像里 - 若用 SSH 地址（如
git@git.example.com:org/repo.git），则需挂载 SSH key 并配置~/.ssh/config，但更推荐 HTTPS + token 方式，避免密钥管理复杂度
Docker 构建中 git clone 私有 repo 失败：没有 ssh-agent 或 known_hosts 缺失
当 go.mod 中依赖写成 git@example.com:org/repo.git 这类 SSH 地址时，go build 内部会调用 git clone，而默认的 golang:alpine 或 golang:slim 镜像不含 ssh-agent、不信任目标 host，直接卡住或报错。
典型错误：fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
- 不要在构建中启动 ssh-agent —— 容器生命周期短，agent 启动+add key+eval shell 的链路不可靠
- 改用 HTTPS + Personal Access Token：把
go.mod中的git@example.com:org/repo.git改为https://token:x-oauth-basic@git.example.com/org/repo.git - 务必在
Dockerfile的 builder 阶段用ARG GIT_TOKEN接收 token，并在go mod download前用git config --global url."https://${GIT_TOKEN}:x-oauth-basic@git.example.com/".insteadOf "https://git.example.com/"
多阶段构建中 GOPROXY 和 GOPRIVATE 不一致导致缓存失效
如果 builder 阶段设置了 GOPROXY=https://proxy.golang.org，但没同步设置 GOPRIVATE，Go 仍会尝试走代理查私有模块，结果 403 或超时，进而触发 fallback 到 direct 模式，但此时又没配凭据，整个 go mod download 就会失败或降级为逐个 git clone，拖慢构建且不稳定。
-
GOPROXY和GOPRIVATE必须成对出现，且 builder 阶段和最终运行阶段若都涉及 Go 操作（如热重载），都要保持一致 - 推荐统一设为：
GOPROXY=https://proxy.golang.org,direct+GOPRIVATE=git.example.com，这样匹配到私有域名就跳过 proxy，直连 - 注意通配符：若私有域名是子域名形式（如
pkg.internal.company.com），需写成GOPRIVATE=*.internal.company.com，否则不生效
go mod vendor 后仍拉私有模块：vendor 不完整或未启用
有人以为 go mod vendor 能彻底隔离网络依赖，结果构建时还是去拉私有模块——要么 vendor 没生成成功，要么构建时没加 -mod=vendor 参数，Go 默认仍会解析 go.mod 并联网。
- 检查
vendor/modules.txt是否包含你的私有模块路径；若没有，说明go mod vendor执行时本身就没权限读取它们 - Docker 构建中运行
go mod vendor前，必须已配置好GOPRIVATE和凭据（token / git config），否则 vendor 步骤就失败 - 构建命令必须显式加
-mod=vendor：例如go build -mod=vendor -o app ./cmd/app；只放vendor/目录不加这个参数，等于没用
最易被忽略的一点：私有模块的版本号如果是 pseudo-version（如 v0.0.0-20230101000000-abcdef123456），它依赖的 commit hash 必须真实存在于对应 Git 仓库中；如果该 commit 已被 force push 覆盖或删除，go mod download 或 go mod vendor 都会静默失败或拉错内容。
