不推荐在镜像打包中使用go mod vendor，因其导致构建缓存失效、镜像体积膨胀、无法复用Go module cache，且校验逻辑未绕过、拷贝开销大；现代CI/CD应依赖模块缓存而非vendor。
go mod vendor 为什么在镜像打包里不推荐用
因为 go mod vendor 会把所有依赖源码复制进项目目录，导致构建缓存极易失效、镜像体积膨胀、且无法利用 Go 的 module cache 机制做层复用。Docker 构建时一旦 vendor/ 目录有任意变更（哪怕只是时间戳），整个依赖层就全重建——这比直接用 go mod download + 缓存挂载慢得多。
更关键的是：vendor 模式下 go build 仍会读取 go.mod 和 go.sum，校验逻辑没绕过，反而多了一层文件拷贝开销；而现代 CI/CD 和多阶段构建都依赖模块缓存的可复用性，vendor 是退化方案。
- 不要在 Dockerfile 中执行
go mod vendor，尤其别COPY vendor/ . - 若必须离线构建，请用
go mod download预拉取缓存并打包$GOPATH/pkg/mod/cache，而非 vendor - 私有模块场景下，
vendor也无法解决认证问题，不如配好GOPRIVATE+GOPROXY
Dockerfile 中 go mod download 的位置和参数陷阱
go mod download 必须紧接在 COPY go.mod go.sum . 之后，且不能带 -u 或 @latest。否则它会触发远程查询，破坏离线或受限网络环境下的构建稳定性。
常见错误包括：把 COPY . . 放在前面，导致每次代码变更都让依赖层失效；或者漏掉 go.sum，使校验失败；还有人写成 go get -d ./...，这会绕过 go.sum 校验，引入不可控版本。
立即学习“go语言免费学习笔记（深入）”；
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 正确顺序：
COPY go.mod go.sum .→RUN go mod download→COPY . .→RUN go build - 禁止使用
go mod download -u，它会升级依赖，破坏可重现性 - 确保
go.sum已提交，且内容与go.mod匹配，否则go mod download直接报错verifying github.com/xxx@v1.2.3: checksum mismatch
CGO_ENABLED=0 不是万能开关
设 CGO_ENABLED=0 确实能跳过 C 依赖、生成纯静态二进制，但代价是失去对 net 库 DNS 解析（回退到纯 Go 实现）、无法调用 OpenSSL、SQLite 等原生库。很多企业项目（比如连 Oracle、MySQL、OpenSSL 加密）根本不能关。
如果必须支持 CGO，镜像里就得装 gcc、musl-dev（Alpine）或 build-essential（Debian），且最终运行镜像要带对应 so 文件或用 ldd 检查缺失依赖——distroless 就不再适用了。
- 确认项目是否真不需要 CGO：
grep -r "import.*C" ./，有结果就不能简单设CGO_ENABLED=0 - Alpine 下启用 CGO 要加
RUN apk add --no-cache git gcc musl-dev - 构建后用
ldd /bin/server检查动态链接，避免运行时报not found
多阶段构建中缓存挂载的实际效果
Docker BuildKit 的 --mount=type=cache 能把 /go/pkg/mod 持久化跨构建复用，实测可将依赖拉取从分钟级压到秒级。但它只在 BuildKit 启用时生效（DOCKER_BUILDKIT=1），且默认 cache ID 是路径，不同项目会冲突。
容易被忽略的是：cache 挂载不自动处理 go.sum 变更。如果 go.sum 更新了，BuildKit 不会自动清 cache，可能导致校验失败；必须配合 --mount=type=bind,source=go.sum,target=go.sum 强制触发重下载。
- 启用方式：
export DOCKER_BUILDKIT=1，然后docker build . - 推荐写法：
RUN --mount=type=cache,target=/go/pkg/mod --mount=type=bind,source=go.sum,target=go.sum go mod download - CI 环境中注意 runner 是否清理了 cache 目录，否则可能复用脏缓存
go.sum 哈希，或者某次 go mod tidy 没提交完整，等镜像跑起来才报 checksum mismatch——这种问题没法靠语法检查提前发现，只能靠每次提交前跑一遍 go mod download -json 对照依赖清单。 
