别再用单阶段构建了:从 1.2GB 到 8MB,多阶段构建如何把镜像“榨干”

引言

先说一个我亲身踩过的坑。

三年前我在一家做 SaaS 的公司负责一个 Go 写的边缘网关服务。本地 go build 出来的二进制只有 15MB,但我们的 CI 流水线打出来的镜像有 1.2GB。当时没人觉得有问题——反正 K8s 拉得下来就行。直到有一天线上做灰度发布,节点磁盘被镜像层撑爆,ImagePullBackOff 报了一屏幕,运维半夜打电话过来。

我们排查后发现镜像里塞了:完整 Debian 基础镜像、Go 1.19 SDK(约 800MB)、git、gcc、make、node_modules、一堆 /root/.cache/go-build 的编译缓存,还有测试用的 fixture 文件。生产环境真正需要的只有一个 15MB 的静态二进制。

这不是个例。我见过太多团队的 Dockerfile 停留在“能跑就行”的阶段。镜像体积的膨胀本质上是一个熵增问题——每次“临时加个依赖方便调试”,都会沉淀到最终镜像里,没人敢删,因为不知道谁在用。

这篇文章我想把这件事讲透:多阶段构建到底在 Docker 引擎层面发生了什么?为什么它能同时解决“体积”和“安全”两个问题?以及最小化镜像真正的边界在哪里——因为很多人对“最小化”有误解,以为越小越好,其实不然。


核心概念:从“打包整个后厨”到“只端出这道菜”

生活化类比

想象你开一家餐厅,顾客点了一份宫保鸡丁。

  • 单阶段构建就像把整个厨房连同灶台、冰箱、食材仓库、厨师本人都塞进餐盒一起送到顾客桌上。顾客只想要那盘菜,你却让他自己从一堆东西里翻。
  • 多阶段构建则是:在后厨(builder 阶段)把所有食材、锅具、调料都用上,做出成品;然后只把装盘的那份菜(runtime 阶段)端出去。后厨留在店里,不跟餐走。

这里的关键洞察是:“构建时需要的东西”和“运行时需要的东西”是两个几乎不相交的集合。编译器、SDK、包管理器、源码——这些在构建完成后就完成了历史使命,没有任何理由进入生产镜像。

技术定义

Docker 的镜像由一组只读层(layer)叠加而成,每个 RUN/COPY/ADD 指令产生一层。镜像体积 ≈ 所有层大小之和(去重后)。容器启动时,这些层通过 UnionFS(overlay2)挂载为一个统一的根文件系统。

多阶段构建利用 Dockerfile 中的多个 FROM 指令,每个 FROM 开启一个新的构建阶段。默认情况下,只有最后一个阶段的产物会进入最终镜像,前面阶段的所有中间层被丢弃(除非用 COPY --from 显式引用)。

graph TD subgraph Builder["Stage 1: builder (被丢弃)"] A1[FROM golang:1.22] --> A2[COPY 源码] A2 --> A3[go mod download] A3 --> A4[go build -o /app/server] end subgraph Runtime["Stage 2: runtime (最终镜像)"] B1[FROM scratch / distroless] --> B2["COPY --from=builder /app/server"] B2 --> B3[ENTRYPOINT /app/server] end A4 -.只传递二进制.-> B2 style A1 fill:#fdd style A2 fill:#fdd style A3 fill:#fdd style A4 fill:#fdd style B1 fill:#dfd style B2 fill:#dfd style B3 fill:#dfd

上图的关键在于那条虚线:跨阶段只传递了最终产物。builder 阶段那 800MB 的 Go SDK、编译缓存,全部留在了构建机的临时空间里,构建结束即销毁。

为什么这能同时解决安全问题

镜像里的每一层都是一个攻击面。gcc、git、curl、bash 这些工具在生产容器里毫无用处,但如果镜像被攻破(比如应用层 RCE),攻击者就能用它们下载 payload、编译提权工具、横向移动。

最小化镜像的本质是缩小攻击面:镜像里没有的东西,攻击者就用不了。这是“不可变基础设施”理念在镜像层面的延伸——不是靠运行时防护,而是靠根本没装。


