使用 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"]
关键点：
立即学习“go语言免费学习笔记（深入）”；
-
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 时才暴露。
