go mod download必须放在COPY go.mod之后，因Docker仅通过该文件内容哈希判断缓存；多阶段构建需用AS声明builder别名供COPY--from引用；CGO项目须禁用或配全环境；启用BuildKit是使用--mount=cache的前提。
go mod download 必须放在 COPY go.mod 之后
缓存命中的前提是 Docker 能识别出 go.mod 和 go.sum 没变。如果把 go mod download 放在 COPY . . 后面，哪怕只改了一行业务代码，整个依赖下载层都会失效——因为 COPY . . 把所有文件（包括没变的 go.mod）一起复制进来，Docker 无法单独判断其内容是否一致。
正确顺序是：
-
COPY go.mod go.sum ./—— 只拷贝这两份声明依赖的文件 -
RUN go mod download—— 此时该层完全由go.mod内容哈希决定，只要没改依赖，就复用缓存 -
COPY . .—— 放在依赖下载之后，不影响前面的缓存
多阶段构建中 builder 阶段必须显式声明 AS 别名
如果不写 AS builder，后续 COPY --from=builder 就会报错 invalid from value builder: invalid stage name。这个别名不是可选语法糖，而是多阶段构建中跨阶段引用的必要标识。
常见疏漏点：
立即学习“go语言免费学习笔记（深入）”；
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 忘记在第一阶段
FROM golang:xx AS builder中加AS - 拼错别名，比如写成
AS build却在COPY --from=builder中用错 - 在第二阶段误用
FROM alpine后又试图COPY --from=0（虽然合法，但可读性差，不推荐）
CGO 项目必须禁用 CGO_ENABLED=0 或提供完整构建环境
默认开启 CGO 的 Go 项目在 Alpine 镜像里会编译失败，报错类似 exec: "gcc": executable file not found in $PATH。这不是缓存问题，而是环境缺失导致构建中断，进而让所有缓存失效。
两种解法对应不同场景：
- 纯静态二进制：加
CGO_ENABLED=0，适用于不调 C 库的项目 - 需要调用 C：用
golang:xx（非 Alpine）作为 builder 阶段，保留 gcc 工具链 - 混合方案：用 BuildKit 的
--mount=type=cache挂载/go/pkg/mod，避免重复下载，但依然要保证 builder 阶段有编译能力
docker build 必须启用 BuildKit 才能用高级缓存挂载
像 --mount=type=cache,target=/go/pkg/mod 这种写法，在传统 Docker 构建引擎下直接报错 unknown flag: --mount。它只在 BuildKit 下生效。
启用方式只有两个有效途径：
- 全局开启：
export DOCKER_BUILDKIT=1（Shell 环境变量） - 单次启用：
DOCKER_BUILDKIT=1 docker build . - CI 中需显式设置，GitHub Actions 里要加
env: { DOCKER_BUILDKIT: 1 }
没开 BuildKit 却写了 --mount，构建会直接失败，而不是静默降级——这点容易被忽略，尤其在本地测试通过、CI 失败时。
