Docker多阶段构建实战:从镜像瘦身到生产发布

举报
yd_277255811 发表于 2026/11/09 08:45:36 2026/11/09
【摘要】 Docker多阶段构建实战:从镜像瘦身到生产发布 一、多阶段构建是什么传统 Dockerfile 是一条流水线:从基础镜像开始,一条 RUN 接一条 RUN,最终产出一个镜像。问题是编译工具链留在最终镜像里,一个 Go 项目最终镜像里却带着 gcc、Go SDK、源码和 Git 历史,体积能到 1GB 以上。多阶段构建(Multi-Stage Build)的思路是:把构建拆成多个阶段,每个...

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

十一、小结

多阶段构建的核心价值可以概括为一句话:构建环境与运行环境分离。

推荐的实践路径:

  1. 先把现有的单阶段 Dockerfile 加上 AS builder 拆开,立刻能拿到体积收益
  2. 把依赖安装挪到源码 COPY 之前,解决缓存问题
  3. 逐步换用更小的基础镜像(alpine / distroless / scratch)
  4. 补上 .dockerignore、非 root 用户、健康检查
  5. 在 CI 里开启 BuildKit 缓存挂载

做完这五步,同一个应用的镜像通常能从 1GB 以上降到 100MB 上下,拉取速度和漏洞扫描结果都会明显改善。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。