多阶段构建是必须的，因为单阶段用from golang:alpine会将编译器、调试工具、源码等全打入生产镜像，导致体积超500mb、攻击面大、k8s拒绝调度；而多阶段可分离构建与运行环境，仅传递静态二进制，配合cgo_enabled=0和-ldflags "-s -w"，最终镜像可压缩至12–20mb，符合最小权限与安全合规要求。
直接用 FROM golang:alpine 构建生产镜像，等于把编译器、调试工具、源码全塞进线上容器——体积大、攻击面宽、K8s 拒绝调度。
为什么多阶段构建是必须的
Go 编译产物是静态二进制，理论上只需要运行时环境。但单阶段 Dockerfile（比如只写一个 FROM golang:alpine）会把 go 命令、$GOROOT、C 工具链、甚至测试依赖全打进最终镜像。实测常见体积超 500MB，且含大量非必要可执行文件，不符合最小权限原则。
- 构建阶段用
golang:1.22-slim（比 Alpine 兼容性更稳，无 musl libc 兼容风险） - 运行阶段必须切换到
scratch或gcr.io/distroless/static；若项目依赖 cgo（如 SQLite、OpenSSL），才退回到alpine:latest - 两个阶段之间只传递编译好的二进制，不传任何环境变量、工作目录或构建缓存
CGO_ENABLED=0 和 -ldflags "-s -w" 必须一起用
不加 CGO_ENABLED=0，Go 会默认链接系统 libc，导致在 scratch 或 distroless 镜像里直接 exec format error 或 No such file or directory；不加 -ldflags "-s -w"，二进制会带调试符号和 DWARF 信息，体积多出 30%～50%，且暴露内部结构。
-
CGO_ENABLED=0是静态链接的前提，关闭所有 C 语言交互 -
-s去除符号表，-w去除 DWARF 调试信息 - 若必须启用 cgo（例如调用
net.LookupIP在某些 DNS 配置下需要），则运行镜像不能用scratch，得换alpine:latest并手动apk add --no-cache ca-certificates
运行阶段必须设 USER nonroot:nonroot
Kubernetes 默认禁止以 root 用户运行容器，Docker Desktop 也默认启用 rootless 模式。没这行，docker run 可能成功，但 kubectl apply 会直接报 container has runAsNonRoot and image has non-root user 或被 PodSecurityPolicy 拦截。
- 先在构建阶段创建非 root 用户（如果用
alpine运行镜像）：RUN addgroup -g 1001 -f runtime && adduser -S runtime -u 1001 - 运行阶段加
USER runtime:runtime（或直接用USER nonroot:nonroot，前提是基础镜像已预置该用户） - 别信
USER 1001这种纯数字写法——部分 distroless 镜像不支持 uid-only 用户切换
时区、信号、路径这三个 runtime 陷阱最常导致启动失败
镜像 build 成功 ≠ 容器能跑起来。os.Getwd() 在 scratch 里返回空字符串；time.Now() 在 alpine 里默认是 UTC；而 SIGTERM 不被捕获会导致 docker stop 等 10 秒后强制 kill，来不及 flush 日志或释放连接。
- 用
ENV TZ=Asia/Shanghai+RUN apk add --no-cache tzdata（仅限 alpine）解决时区 - 在 Go 代码里用
signal.Notify监听os.Interrupt和syscall.SIGTERM，做优雅退出 - 避免硬编码路径，用
os.Executable()或传入WORKDIR作为配置根目录，别依赖os.Getwd()
真正难的不是写出能 build 的 Dockerfile，而是让二进制在 scratch 里拿到正确时区、响应 SIGTERM、读到配置文件、连上远端服务——这些都发生在容器启动那一秒，没日志、没 shell、没法 strace，只能靠提前埋点和确定性设计。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