源码级深度分析:COPY --from 在引擎里到底做了什么

很多人把多阶段构建当成一个“语法糖”,其实它触及了 Docker 构建器(BuildKit)的核心数据模型。我们拆开看。

Dockerfile 的 AST 与阶段图

以 BuildKit 的源码为参照(frontend/dockerfile/dockerfile2llb/convert.go),Dockerfile 被解析后,每个 FROM 会生成一个 dispatchState,它持有该阶段的所有指令、依赖关系和基础镜像引用。伪代码大致如下:

// 简化自 BuildKit 的 dispatchState 概念
type dispatchState struct {
    stage      instructions.Stage // 阶段名,如 "builder" / "runtime"
    base       *llb.Image         // 基础镜像的 LLB 引用
    deps       []*dispatchState   // 依赖的前序阶段(被 COPY --from 引用的)
    commands   []*command         // 该阶段内的指令序列
    image      *llb.State         // 该阶段最终的文件系统状态
}

// 关键:只有被"标记为输出"的阶段才会进入最终镜像
// 其余阶段仅作为依赖参与构建,构建完成后其 LLB State 被 GC

这里最核心的概念是 LLB(Low-Level Build)——BuildKit 的中间表示,本质上是一个 DAG(有向无环图)。每个 FROM 是图中的一个节点,COPY --from=builder 会在图中创建一条从 builder 节点指向 runtime 节点的边,但只取 builder 节点的某个文件路径,而不是整个文件系统。

COPY --from 的语义:文件级引用,而非层拷贝

这是最容易被误解的地方。COPY --from=builder /app/server /app/server 并不是把 builder 的层复制过来,而是:

  1. 在构建时,BuildKit 从 builder 阶段的最终文件系统状态中,读取指定路径的文件;
  2. 把这个文件内容作为新的一层写入 runtime 阶段;
  3. runtime 阶段完全不继承 builder 的任何层。

我们可以用一个实验验证。下面这个 Dockerfile 故意制造一个“体积陷阱”:

# 阶段1:builder,故意塞满无用文件
FROM alpine:3.19 AS builder
RUN dd if=/dev/zero of=/waste.bin bs=1M count=100   # 制造 100MB 垃圾
RUN echo "hello" > /app-binary

# 阶段2:runtime
FROM alpine:3.19 AS runtime
COPY --from=builder /app-binary /app-binary
CMD ["cat", "/app-binary"]

构建后 docker images 显示 runtime 镜像只比 alpine:3.19 大了几 KB(/app-binary 的内容),那 100MB 的 waste.bin 完全不存在于最终镜像。这就是文件级引用的威力。

为什么“单阶段 + 末尾 rm”不行

一个常见的错误直觉是:“我在同一阶段里 RUN rm -rf /tmp/cache 不就行了?” 不行。因为 Docker 的层是不可变的(immutable)。rm 只会在新的一层里创建一个“删除标记(whiteout)”,被删文件所在的旧层依然存在,镜像总大小不会减少。

# 反例:这样镜像依然很大
FROM golang:1.22
COPY . /src
WORKDIR /src
RUN go build -o /app/server . && rm -rf /root/.cache /src   # 删除无效!

/root/.cache 和 /src 的内容仍然躺在下面的层里,rm 只是加了个 whiteout。只有跨阶段才能彻底丢弃层。这是多阶段构建不可替代的根本原因。

最小化镜像的边界:scratch 不是银弹

FROM scratch 是最极致的方案——一个完全空的根文件系统,镜像里只有你的二进制。但它有代价:

  • 没有 CA 证书:任何 HTTPS 调用都会失败(x509: certificate signed by unknown authority);
  • 没有时区数据:time.LoadLocation("Asia/Shanghai") 报错;
  • 没有 /etc/passwd:USER 指令、某些需要解析用户的库会出错;
  • 没有动态链接器:如果你的二进制不是静态编译的(比如用了 cgo),直接 exec format error。

