Docker多阶段构建实战:从镜像瘦身到生产发布
Docker多阶段构建实战:从镜像瘦身到生产发布
一、多阶段构建是什么
传统 Dockerfile 是一条流水线:从基础镜像开始,一条 RUN 接一条 RUN,最终产出一个镜像。问题是编译工具链留在最终镜像里,一个 Go 项目最终镜像里却带着 gcc、Go SDK、源码和 Git 历史,体积能到 1GB 以上。
多阶段构建(Multi-Stage Build)的思路是:把构建拆成多个阶段,每个阶段用独立的 FROM 开头,前一个阶段的产物通过 COPY --from 传给下一个阶段。
阶段1 builder: 基础镜像 + 编译器 + 源码 → 编译出二进制文件
阶段2 runtime: 极简运行时镜像,只 COPY 上一步的二进制
最终产物只包含运行时真正需要的东西,编译工具链留在中间阶段,永远不会进入最终镜像。
二、一个反面教材
先看传统的写法:
FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN go build -o /app/server ./cmd/server
FROM ubuntu:22.04
WORKDIR /app
COPY --from=builder /src/go.mod ./
COPY --from=builder /src/go.sum ./
RUN apt-get update && apt-get install -y ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/server .
EXPOSE 8080
CMD ["./server"]
改造前后的对比:
| 项目 | 单阶段 | 多阶段 |
|---|---|---|
| 镜像大小 | ~1.1 GB | ~180 MB |
| 攻击面 | 含 gcc、curl、源码 | 仅运行时依赖 |
| CVE 扫描告警 | 几十条 | 个位数 |
| 拉取耗时 | 慢 | 快 5 倍以上 |
三、第一个多阶段构建
3.1 Go 应用完整示例
# ---------- 阶段 1:编译 ----------
FROM golang:1.22-alpine AS builder
WORKDIR /src
# 先只拷依赖描述文件,命中缓存时不必重装依赖
COPY go.mod go.sum ./
RUN go mod download
COPY . .
# CGO_ENABLED=0 生成静态二进制,可直接跑在 scratch/distroless 上
RUN CGO_ENABLED=0 GOOS=linux go build \
-ldflags="-s -w" \
-o /out/server ./cmd/server
# ---------- 阶段 2:运行时 ----------
FROM alpine:3.19
RUN apk add --no-cache ca-certificates tzdata \
&& echo "Asia/Shanghai" > /etc/timezone
WORKDIR /app
COPY --from=builder /out/server /app/server
# 用非 root 用户运行
RUN addgroup -S app && adduser -S app -G app \
&& chown -R app:app /app
USER app
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s \
CMD wget -qO- http://localhost:8080/healthz || exit 1
ENTRYPOINT ["/app/server"]
3.2 阶段命名的讲究
AS builder 里的名字可以任意取,但建议语义化:
FROM node:20 AS deps # 只装依赖
FROM node:20 AS builder # 编译
FROM nginx:alpine AS runtime # 运行时
多阶段多了以后,COPY --from=builder 会更好维护。
四、COPY --from 的四种来源
4.1 从前一个阶段
COPY --from=builder /out/server /app/server
4.2 从外部镜像
可以把构建产物直接从一个独立镜像拷过来,实现「预构建镜像 + 运行时拼装」:
FROM myregistry/app-builder:1.4 AS prebuilt
FROM alpine:3.19
COPY --from=prebuilt /app/server /app/server
4.3 从构建上下文
COPY --from=context . /app/src
实际很少用,因为跟普通 COPY . . 没区别。
4.4 从 Docker 镜像 tarball
COPY --from=alpine:3.19 /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
这条很实用:直接从官方镜像里拿 CA 证书包,不用自己 apt install。
五、跨语言实战
5.1 Node.js / TypeScript
Node 依赖多,最容易踩「devDependencies 被打进镜像」的坑:
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist
USER node
CMD ["node", "dist/main.js"]
注意 npm ci --omit=dev,只装生产依赖。
5.2 Python
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /install /usr/local
COPY . .
EXPOSE 8000
CMD ["gunicorn", "app:app", "-b", "0.0.0.0:8000"]
5.3 Java / Spring Boot
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /build
COPY pom.xml .
RUN mvn -B dependency:go-offline
COPY src ./src
RUN mvn -B package -DskipTests
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY --from=builder /build/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
dependency:go-offline 单独放在前面,是为了利用 Docker 层缓存——只改代码不用重下依赖。
六、镜像瘦身的六个手段
6.1 选对基础镜像
| 基础镜像 | 大小 | 适用场景 |
|---|---|---|
alpine:3.19 |
~7 MB | 大多数 Go / 静态二进制 |
scratch |
0 MB | 完全静态、无需证书的程序 |
distroless/static |
~2 MB | 生产级最小镜像 |
debian:12-slim |
~75 MB | 需要 glibc 和各种工具 |
ubuntu:22.04 |
~77 MB | 通用 |
golang:1.22 |
~800 MB | 只用在构建阶段 |
6.2 合并 RUN 并清理缓存
每一层 RUN 都会留一个层。分开的写法会留下中间层垃圾:
# 不好:apt 缓存留在前一层
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*
# 好:同一条指令里更新、安装、清理
RUN apt-get update \
&& apt-get install -y --no-install-recommends curl \
&& rm -rf /var/lib/apt/lists/*
Alpine 同理:
RUN apk add --no-cache curl
--no-cache 直接不写索引缓存。
6.3 用 .dockerignore 排除无关文件
没有 .dockerignore 时,COPY . . 会把 node_modules、.git 一起打进去:
.git
node_modules
dist
*.log
.env
.DS_Store
docs/
tests/
这不仅拖慢构建,还可能把密钥带进镜像。
6.4 别用 root 跑
RUN adduser -S app -G app
USER app
不只是安全规范——很多运行时会拒绝以 root 启动容器。
6.5 前置 apt update
# 不好:apt-get update 可能命中过期索引
RUN apt-get install -y curl
# 好:同一条里先 update
RUN apt-get update && apt-get install -y --no-install-recommends curl \
&& rm -rf /var/lib/apt/lists/*
6.6 用 BuildKit 缓存挂载
# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
npm ci
COPY . .
RUN --mount=type=cache,target=/root/.npm \
npm run build
依赖安装只在第一次真正下载,后续构建复用缓存目录,能省大量时间。
七、构建命令
7.1 基本构建
docker build -t myapp:1.0 -t myapp:latest .
7.2 指定阶段
多阶段构建默认构建最后一个阶段。调试时可以指定中间阶段:
# 只构建到 builder 阶段,进去看看编译产物
docker build --target builder -t myapp:debug .
docker run --rm -it myapp:debug sh
7.3 使用 BuildKit
DOCKER_BUILDKIT=1 docker build -t myapp:1.0 .
BuildKit 支持 --mount、并行执行构建步骤、更好的缓存策略。
7.4 导出镜像
docker save -o myapp.tar myapp:1.0
docker load -i myapp.tar
八、CI/CD 中的构建
8.1 GitHub Actions
name: build-and-push
on:
push:
tags: ['v*']
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Buildx
uses: docker/setup-buildx-action@v3
- name: Login to registry
uses: docker/login-action@v3
with:
registry: ${{ secrets.REGISTRY }}
username: ${{ secrets.REGISTRY_USER }}
password: ${{ secrets.REGISTRY_PASSWORD }}
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: ${{ secrets.REGISTRY }}/myapp:${{ github.ref_name }}
cache-from: type=registry,ref=${{ secrets.REGISTRY }}/myapp:cache
cache-to: type=registry,ref=${{ secrets.REGISTRY }}/myapp:cache,mode=max
8.2 Docker Compose 本地验证
services:
app:
build:
context: .
target: runtime
image: myapp:1.0
ports:
- "8080:8080"
environment:
- TZ=Asia/Shanghai
九、验证瘦身效果
# 对比各层大小,找出大的层
docker history myapp:1.0
# 查看最终大小
docker images myapp:1.0
# 扫描高危漏洞
docker scout cves myapp:1.0
一个实用的技巧是先看看体积花在哪:
docker history --no-trunc myapp:1.0 | head -20
通常你会发现构建阶段的几层占了大头——那正是多阶段构建要消除的部分。
十、常见坑
坑 1:COPY --from 报文件不存在
多阶段构建的路径是相对于上一个阶段的根目录,不是相对于 WORKDIR:
# 错误
RUN go build -o /out/server ./cmd/server
COPY --from=builder /out/server /app/server # ✅ 对的
# 如果写成了相对路径
RUN go build -o server ./cmd/server
COPY --from=builder ./server /app/server # ❌ 找不到
坑 2:静态二进制仍然报找不到 libc
说明 CGO 没关掉:
CGO_ENABLED=0 go build
验证:
docker run --rm myapp:1.0 ldd /app/server
# 输出 "not a dynamic executable" 才对
坑 3:镜像里带着时区不对
FROM alpine
RUN apk add --no-cache tzdata
ENV TZ=Asia/Shanghai
Alpine 默认没有时区数据,日志时间会差 8 小时。
坑 4:缓存不生效
Docker 只在 COPY 指令之后的层失效。如果依赖装在 COPY . . 之后,任何代码改动都会导致依赖重装。依赖相关指令必须放在源码 COPY 之前:
COPY package.json package-lock.json ./ # 先拷依赖描述
RUN npm ci
COPY . . # 再拷源码
坑 5:scratch 镜像证书问题
用 scratch 时 HTTPS 请求会报证书错误,因为没有 CA 证书:
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /out/server /server
十一、小结
多阶段构建的核心价值可以概括为一句话:构建环境与运行环境分离。
推荐的实践路径:
- 先把现有的单阶段 Dockerfile 加上
AS builder拆开,立刻能拿到体积收益 - 把依赖安装挪到源码 COPY 之前,解决缓存问题
- 逐步换用更小的基础镜像(alpine / distroless / scratch)
- 补上
.dockerignore、非 root 用户、健康检查 - 在 CI 里开启 BuildKit 缓存挂载
做完这五步,同一个应用的镜像通常能从 1GB 以上降到 100MB 上下,拉取速度和漏洞扫描结果都会明显改善。
- 点赞
- 收藏
- 关注作者
评论(0)