容器与云原生 / 系统课时
多阶段构建解决什么问题
多阶段构建解决什么问题
生产镜像真正需要的通常只是可执行文件、运行时库和少量配置,但传统单阶段 Dockerfile 会把编译器、SDK、源码和构建缓存一起带进镜像。多阶段构建把“编译”和“运行”拆成独立阶段,只复制最终产物,从结构上减少生产镜像内容。
学习目标
- 理解多阶段构建中各阶段之间的职责与数据流
- 能编写一个完成编译并只复制产物到运行阶段的 Dockerfile
- 能验证最终镜像不包含构建工具和源码
多阶段构建的核心是隔离构建环境
一个多阶段 Dockerfile 可以出现多个 FROM。每个 FROM 都开启一个新的构建阶段,前面的阶段可以包含编译器、依赖下载工具和源码,后面的阶段则只接收运行时真正需要的文件。
最终镜像默认是最后一个阶段的文件系统,而不是前面所有阶段的叠加。因此,前一阶段里即使安装了几百 MB 的工具,只要没有通过 COPY --from=<stage> 复制到最终阶段,它们就不会进入生产镜像。

用 Go 应用完成一次多阶段构建
下面是一个最小可运行示例。main.go 只有一个输出,便于把注意力放在构建阶段之间的关系。
package main
import "fmt"
func main() {
fmt.Println("hello from multistage")
}Dockerfile 中,第一个阶段命名为 build,负责编译;第二个阶段重新从较小的 Alpine 镜像开始,只复制二进制文件。
FROM golang:1.25-alpine AS build
WORKDIR /src
COPY main.go .
RUN CGO_ENABLED=0 go build -o /out/app main.go
FROM alpine:3.22
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]这里的关键不是“用了两个基础镜像”,而是第二阶段没有继承第一阶段的文件系统。COPY --from=build 明确指定只把 /out/app 带入最终镜像。
在包含 main.go 和 Dockerfile 的目录执行:
docker build --quiet -t demo-multistage .
docker run --rm demo-multistage
docker run --rm --entrypoint sh demo-multistage -c 'if command -v go >/dev/null 2>&1; then echo go-present; else echo go-absent; fi'预期输出:
sha256:<ID>
hello from multistage
go-absent镜像 ID 会随构建变化。核心验收结果是应用能输出 hello from multistage,同时运行阶段查不到 go 命令,说明 Go 工具链没有被复制进最终镜像。
为什么这比“构建后删除工具”更可靠
单阶段做法经常先安装编译器,再构建应用,最后执行 rm 删除源码和工具。但如果这些内容已经进入更早的镜像层,后续删除不能回收前一层的数据。多阶段构建直接让最终阶段从一个新的基础镜像开始,因此构建期文件从来没有成为最终镜像的一部分。
这种隔离还有两个额外收益:最终镜像包含的软件更少,漏洞扫描和补丁范围更小;运行容器中也没有编译器、包管理器等通常不需要的工具,攻击面更容易控制。
验证最终镜像只留下运行所需内容
构建成功后,可以查看镜像历史确认最终阶段只包含 Alpine 基础层、复制产物和入口配置。
docker run --rm --entrypoint sh demo-multistage -c 'test ! -e /src && echo source-dir-absent'
docker history demo-multistage --format '{{.CreatedBy}}' | grep -E 'go build|COPY main.go|WORKDIR /src' || echo "build-stage-not-in-final-history"预期输出:
source-dir-absent
build-stage-not-in-final-history这两个检查分别验证运行镜像里没有构建源码目录,最终镜像历史里也没有第一阶段的编译步骤。实际层描述会随 Docker/BuildKit 版本变化,但多阶段构建的边界不变。调试构建阶段时可以使用 --target build 指定目标阶段,生产交付仍应以最后的运行阶段为目标。
当应用必须经过编译、打包、压缩或前端构建,而运行时只需要产物时,多阶段构建通常是最直接的选择。它不是事后清理,而是在 Dockerfile 结构上规定“哪些东西有资格进入最终镜像”。