所以“最小化”的正确姿势不是无脑 scratch,而是在满足运行时依赖的前提下尽可能小。gcr.io/distroless/static 这类基础镜像就是为此而生:它包含 CA 证书、/etc/passwd、时区数据,但没有 shell、没有包管理器,体积约 2MB。


实战代码

下面三个示例覆盖三种典型场景:Go 静态二进制、Node.js 前端、Python 应用。每个都带详细注释,可直接运行。

示例 1:Go 服务 → distroless(1.2GB → 8MB)

# syntax=docker/dockerfile:1.7

# ============ Stage 1: builder ============
FROM golang:1.22-alpine AS builder

# 安装构建期依赖(只在 builder 阶段存在)
RUN apk add --no-cache git ca-certificates tzdata

WORKDIR /src

# 先只拷贝依赖清单,利用层缓存:
# go.mod/go.sum 不变时,go mod download 这层可复用
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

# 再拷贝源码并编译
COPY . .

# CGO_ENABLED=0 生成静态二进制,才能在 scratch/distroless 里跑
# -ldflags="-s -w" 去掉符号表和调试信息,通常能减 20%~30%
# -trimpath 去掉构建路径,提升可复现性
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux go build \
        -trimpath \
        -ldflags="-s -w -X main.version=$(date +%Y%m%d)" \
        -o /out/server ./cmd/server

# ============ Stage 2: runtime ============
# distroless/static 自带 CA 证书、/etc/passwd、时区,约 2MB
FROM gcr.io/distroless/static-debian12:nonroot

# 从 builder 拷贝二进制(文件级引用,只传这一个文件)
COPY --from=builder /out/server /server

# nonroot 镜像默认 UID=65532,避免以 root 运行
USER nonroot:nonroot

EXPOSE 8080
ENTRYPOINT ["/server"]

要点解析:

  • --mount=type=cache 是 BuildKit 的缓存挂载,它不会进入镜像层,只加速重复构建。这是比 COPY go.mod 更现代的缓存策略,两者可以叠加使用。
  • -ldflags="-s -w" 中的 -s 去掉符号表、-w 去掉 DWARF 调试信息。代价是 panic 时堆栈的行号信息会弱化,生产排障时如果依赖 pprof 符号,需要权衡。
  • distroless/static:nonroot 而非 scratch,是为了稳妥拿到 CA 证书和时区。

示例 2:Node.js 前端 → Nginx(多阶段 + 依赖分层)

# syntax=docker/dockerfile:1.7

# ============ Stage 1: deps ============
# 单独提取依赖安装阶段,最大化缓存命中
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
# ci 而非 install:严格按 lockfile 安装,保证可复现
RUN --mount=type=cache,target=/root/.npm \
    npm ci

# ============ Stage 2: builder ============
FROM node:20-alpine AS builder
WORKDIR /app
# 复用 deps 阶段的 node_modules(跨阶段引用目录)
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build   # 产物输出到 /app/dist

# ============ Stage 3: runtime ============
# 用 nginx 提供静态资源,而不是用 node 跑静态服务
FROM nginx:1.27-alpine AS runtime

# 精简 nginx 默认配置,只保留 SPA 所需
COPY nginx.conf /etc/nginx/conf.d/default.conf
# 只拷贝构建产物
COPY --from=builder /app/dist /usr/share/nginx/html

# 以非 root 运行:nginx 镜像需改权限
RUN chown -R nginx:nginx /usr/share/nginx/html /var/cache/nginx \
    && sed -i 's/user  nginx;/user  nginx;/' /etc/nginx/nginx.conf

USER nginx
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

配套的 nginx.conf(SPA 路由回退 + gzip):

