多阶段构建到底省了多少镜像体积
Go 二进制本身静态链接、无依赖，但直接 FROM golang:1.22 构建出来的镜像动辄 900MB+，真正需要的只是几 MB 的可执行文件。多阶段构建的核心价值不在“能不能跑”，而在“交付包里有没有塞进编译器、go.mod 缓存、/tmp 里的中间文件”。
实操建议：
- 基础镜像用
golang:1.22-alpine（编译阶段） +alpine:3.20（运行阶段），比全量golang:1.22少掉约 750MB； - 务必在 builder 阶段用
CGO_ENABLED=0 go build -ldflags="-s -w"：前者禁用 C 依赖避免拉入 libc，后者剥离调试信息和符号表，通常再减 30%–50% 体积； - 别在 builder 阶段
COPY . .整个目录——go mod download后只COPY go.mod go.sum .，再COPY main.go internal/ cmd/等必要源码，避免把node_modules、.git、测试数据一并拖进构建缓存。
为什么 go build -ldflags="-s -w" 必须加
默认 go build 产出的二进制带 DWARF 调试信息和 Go 符号表，对容器运行毫无用处，却占体积大头。不加 -s -w，一个简单 HTTP server 二进制可能 12MB；加上后压到 6–7MB，且启动速度略快（加载符号表有开销）。
注意点：
立即学习“go语言免费学习笔记（深入）”；
-
-s剥离符号表，-w剥离调试信息，两个必须一起用，单独用效果有限； - 加了之后
pprof仍可用，但 stack trace 会丢失函数名和行号（生产环境通常可接受）； - 如果要用
delve调试，构建时就不能加这两个 flag，但调试版绝不该进生产镜像。
Alpine 镜像下 CGO_ENABLED=0 不是可选项
Alpine 用 musl libc，而 Go 默认开启 cgo 会尝试链接 glibc，导致构建失败或运行时 panic：standard_init_linux.go:228: exec user process caused: no such file or directory。这不是路径问题，是动态链接器不匹配。
正确姿势：
- 显式设
ENV CGO_ENABLED=0在 builder 阶段开头，避免因 base image 或 shell 环境残留导致意外启用； - 若项目真依赖 cgo（比如调
net.LookupIP在某些 DNS 配置下 fallback 到 libc），就得换debian:slim基础镜像，体积立刻多出 40MB+，且要手动装ca-certificates； - 验证是否生效：构建后运行
file your-binary，输出含statically linked才算成功。
构建缓存失效比想象中更频繁
Docker 多阶段构建不是“先跑完 stage1 再跑 stage2”，而是按层计算缓存。只要 builder 阶段的 COPY 上层变了（比如改了 go.mod），整个 builder 阶段重来，包括 go mod download ——哪怕依赖没变，也得重拉一遍 module cache。
缓解方法：
- 把
go mod download单独提成一层，在COPY go.mod go.sum .后立即执行，这样只有模块变更才触发下载； - 避免在
RUN go build前做任何非幂等操作（比如RUN date >> build.log）； - 如果用 BuildKit（推荐），开启
cache-to推送到 registry，跨 CI job 复用 module cache，但要注意go.sum校验严格，小版本升级也会让缓存失效。
最常被忽略的是：go build 输出路径默认在当前目录，如果没指定 -o，二进制名就是 main，容易和别的项目冲突；放进 COPY --from=builder 时写错名字就白忙活。直接写死 -o /app/server，复制时也明确写 COPY --from=builder /app/server .，少一层猜测。
