从能跑到又小又稳
一句话：多阶段构建 + 纯静态二进制 + 最小运行时镜像，是 Go（及类似编译型语言）服务容器化的最佳路径——构建环境和运行环境彻底分离，最终镜像只装「运行必需品」。
0. 为什么值得做
不做优化的镜像动辄几百 MB（完整
golang/node镜像做运行时），每次推送到仓库、拉取到 k8s 集群都在浪费网络和时间。镜像里带的工具链越多，攻击面越大，漏洞扫描越红。
最终目标形态：镜像里只有你的二进制（+前端静态资源+极少数运行时必需文件），300MB 可以压到 20~30MB。
1. 核心原则
构建环境 ≠ 运行环境：编译需要的工具链（Go、Node、pnpm）永远不进最终镜像。
能静态编译就不动态链接：
CGO_ENABLED=0产出纯静态二进制，运行时不依赖 libc，才有可能用极简底座。运行时底座按需选最小，优先级从轻到重：
scratch（空镜像，零依赖，要求二进制完全静态；需自带 ca-certificates/tzdata）distroless（Google 出品，无 shell、无包管理器，只有精简运行时库）alpine（需要 shell 调试或动态依赖时才用）
一切可配置的东西走环境变量，不烧死在镜像里（监听地址、数据目录、静态资源路径）。
2. 三阶段构建标准模板（前端 + Go 后端）
DOCKERFILE
# ---------- 阶段 1：前端 ----------
FROM node:20-alpine AS frontend-builder
WORKDIR /build
# 先只拷依赖清单，充分利用层缓存
COPY frontend/package.json frontend/pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY frontend/ ./
RUN pnpm build
# ---------- 阶段 2：后端 ----------
FROM golang:1.24-alpine AS server-builder
RUN apk add --no-cache ca-certificates tzdata
WORKDIR /src
COPY backend/ ./
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/app .
# ---------- 阶段 3：运行时 ----------
FROM scratch
COPY --from=server-builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=server-builder /usr/share/zoneinfo /usr/share/zoneinfo
ENV TZ=Asia/Shanghai
COPY --from=server-builder /out/app /app/app
COPY --from=frontend-builder /build/dist /app/frontend
ENTRYPOINT ["/app/app"]
若后端无需调 HTTPS API、不关心日志本地时区，阶段 2 可以不装 ca-certificates/tzdata，运行阶段也可以省掉对应 COPY，镜像更小。
3. 各步骤的「为什么」
实践 | 为什么 |
|---|---|
先 | 依赖不变时命中 Docker 层缓存，改代码不用重装依赖 |
| 严格按 lockfile 安装，构建可复现 |
| 关闭 CGO，二进制不链接系统 libc，scratch 也能跑 |
| 去掉编译机路径信息，构建可复现、不泄露本机目录 |
| 去掉符号表和调试信息，二进制更小 |
| 空镜像零冗余；附带好处：兼容老内核（如 CentOS 7 / 3.10）等无 glibc 约束的环境 |
自带 | scratch 里没有根证书，程序调上游 HTTPS API 会失败 |
自带 | scratch 里没有时区数据，否则日志时间是 UTC |
配置全走 | 同一镜像换环境只需换环境变量，符合十二要素应用 |
4. 常见坑
用了 scratch 后程序 panic：几乎一定是二进制不是纯静态（忘了
CGO_ENABLED=0），或依赖了 DNS/时区/证书等系统文件。调 HTTPS 报证书错误：scratch/distroless 没带
ca-certificates。日志时间不对：没带
tzdata，或没设TZ。想进容器排查却发现没有 shell：scratch/distroless 本来就没有，这是特性不是 bug；需要调试时临时换
alpine底座。镜像推不上去/拉不下来：镜像 tag 要带自己的仓库账号名；minikube 里访问服务要用
minikube ip而非 localhost。
5. 决策清单（动手前过一遍）
语言能否静态编译？能 → scratch；不能（依赖 CGO/动态库）→ distroless 或 alpine。
程序要调外部 HTTPS 吗？要 → 带 ca-certificates。
在意日志本地时间吗？在意 → 带 tzdata + 设 TZ。
有前端吗？有 → 单独一个构建阶段，产物 COPY 进运行阶段，前后端可同容器（简单场景）或分容器（k8s 常规做法）。
最终用
docker images对比体积，用docker run+curl验证功能，再 push。
6. 总结
多阶段构建的本质是把「构建的复杂性」留在构建阶段，把「运行的简单性」留给最终镜像：编译工具链、Node、pnpm 全部止步于 builder 层；运行层只装二进制和静态资源。配合静态编译和 scratch 底座，可以得到体积 20~30MB、攻击面最小、兼容老内核的生产级镜像——这正是后续频繁推拉镜像、滚动发布、k8s 弹性调度所依赖的基础。
本文由AI生成总结