server {
    listen 8080;
    root /usr/share/nginx/html;
    index index.html;

    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;

    # SPA:所有未匹配路径回退到 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源长缓存(文件名带 hash 时安全)
    location ~* \.(js|css|png|jpg|svg|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

要点解析:

  • 拆出独立的 deps 阶段是 Node 项目的最佳实践:package-lock.json 不变时 npm ci 层完全命中缓存,改业务代码不会触发重装。
  • 用 nginx 而非 node 提供静态资源,是因为 Nginx 的静态文件性能、连接复用、gzip 都远优于 Node 的 http-server,且镜像更小(Nginx 约 40MB vs Node 约 130MB)。

示例 3:Python 应用 → 精简运行时(处理 venv 与编译依赖)

Python 的难点在于:很多包(如 psycopg2、numpy)需要编译工具链,但运行时只需要编译好的 .so。

# syntax=docker/dockerfile:1.7

# ============ Stage 1: builder ============
FROM python:3.12-slim AS builder

# 编译期依赖:gcc、头文件等,只在 builder 存在
RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 用 venv 隔离,便于整体拷贝到 runtime
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
# 关键:--no-compile 减少 .pyc,先装到 venv 里
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --no-cache-dir -r requirements.txt

# ============ Stage 2: runtime ============
FROM python:3.12-slim AS runtime

# 运行时只需 libpq 运行时库(不含 -dev 头文件)
RUN apt-get update && apt-get install -y --no-install-recommends \
        libpq5 \
    && rm -rf /var/lib/apt/lists/*

# 整体拷贝 venv(包含编译好的 .so 和纯 Python 包)
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH" \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# 创建非 root 用户
RUN useradd -r -u 1001 -s /sbin/nologin appuser
WORKDIR /app
COPY --chown=appuser:appuser . .
USER appuser

EXPOSE 8000
CMD ["gunicorn", "app.main:app", "-c", "gunicorn.conf.py"]

要点解析:

  • venv 整体拷贝是 Python 多阶段的关键技巧:venv 里的 .so 链接的是 builder 阶段的 Python,只要两个阶段基础镜像版本一致(都用 3.12-slim),路径就兼容。
  • builder 装 libpq-dev(头文件),runtime 只装 libpq5(运行时库),这是“编译依赖 vs 运行时依赖”分离的典型。
  • 风险提示:venv 跨阶段拷贝依赖“两阶段 Python 版本与路径完全一致”,一旦版本漂移会静默失败。生产上建议用 python:3.12.4-slim 这种精确到 patch 的 tag。

方案对比:多阶段构建 vs 其他“瘦身”手段

方案 原理 体积收益 安全收益 适用场景 主要坑
多阶段构建 跨阶段只传产物 ★★★★★ ★★★★ 几乎所有编译型语言 需处理 CA/时区/用户
scratch/distroless 极简基础镜像 ★★★★★ ★★★★★ 静态二进制 动态链接、无 shell 调试
docker-slim 静态分析+运行时探测 ★★★ ★★★ 遗留镜像改造 探测不全导致缺文件
Alpine 替换 用 musl 基础镜像 ★★★ ★★ 简单应用 musl 与 glibc 不兼容
层合并/--squash 压掉中间层 ★★ ★ 历史包袱 破坏层缓存,不推荐

几个关键权衡

Alpine 的 musl 陷阱:很多团队把 debian 换成 alpine 就以为万事大吉,结果 Python 的 numpy、psycopg2 预编译 wheel 是 glibc 的,Alpine 上装不了,被迫现场编译,构建时间暴涨且镜像反而变大。Alpine 适合纯静态/Go/Rust,不适合重度依赖预编译二进制包的场景。

docker-slim 的定位:它通过“跑一遍应用、观察实际访问了哪些文件”来裁剪镜像,适合改造存量镜像。但它是黑盒探测,覆盖不到的代码路径(比如定时任务、异常分支)用到的文件会被误删,生产风险较高。我倾向于把它当“事后审计工具”,而不是主要手段。

distroless vs scratch:distroless 是“有边界的最小化”——它替你预置了 CA、时区、passwd 这些“几乎人人需要”的东西;scratch 是“绝对最小化”——一切自备。99% 的团队应该选 distroless,scratch 只留给对体积有极致要求(如边缘设备)且能自管依赖的场景。


最佳实践与避坑指南

1. 缓存策略:把“变化频率”从低到高排列指令

这是层缓存的黄金法则。COPY 源码永远放最后,依赖清单放前面。

COPY go.mod go.sum ./     # 变化少 → 缓存命中高
RUN go mod download
COPY . .                  # 变化多 → 放最后
RUN go build ...

2. 用 .dockerignore 堵住上下文泄漏

COPY . . 会把 .git、node_modules、测试数据、.env 全塞进构建上下文,不仅慢,还可能把密钥打进镜像。必备的 .dockerignore:

.git
.gitignore
node_modules
dist
*.log
.env*
__pycache__
.venv
*.md
.github

3. 固定基础镜像 tag,禁止 latest

FROM node:latest 意味着你的构建不可复现——今天和明天打出来的镜像可能不同。生产用精确 tag + digest:

FROM node:20.11.1-alpine3.19@sha256:xxxxx

4. 永远以非 root 运行

USER 1001:1001

K8s 的 securityContext.runAsNonRoot: true 会在 Pod 层面兜底,但镜像层面就该做对。distroless 的 nonroot tag 已经帮你搞定。

5. 常见坑清单

  • COPY --from 引用了不存在的路径:构建时静默失败或报错,务必在 builder 阶段 ls 确认产物路径。
  • 动态链接的二进制放进 scratch:exec format error 或 no such file or directory(其实是缺 ld-linux)。用 ldd ./binary 检查。
  • HTTPS 调用失败:漏拷 CA 证书。COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ 或直接用 distroless。
  • 时区 Asia/Shanghai 报错:漏了 tzdata。COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo。
  • --mount=type=cache 在旧版 Docker 不可用:需要 BuildKit(Docker 18.09+ 默认开启),CI 里确认 DOCKER_BUILDKIT=1。
  • 跨阶段 venv 拷贝版本漂移:Python/Node 的 venv、node_modules 跨阶段拷贝时,两阶段基础镜像版本必须完全一致。

6. 把镜像体积纳入 CI 门禁

光靠自觉是不够的。在 CI 里加一道检查,超过阈值就 fail:

# GitHub Actions 片段
- name: Check image size
  run: |
    SIZE=$(docker image inspect myapp:ci --format='{{.Size}}')
    LIMIT=$((200 * 1024 * 1024))   # 200MB
    echo "Image size: $((SIZE / 1024 / 1024))MB"
    if [ "$SIZE" -gt "$LIMIT" ]; then
      echo "::error::镜像超过 200MB 阈值,请检查 Dockerfile"
      exit 1
    fi

配合 dive 工具做层分析,能快速定位是哪一层把体积撑大的。


总结

回到开头那个 1.2GB → 8MB 的故事。真正的收益不只是磁盘和拉取时间,而是三件事:

  1. 攻击面缩小:镜像里没有 shell、编译器、包管理器,攻击者攻进来也“无处下手”;
  2. 部署确定性提升:镜像小意味着拉取快、冷启动快,滚动更新和 HPA 扩容的响应时间显著下降;
  3. 构建可复现:精确 tag + 缓存分层 + -trimpath,让“同样的源码产出同样的镜像”成为可能。

我想强调的核心观点是:最小化不是目的,而是“构建期依赖与运行时依赖彻底分离”这一架构原则的自然结果。多阶段构建的语法只是手段,理解“哪些东西属于后厨、哪些属于餐盘”才是关键。当你把每个依赖都问一遍“运行时真的需要它吗”,镜像体积自然会收敛到合理值。

最后留一个延伸思考:镜像最小化之后,调试怎么办? 生产容器里没 shell、没 curl、没 ps,出问题时怎么排查?答案是转向 ephemeral container(临时容器) 和 eBPF 可观测性——不往镜像里加工具,而是从集群层面旁路观测。这恰好印证了“不可变基础设施”的哲学:镜像越纯粹,运维手段越应该外置。这也是为什么 K8s 从 1.23 起大力推 ephemeral container——它和最小化镜像是天生一对。

下一步,建议你把团队现有的 Dockerfile 全部过一遍 dive,看看体积都堆在哪一层。大概率你会发现,和当年的我一样:真正需要的,远比你以为的少得多。