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。这个别名不是可选语法糖，而是多阶段构建中跨阶段引用的必要标识。
常见疏漏点：
- 忘记在第一阶段
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。这不是缓存问题，而是环境缺失导致构建中断，进而让所有缓存失效。
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
两种解法对应不同场景：
- 纯静态二进制：加
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 失败时。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
