根本原因是COPY指令引入的文件内容变化触发后续所有层重建；必须单独复制go.mod和go.sum、用.dockerignore排除无关文件、严格按依赖声明→下载→源码编译三步组织Dockerfile。
go mod download 层缓存失效，根本原因不是命令本身，而是 COPY 指令引入的文件内容变化触发了后续所有层重建。
为什么 go.mod 和 go.sum 复制后仍缓存失效
常见错误是把 COPY . . 放在 RUN go mod download 之前，或没隔离依赖文件与源码。Docker 缓存比对的是整个构建上下文哈希值——哪怕 .git、README.md 或 IDE 配置文件被一并 COPY 进来，只要它们有变动，COPY . . 这一层就必然失效，导致其后的 RUN go mod download 无法复用缓存。
-
go.mod和go.sum必须单独、**且仅**被COPY一次，路径和顺序不能混入其他文件 - 不要用
COPY . .代替细粒度复制；它等于把整个目录树哈希值作为缓存 key -
.dockerignore必须存在且包含node_modules、.git、*.log等无关项，否则这些文件会悄悄污染 COPY 层
正确组织 Dockerfile 的三层顺序
必须严格按「依赖声明 → 依赖下载 → 源码编译」分三步，且中间不能插入任何可能变动的操作：
- 第一层：
COPY go.mod go.sum ./—— 只这两文件，路径结尾的./不能写成/app/（路径变更即新层） - 第二层：
RUN go mod download—— 此层缓存 key 完全由前一层文件内容决定 - 第三层：
COPY . .或更优的COPY main.go internal/ cmd/ ./—— 源码可变，放最后，不影响前两层
示例片段：
FROM golang:1.21-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY main.go internal/ cmd/ ./ # 不 copy testdata/ 或 docs/ RUN CGO_ENABLED=0 GOOS=linux go build -o server .
多阶段构建中 --from=builder 的缓存陷阱
即使 builder 阶段缓存命中，若 runtime 阶段的 COPY --from=builder 指令目标路径或文件名有微小差异（比如从 /server 改成 /app/server），Docker 会认为这是全新指令，跳过缓存复用。
- 确保
COPY --from=builder的源路径与 builder 阶段中RUN go build -o输出路径**完全一致** - 避免在 builder 阶段使用动态路径变量（如
$PWD），全部写死为绝对路径 - 如果 runtime 阶段用了
ADD而非COPY，解压行为会破坏哈希一致性，一律用COPY
CI/CD 中需要强制刷新依赖时的最小扰动方式
不推荐无差别用 --no-cache，它会让整个构建退化为线性重跑。真正要刷新依赖时，只需让 go.mod 层失效即可：
- 在 CI 脚本中注入时间戳到注释行：
echo "// CACHE_BUST $(date +%s)" >> go.mod，再提交 —— 注释不参与构建但改变文件哈希 - 或改用构建参数：在 Dockerfile 开头加
ARG GO_MOD_HASH，然后COPY go.mod.$GO_MOD_HASH go.mod，CI 中传--build-arg GO_MOD_HASH=$(sha256sum go.mod | cut -d' ' -f1) - 注意：修改
go.sum内容（如升级依赖）本身就会自然触发缓存更新，无需额外操作
最易被忽略的一点：go mod vendor 生成的 vendor/ 目录如果被 COPY 进镜像，它的存在与否、内部文件时间戳、甚至 git 状态（如 untracked 文件）都会影响缓存稳定性——除非你明确需要 vendor，否则别碰它。
