根本原因是CI环境每次新建容器或runner导致$GOMODCACHE无法复用，解决办法是：Dockerfile中将go mod download单独成层并置于go.mod之后、源码COPY之前；CI脚本中用actions/cache缓存$(go env GOMODCACHE)，key包含Go版本和go.sum哈希；构建时加-mod=readonly强制只用已缓存模块。
CI 构建时 go mod download 被反复执行，拖慢整体耗时
根本原因是 Docker 构建或 CI job 每次都从零开始，go mod download 重新拉取全部依赖，无法复用本地缓存。Go 默认把模块缓存在 $GOMODCACHE（通常是 $GOPATH/pkg/mod），但 CI 环境每次都是干净容器或新 runner。
解决办法不是靠“猜”缓存路径，而是显式控制下载阶段：
- 在
Dockerfile中，把go mod download单独作为一层，放在COPY go.mod go.sum .之后、COPY . .之前 —— 这样只要go.mod/go.sum不变，这层就命中缓存 - CI 脚本里（如 GitHub Actions）启用
actions/cache缓存$(go env GOMODCACHE)，注意 key 要包含 Go 版本和go.sum的 hash（避免不同 commit 用错缓存） - 禁用
go build自动下载：加-mod=readonly，强制它只用已下载/缓存的模块，出错立刻失败，不掩盖网络抖动问题
多子包并行构建时依赖解析冲突或版本不一致
大型单体项目常拆成多个 cmd/xxx、pkg/yyy 子目录，但共用一个 go.mod。CI 并行跑 go build ./cmd/a 和 go build ./cmd/b 时，看似独立，实则共享同一模块根，go mod 状态可能被并发读写干扰（尤其在旧版 Go 中）。
稳妥做法是避免“并发触发模块操作”，只让构建本身并行：
立即学习“go语言免费学习笔记（深入）”；
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 所有构建命令前统一加
GOFLAGS="-mod=readonly"，禁止任何自动修改行为 - CI 中先串行执行一次
go mod verify，确认go.sum完整且未被篡改；再并行执行各go build目标 - 不要在 Makefile 或脚本里对同一项目并发调用
go mod tidy或go get—— 这类操作必须串行且仅在显式更新依赖时发生
私有模块在 CI 中 resolve 失败，报错 module not found 或 checksum mismatch
典型现象是本地能 go build，CI 却卡在 go mod download，错误类似 failed to load module requirements 或 invalid version: git ls-remote。这不是网络问题，而是认证或代理策略不一致。
关键配置必须显式声明，不能依赖开发机环境：
- 设
GOPRIVATE=git.company.com/*（替换成你的真实域名），否则 Go 会试图走GOPROXY下载私有模块，必然失败 - CI 中用 SSH Agent 或 Personal Access Token 配置 Git 认证：GitHub/GitLab Runner 支持 inject token，Docker 构建则需挂载
~/.ssh或用git config --global url."git@github.com:".insteadOf "https://github.com/" -
go.sum必须提交，且每个私有模块的 checksum 条目要完整 ——go mod verify会校验它，缺失条目直接失败
构建产物体积大、启动慢，怀疑间接依赖污染
运行 go list -m all | wc -l 发现依赖模块数超 200+，但业务代码其实只用其中一小部分。冗余依赖不仅增大二进制体积，还延长 go mod download 时间，并增加安全扫描负担。
精简不是靠删 require 行，而是靠验证实际使用：
- 用
go mod graph | grep -v 'golang.org' | sort | uniq -c | sort -nr | head -20查高频间接依赖，再结合go list -f '{{.Deps}}' ./... | grep xxx确认是否真被引用 - 对非必要工具类依赖（如
github.com/spf13/cobra只用于cmd/），考虑移入对应子目录的独立go.mod（需配合replace开发，发布前清理） - 构建时加
-ldflags="-s -w"剥离调试信息，对体积影响显著；真正的大头往往是日志、模板、嵌入文件 —— 这些不属于模块管理范畴，别混淆
go.mod 更新后，CI 是否同步了 go.sum？私有模块的 GOPRIVATE 是否漏配？go build -mod=readonly 是不是只加在 build 命令里，却忘了 test 或 vet？这些细节一旦错位，就会变成“随机失败”。 
