使用 multi-stage 构建 Go 镜像可将体积从 800MB+ 压至 10MB 内，因 Go 静态二进制不依赖工具链；构建阶段用 golang:alpine，运行阶段用 scratch 或 alpine，并设 CGO_ENABLED=0、GOOS=linux 和静态链接标志。

为什么用 multi-stage 构建 Go 镜像

Go 编译产物是静态二进制，不依赖 glibc 或 GOPATH，所以没必要把 go 工具链、源码、测试文件塞进最终镜像。直接用 golang:alpine 构建再拷出二进制，镜像体积能从 800MB+ 压到 10MB 以内。

常见错误是单 stage 构建：用 golang:1.22 作为基础镜像，COPY 源码，RUN go build，再 CMD 启动 —— 这会让整个 Go SDK 和缓存层都留在镜像里，既不安全也不高效。

构建阶段用 golang:1.22-alpine（小体积、带 git 和 ca-certificates）
运行阶段必须用 scratch 或 alpine:latest，不能用 golang 镜像
如果用了 cgo（比如调 net 包 DNS 解析），得显式设 CGO_ENABLED=0，否则 scratch 会报 no such file or directory

如何写一个最小可行的 Dockerfile

以下是最简且健壮的写法，适配绝大多数 CLI 或 HTTP 服务：

FROM golang:1.22-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-extldflags "-static"' -o /usr/local/bin/myapp .

FROM scratch COPY --from=builder /usr/local/bin/myapp /usr/local/bin/myapp EXPOSE 8080 CMD ["/usr/local/bin/myapp"]

关键点：

GOOS=linux 是必须的，本地是 macOS/Windows 时不然编译失败
-a 强制重新编译所有依赖，避免缓存导致的隐性版本不一致
-ldflags '-extldflags "-static"' 确保链接器不引入动态库（尤其在 Alpine 上）
scratch 镜像没有 /bin/sh，所以 CMD 必须用 exec 格式（数组），不能写成 CMD myapp

调试阶段怎么保留构建环境

CI 打包用 multi-stage，但本地开发调试需要进容器看日志、查进程、抓包，这时得临时切回单 stage 或加调试层。

推荐做法：用 ARG BUILD_ENV=prod 控制行为，避免维护两份 Dockerfile：

ARG BUILD_ENV=prod FROM golang:1.22-alpine AS builder # ... 构建逻辑保持不变

FROM alpine:latest AS runtime RUN apk add --no-cache strace tcpdump procps COPY --from=builder /usr/local/bin/myapp /usr/local/bin/myapp

FROM scratch COPY --from=runtime /usr/local/bin/myapp /usr/local/bin/myapp CMD ["/usr/local/bin/myapp"]

FROM runtime AS debug

供 docker run -it --rm myapp:debug /bin/sh 使用

这样：docker build --build-arg

BUILD_ENV=debug -t myapp:debug . 就能拿到带工具的镜像；而默认仍走 scratch。

别在 scratch 里硬加 sh 或 curl —— 安全模型就崩了
alpine 镜像里装调试工具比 debian 轻量得多，strace 和 tcpdump 都有静态编译版
调试镜像不要推到生产 registry，CI 中用 if [ "$BUILD_ENV" = "debug" ]; then exit 1; fi 拦住

Go module 和 vendor 目录怎么处理才不翻车

很多团队为“离线构建”提前 go mod vendor，但 Docker 构建时若没清理干净，容易混用 vendor 和 proxy 缓存，导致构建结果不一致。

如果用 vendor：在 Dockerfile 中 COPY vendor ./vendor，并在 RUN 前加 go env -w GOPROXY=off
如果不用 vendor：确保 go mod download 在 COPY . . 之前，利用 layer 缓存加速；同时设 GO111MODULE=on 防止老项目误启 GOPATH 模式
检查 go.mod 是否含 replace 语句（比如指向本地路径），这种在容器里必然失败，CI 前应跑 go list -m all 验证

真正难的是跨平台交叉编译时的 GOARCH 一致性 —— 比如在 x86_64 构建 ARM64 镜像，要加 --platform linux/arm64 并确认 base 镜像支持该平台，否则 exec format error 不会在构建时报，而是在 docker run 时才暴露。