go mod download 比 go build 更关键，因其显式预拉取依赖确保构建离线稳定；需配合 GOPROXY 和 GOSUMDB，严格校验 go.sum，并妥善处理私有模块与 vendor 策略。
自建 CI/CD 流水线里，go mod 不是“配好就能跑”，而是最容易在构建阶段突然失败的环节——缓存错乱、版本漂移、私有模块拉不到、go.sum 校验失败，全发生在你点下“运行”之后。
流水线中 go mod download 为什么比 go build 更关键
很多团队直接写 go build 就进流水线，结果在不同节点上时快时慢、偶尔失败。根本原因是：默认行为会边构建边下载依赖，而网络波动、代理配置不一致、模块缓存未命中都会导致超时或版本不一致。
-
go mod download显式触发依赖预拉取，把所有require条目下载到本地$GOPATH/pkg/mod，后续go build完全离线执行 - 必须配合
GOPROXY和GOSUMDB环境变量使用，否则可能 fallback 到直连 GitHub，被限流或拦截 - CI 节点若复用（如 Kubernetes pod 复用），
go mod download前加go clean -modcache反而是陷阱——它清掉缓存却没重置go.sum，容易引发校验失败 - 推荐做法：固定
GOPROXY=https://proxy.golang.org,direct，GOSUMDB=off（仅限内网可信环境）或GOSUMDB=sum.golang.org（公网场景）
go.sum 在流水线中不是摆设，而是构建锁
go.sum 文件记录每个模块的哈希值，是 Go 构建可复现性的最后防线。但流水线里常被忽略两点：它会被 go get 自动更新、且校验失败时默认 panic。
- 任何
go get或go mod tidy操作都可能修改go.sum，如果没提交就进 CI，会导致“本地能过、流水线报 checksum mismatch” - CI 中应严格校验：
go mod verify必须作为独立步骤放在go mod download之后、go build之前；失败即中断，不自动修复 - 若用私有模块（如
git.company.com/internal/pkg），其哈希由 Git commit ID 生成，需确保该 commit 在所有节点都可达（比如通过git submodule update --init或提前 fetch） - 禁止在 CI 脚本里写
go mod tidy -v——它会静默添加/删除依赖，绕过人工审查
私有模块在自建流水线中的三种落地方式
当项目依赖公司内部的 gitlab.company.com/go/utils 这类模块时，go mod 默认无法解析 SSH 路径或 Token 认证地址，必须显式声明。
Alibabacloud Sdk Client Initialization For Golang
下载
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
-
GOPRIVATE=gitlab.company.com/go/*是前提，否则 Go 仍会尝试走GOPROXY，返回 404 - SSH 方式：在 CI runner 上预置 deploy key，并确保
~/.ssh/config配置了对应 Host 别名，go.mod中写成gitlab.company.com/go/utils v0.1.0即可 - HTTPS + Token 方式：用
git config --global url."https://token:x-oauth-basic@gitlab.company.com/".insteadOf "https://gitlab.company.com/"注入凭证，注意 token 权限需含read_repository - 最稳但最重的方式：用
replace指向本地路径（如replace gitlab.company.com/go/utils => ./internal/utils），仅限单体仓库开发期；发布前必须删掉replace并go mod tidy，否则下游无法构建
流水线中 go mod vendor 的真实价值与代价
启用 vendor 目录看似“彻底离线”，但在自建流水线中，它解决的是确定性问题，不是性能问题。
-
go mod vendor本质是把所有依赖源码复制进vendor/，构建时加-mod=vendor参数即可跳过远程操作——这对网络极不稳定的内网 CI 很有用 - 但代价明显：vendor 目录体积大（常达百 MB）、diff 巨大、
go mod vendor本身耗时长（尤其首次），且不会自动清理已删除的依赖 - 真正需要它的场景只有两个：① 审计要求所有源码必须本地化；② CI 节点完全无外网，连
sum.golang.org都不通 - 若只是想提速，优先用
go mod download+ 缓存$GOPATH/pkg/mod目录，比维护 vendor 更轻量可靠
流水线里最常被跳过的动作，是验证 go.mod 和 go.sum 是否被意外修改——它们不像代码那样有语法错误提示，但一旦错位，故障只会在某个特定分支、某次特定构建中幽灵般出现。
