Golang容器镜像优化核心是多阶段构建+静态编译：第一阶段用golang镜像编译，第二阶段仅拷贝CGO_ENABLED=0生成的静态二进制到scratch或distroless镜像，并合并RUN指令、清理中间文件、启用BuildKit提升缓存复用。
直接用 golang:1.22 这类官方镜像跑开发或构建，不是不行，但很快会遇到体积大、启动慢、缓存失效频繁、信号处理异常、安全策略不满足等问题。真正的优化不是“换一个更小的镜像”，而是从构建逻辑、运行约束和环境分层三方面系统调整。
多阶段构建必须分清 builder 和 runtime 两个角色
很多人写 Dockerfile 时把编译和运行混在一个 stage，或者只用一个 FROM golang 镜像直接 CMD ["go", "run"]，这会导致最终镜像带入整个 Go 工具链（go 命令、GOPATH、测试工具、C 编译器等），体积轻松破 900MB。
正确做法是显式拆成至少两个 stage：
- builder 阶段用
golang:1.22或golang:1.22-alpine，只做go mod download和go build - runtime 阶段必须切换基础镜像，推荐
gcr.io/distroless/static-debian12（非 root、无 shell、证书齐全）或alpine:latest（需手动apk add ca-certificates） - 务必用
COPY --from=builder复制二进制，而不是COPY .再 build - 避免在 runtime 阶段执行任何
RUN指令（比如apk add），否则破坏 distroless 的精简性
CGO_ENABLED=0 和 -ldflags="-s -w" 不是可选项
默认开启 CGO 会让 Go 二进制动态链接 musl/glibc，导致在 scratch 或 distroless 镜像中直接报 no such file or directory 错误；而保留调试符号和 DWARF 信息，会让二进制体积膨胀 30%~50%，还可能泄露路径、变量名等敏感信息。
立即学习“go语言免费学习笔记（深入）”；
构建命令必须固定为：
CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" -o main ./cmd/api
注意几点：
-
GOOS=linux是必须的，即使你在 macOS 或 Windows 上构建，容器运行环境是 Linux -
-a强制重新编译所有依赖，配合CGO_ENABLED=0确保完全静态链接 - 不要加
-mod=vendor除非你真有 vendor 目录且想绕过go.mod—— 它会干扰缓存复用
Dockerfile 指令顺序决定缓存是否生效
改一行业务代码就触发全部依赖重下载，这是最常见却最容易被忽略的低效点。Docker 构建缓存是按指令逐层命中，一旦某层失效，其后所有层都会重建。
关键顺序必须是：
- 先
COPY go.mod go.sum .→ 单独RUN go mod download - 再
COPY . .→ 最后RUN go build - 中间不能插入其他
COPY或RUN，比如把.dockerignore忘了，导致node_modules或vendor被复制进来，缓存立刻失效 - 如果项目含 cgo 依赖（如
sqlite3），go.mod变更频率低，但CGO_ENABLED=1时仍建议把CGO_*环境变量提前写进FROM行，避免 RUN 层污染缓存
容器内信号处理和进程模型必须由 Go 自己接管
很多 Golang 容器在 Kubernetes 里被 kill -15 后僵死或 panic，根本原因是没正确监听 os.Interrupt 和 syscall.SIGTERM；更隐蔽的问题是用 CMD ["sh", "-c", "./main"] 启动，导致信号无法透传给 Go 进程。
运行阶段必须满足：
-
ENTRYPOINT ["./main"]或CMD ["./main"]，禁止包裹 shell - Go 代码中显式注册信号处理：
signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM) - HTTP server 关闭前要调用
srv.Shutdown()，DB 连接池要Close() - 不要在容器里起 supervisord、tini 或自定义 init，Go 程序自己就是 PID 1
真正难的不是写出能跑的 Dockerfile，而是让每一层构建都可预期、每个信号都能被捕获、每次部署都不因镜像差异引发线上行为偏移——这些细节在压测和滚动更新时才会集中暴露。
