Dockerfile 最佳实践 多阶段构建减少镜像体积

什么是 Docker 多阶段构建

多阶段构建（Multi-stage Build）是 Docker 17.05 引入的一项重要特性，它允许在一个 Dockerfile 中使用多个 FROM 指令。每个 FROM 开始一个新的构建阶段，你可以选择性地将前一个阶段的产物复制到当前阶段，而无需引入多余的工具链、依赖和源代码，从而显著减小最终镜像的体积，同时保持 Dockerfile 的清晰和可维护性。

为什么需要多阶段构建

传统单阶段构建的痛点

在单阶段构建中，为了编译或构建应用，通常需要安装编译器、SDK、开发头文件等大量构建依赖。这些工具和文件会在最终镜像中残留，导致以下问题：

• 镜像体积膨胀：构建工具本身可能占用数百兆甚至上GB的空间
• 攻击面增大：包含编译器、调试工具会增加安全风险
• 部署效率低下：镜像拉取和启动速度变慢
• 维护混乱：往往需要编写复杂的 shell 命令来清理临时文件

多阶段构建带来的优势

• 镜像体积最小化：只保留运行时必需的文件
• 安全性提升：移除构建工具和源代码，减少潜在漏洞
• Dockerfile 更易读：构建步骤逻辑分离，结构清晰
• 构建缓存优化：不同阶段可使用独立缓存，提升构建速度

多阶段构建工作原理

多阶段构建通过在 Dockerfile 中定义多个 FROM 指令，并利用 --from 标志从前期阶段复制文件。

# 第一阶段：构建环境
FROM golang:1.21 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o myapp .

# 第二阶段：运行环境
FROM alpine:3.18
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/myapp /usr/local/bin/myapp
ENTRYPOINT ["myapp"]

• 第一阶段命名为 builder，安装了 Go 编译器并构建出二进制文件
• 第二阶段使用轻量级的 Alpine，仅复制编译好的二进制和必要证书
• 最终镜像中不会包含 Go SDK 和源码

编写高效多阶段 Dockerfile 的最佳实践

选择合适的基础镜像

• 构建阶段：使用包含完整工具链的官方镜像，如 golang:1.21、node:18、maven:3.9-eclipse-temurin-17 等，确保构建顺利进行
• 运行阶段：优先选择精简操作系统基础镜像，如 alpine、distroless 或 scratch（如果应用静态编译）
  • alpine：约 5MB，适合多数场景
  • distroless：只包含应用所需的最小依赖，安全且体积小
  • scratch：空镜像，仅适用于完全静态链接的二进制

优化阶段顺序与缓存

Docker 构建会按行缓存，将不常变化的步骤放在前面，可最大化利用缓存：

# 先复制依赖描述文件，再复制源码
COPY go.mod go.sum ./
RUN go mod download
COPY . .

对于多阶段构建，不同阶段拥有独立的缓存空间，修改一个阶段的步骤不会使其他阶段缓存失效，除非名称引用发生变化。

使用多阶段分离编译与运行时依赖

将依赖安装、代码编译放在构建阶段，运行时阶段只复制最终产出：

Node.js 示例：

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/main.js"]

这里仅复制了 node_modules 和生产构建产物 dist，不包含源代码和开发依赖。

正确使用 .dockerignore

.dockerignore 文件可避免将不必要的文件（如 .git、node_modules、日志、本地配置）发送到构建上下文，既能减少构建时间，也能防止敏感信息意外进入镜像。

.git
node_modules
*.log
.env
.vscode
Dockerfile
.dockerignore

合并多个 RUN 命令减少层数

在构建阶段，将多个命令合并在一个 RUN 中执行，并使用 && 连接，可降低镜像层数：

RUN package-manager update && \
    package-manager install -y build-deps && \
    ./compile.sh && \
    package-manager remove -y build-deps && \
    package-manager clean all

但注意：在多阶段构建中，构建阶段的层数不影响最终镜像大小，因此为了可读性和调试方便，可适当保留合理数量的层。运行时阶段则应尽量精简。

使用 --from 精确复制文件

COPY --from 不仅可以从上一个阶段复制，还可以直接复制任意阶段、甚至外部镜像的文件：

COPY --from=nginx:latest /etc/nginx/nginx.conf /etc/nginx/nginx.conf

这适用于提取官方镜像中的特定配置文件或工具，避免重复编写复杂脚本。

合理命名构建阶段

通过 AS 为阶段命名，提高可读性，也便于后续引用：

FROM node:18 AS deps
FROM deps AS build
FROM alpine:3.18 AS runtime

如果只构建某一阶段（如用于调试），可以使用 --target 参数：

docker build --target build -t myapp:build .

实战案例：Go 语言多阶段构建

一个优化到极致的 Go 应用 Dockerfile：

# 构建阶段
FROM golang:1.21-alpine AS builder
RUN apk add --no-cache git ca-certificates
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app ./cmd/myapp

# 运行阶段
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /app /app
EXPOSE 8080
ENTRYPOINT ["/app"]

• 使用 -ldflags="-s -w" 去除调试信息和符号表，进一步减小二进制大小
• 运行阶段使用 scratch，并仅拷贝 CA 证书满足 HTTPS 请求
• 最终镜像仅含一个可执行文件，体积通常在 10 MB 以内

多阶段构建与前端 SPA

对于 React、Vue 等前端项目，可将构建与部署分离：

# 构建阶段
FROM node:18-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 生产阶段
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

生产阶段只包含静态文件和 Nginx，镜像大小仅比 nginx:alpine 增加几 MB。

常见问题与注意事项

文件权限问题

在多阶段复制文件时，权限会保留源文件的所有者和组。如果运行阶段使用不同用户，可能需要调整：

COPY --from=builder --chown=nonroot:nonroot /app /app

动态链接库缺失

当运行阶段使用 scratch 或 distroless 时，若二进制依赖动态链接库（如 glibc），需提前在构建阶段安装对应共享库，并通过复制等方式带入运行阶段。更好的方案是静态编译 (CGO_ENABLED=0)。

多阶段构建的缓存复用

构建阶段和运行阶段的层缓存相互独立；当源码变更时，仅在构建阶段重新执行，运行阶段仅复制产物，因此修改业务代码后，大部分缓存仍然有效，能缩短二次构建时间。

对比：多阶段构建 vs 传统优化方案

多阶段构建已成为 Docker 官方推荐的最佳实践，能有效平衡体积、安全与开发体验。

总结

• 多阶段构建通过在 Dockerfile 中使用多个 FROM 分离构建和运行环境
• 能够显著减少镜像体积，提升安全性，同时保持 Dockerfile 整洁
• 善于利用 --from 复制所需文件，选择极简基础镜像（alpine、scratch、distroless）
• 结合 .dockerignore、合理分层、静态编译等技巧，可进一步优化镜像
• 适用于各种语言栈，是生产级 Docker 镜像的标配方案