2026/9/15 5:38:31
FEATURED · 精选文章 
1. 为什么我劝你早点用上多阶段构建很多朋友第一次接触 Docker 都是先学会写一个简单的 Dockerfile拉一个基础镜像把代码 COPY 进去再 RUN 几条安装命令最后 EXPOSE 一个端口完事。这种写法在跑通项目的阶段完全够用但一旦项目开始交付、上生产环境痛点就马上出来了。最大的痛点就是镜像体积。我见过一个 Java 后端服务开发机打包出来的 JAR 才 80MB结果 Dockerfile 用FROM maven:3.8-jdk-11做基础镜像再把源码直接 COPY 进去构建最后构建出来的镜像居然有将近 800MB。800MB 是什么概念你推送到镜像仓库要好几分钟在服务器上拉取也要好几分钟带宽占用大不说万一同时部署好几个服务磁盘空间直接报警。更尴尬的是这 800MB 里真正运行时的 Java 程序只有 80MB剩下 700 多 MB 全是编译工具、依赖缓存和中间产物这些在容器跑起来之后一点用都没有。第二个痛点也很要命构建环境的安全风险。用一个大而全的基础镜像做运行时意味着你的生产容器里装着编译器、构建工具、各种源码文件。如果镜像被拉下来做安全扫描这些组件很容易暴露高危漏洞如果应用被攻破攻击者甚至可以基于容器里的编译工具做进一步的横向操作。简单说你在生产环境里塞了一堆完全不该存在的东西。多阶段构建multi-stage build就是冲着这两个痛点去的。它的核心思路特别朴素构建过程用功能完整的大镜像构建产物拷贝到一个干净的小镜像里最后只有小镜像被打包分发。整个过程写在一个 Dockerfile 里不依赖外部的 CI 脚本也不需要维护两套配置文件。这篇文章我会从多阶段构建的原理讲起逐步演示 Go、Node.js、Java 三种主流场景的完整 Dockerfile 写法再讲构建缓存、ARG 传参、平台兼容、镜像瘦身这些进阶操作最后把我在实际项目中踩过的坑和排查思路整理成一份速查表。不管你是刚接触 Docker 的新手还是已经在生产环境用了一段时间、想进一步优化镜像体积的开发者这篇文章应该都能给你一些可直接落地的参考。为了方便复现我先说明一下环境和基础操作。本机为 Windows 11已安装 WSL2 后端但本文所有 Dockerfile 也能在 macOS、Linux 及裸机 docker 上直接运行。如果你的 Docker 还没装好或者启动时报错我建议先检查两件事Windows 上确认 BIOS 里虚拟化已开启WSL2 终端里执行wsl -l -v能看到 docker-desktop 分发版Ubuntu/CentOS 上就在终端执行docker info确认 Client 和 Server 都已正常。下面的内容默认你的docker version和docker compose version都输得出信息。2. 多阶段构建的核心思路与设计逻辑2.1 从单阶段构建的“一条龙”说起先看一个典型的单阶段构建 Dockerfile以 Node.js 项目为例FROM node:18 WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build EXPOSE 3000 CMD [npm, start]这个 Dockerfile 的问题在哪里它把依赖安装、源代码拷贝、构建、运行全部混在一个镜像里了。node:18是一个完整的开发环境镜像自带了 npm、npx、编译链等工具体积本身就超过了 1GB。你最终分发出去的镜像既有 node_modules 里几百 MB 的依赖包又有构建过程中生成的临时文件还有完整的开发工具链。逻辑上这相当于你在搬家的时候不但把家里用的家具搬过去了还把装修用的电锯、油漆桶、脚手架也一起搬过去了。家具只需要用一次但装修工具永远留在新家里占地方第一次可能感受不到等镜像多起来、团队成员多起来每个人本地都要拉这几百 MB 的东西问题就会被无限放大。单阶段构建还有一种常见情况运行环境需要的东西和构建环境需要的东西不一样。比如 C 语言项目要编译出二进制文件编译需要 gcc、make、各类头文件但运行时只靠一个动态链接的二进制文件就够了比如 Java 项目编译需要 JDK 和 Maven运行时只需要 JRE比如前端项目构建需要 Node.js但最终产物只是静态文件甚至连 Nginx 都可以用现成的镜像。这种“构建和运行环境分离”的需求单阶段构建几乎没法优雅满足传统的做法是写两个 Dockerfile再靠 CI 脚本去串联维护成本很高。2.2 多阶段构建解决了什么多阶段构建的核心机制非常简单一个 Dockerfile 里可以有多个FROM指令每个FROM开启一个新的构建阶段。后面的阶段可以通过COPY --from阶段名或序号从前面的阶段拷贝文件而前面的阶段就是“构建使用的环境”最后一个阶段才是“实际产出的镜像”。这么说可能还是有点抽象下面是一个最简单的 Go 语言示例# 阶段一编译 FROM golang:1.21 AS builder WORKDIR /build COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED0 GOOSlinux go build -o myapp . # 阶段二打包运行 FROM alpine:3.19 WORKDIR /root COPY --frombuilder /build/myapp . EXPOSE 8080 CMD [./myapp]这个 Dockerfile 里有两个阶段golang:1.21阶段只做一件事拉取依赖、编译出二进制。alpine:3.19阶段只做一件事把编译好的二进制文件拷过来然后运行它。最终镜像不包含 Go 编译器、不包含源代码、不包含任何依赖缓存只有瘦小的 Alpine 系统和那一个二进制文件。在真实项目中这个镜像的实际大小大概在 10~20MB 之间这和使用标准golang:1.21镜像构建且不做任何优化的版本相比体积缩小 10 倍以上。理解了这句话你基本就把握住多阶段构建的七成了前面的阶段是加工车间后面的阶段是成品房车间里的工具一概不带走。2.3 为什么这条路径值得选权衡与取舍同为镜像瘦身方案多阶段构建还常被拿来和另几条路对比我列一下自己在调研和实践中看到的真实差异用docker-slim做自动瘦身这个工具能基于运行行为自动生成精简镜像但生成过程比较玄学依赖动态分析遇到启动后不怎么写入文件的应用容易误删而且对不同项目的结果一致性不太好保证。我的体会是它适合拿来处理那些你拿不到源码的历史镜像如果源码就在你手里多阶段构建的控制力要强得多。手动“编译后清理”就是在同一条 RUN 命令里先安装构建工具编译完再删掉。问题在于镜像的分层机制删除操作如果不在同一层里完成就不会真正减小镜像体积如果你把 apt 安装和 rm 拆成两条 RUN那些包还是会在镜像历史里占空间。多阶段构建把这个问题从根上绕开了因为构建工具根本不会进入最终阶段。把构建放在宿主机只把产物打进镜像这种方式本质上是在 Dockerfile 之外手工复刻了多阶段构建里的“builder”阶段但容易把宿主机环境差异带进来比如 glibc 版本不一致、平台架构不一致而且 CI 脚本要额外维护。多阶段构建完全在 Dockerfile 描述范围内完成换任何人、任何机器都能以同样的方式构建可复现性更高。所以我的经验是如果一个项目需要在容器里做构建能上多阶段构建就尽量上它应该是默认选项而不是需要特别理由的优化项。3. 核心细节解析与实操要点3.1 阶段命名与 COPY --from 的正确姿势多阶段构建里有两个特别容易忽略的小细节阶段命名和COPY --from的写法。阶段默认的标识是序号从 0 开始。也就是说上面的 Go 例子里golang阶段是第 0 阶段alpine阶段是第 1 阶段。你在后面的阶段里可以写COPY --from0 /build/myapp /root/myapp。序号写法有个问题如果你在中间插入了新的阶段所有的序号都会变Dockerfile 的可维护性直线下降。所以凡是超过两个阶段或者有插入新阶段可能的项目我都建议给阶段起一个可读的名字。方法是在FROM后面加上AS关键字FROM golang:1.21 AS builder然后在拷贝的时候用名字引用COPY --frombuilder /build/myapp /root/myapp这样不管阶段顺序怎么调整、上面新增多少阶段只要AS builder这个名字不变下面的拷贝逻辑就永远正确。另外注意一个容易踩的坑COPY --from不仅能从前面的阶段拷贝文件还能从“外部镜像”拷贝文件。比如你能从nginx:1.25镜像里直接拷贝配置文件而不需要在当前构建过程中再拉取那个镜像。这在实际项目中用途很多最常见的做法是COPY --fromnginx:1.25 /etc/nginx/nginx.conf /etc/nginx/nginx.conf这段指令在构建时会把nginx:1.25镜像里的nginx.conf文件拷贝到当前镜像对应路径相当于一个“文件级引用”不必继承整个镜像的基础层。需要注意此时 Docker 会去拉取这个镜像如果本地没有它会先从远程仓库下载然后再提取文件。好处是你不用自己写一份配置文件也无需单独维护一个配置文件镜像。3.2 构建上下文与 .dockerignore 配合多阶段构建能在最终镜像里缩小体积但有一个前置条件容易被忽略构建上下文的大小。所谓构建上下文就是你执行docker build时指定的那个目录通常是.。Docker 会先把整个上下文目录打包发送给 Docker 守护进程然后才能执行 Dockerfile 里的指令。如果你的项目目录里有一个巨大的node_modules、target、dist、.git每次构建这些都会被打包发送。这会带来两个实际问题构建前等待时间变长如果上下文里包含敏感信息比如.env文件、密钥文件它们还有可能被留在镜像历史中。多阶段构建不会自动帮你过滤上下文。所以我建议在任何项目里都保持一个基本的.dockerignore文件至少排除掉这些内容.git .gitignore node_modules npm-debug.log target dist build *.log .env .env.* Dockerfile .dockerignore这个文件的作用是构建时 Docker 会跳过这些路径不把它们发送到守护进程。看着很不起眼但在 monorepo 或大型项目里它能显著加快构建速度。另外一个很容易被忽略的点.dockerignore对构建上下文的大小优化只影响“发送阶段”不影响你在 Dockerfile 里实际能 COPY 什么。如果你在.dockerignore里排除了node_modules然后又写了COPY node_modules /app/node_modules构建时会报错找不到文件所以“排除”和“使用”边界要分清。3.3 基础镜像选型与包管理器源多阶段构建中基础镜像的选择会直接影响最终镜像的体积和安全性。让我从几个常用方向分析一下官方镜像 vs 精简镜像官方镜像如node:18、python:3.11、golang:1.21适合作为 builder 阶段的基础镜像。它们功能完整有什么依赖问题基本都能在官方镜像里找到CLI 工具齐全调试省心。但最终运行阶段我通常不会直接用它们而是换用 Alpinealpine:3.19、Distrolessgcr.io/distroless/*或直接基于scratch。Alpine 镜像目前最主流的精简镜像选择体积约 5MB基于 musl libc包管理用apk。缺点是如果你编译的程序是动态链接到 glibc 的直接放到 Alpine 里会报 “not found”。这个坑我后面专门讲。Distroless 镜像Google 提供的“只包含运行时必要内容”的镜像里没有 shell、没有包管理器、没有系统库以外的东西安全等级更高但进容器调试基本不可能没有/bin/sh。它适合你已经很稳定、几乎不需要在容器里敲命令的服务。scratch空镜像适合纯静态二进制比如 Go 的CGO_ENABLED0编译结果。注意scratch不是一个真正的镜像仓库它只是一个构建起点FROM scratch后你的镜像里除了自己 COPY 进去的东西什么都不会有。镜像源调整技巧如果你在国内网络环境构建官方镜像源往往拉不动或者慢到怀疑人生。我常用的两个办法先在宿主机或 Dockerfile 里配好国内镜像源比如 alpine 的mirrors.aliyun.com、Ubuntu 的mirrors.tuna.tsinghua.edu.cn、npm 的registry.npmmirror.com在 Dockerfile 里加一行RUN sed -i s#dl-cdn.alpinelinux.org#mirrors.aliyun.com#g /etc/apk/repositories之类的替换逻辑。另一个办法是给 Docker daemon 配 registry mirrorDaemon 层面统一走加速器这样在任何镜像仓库的拉取都会快不少。从我的实践看镜像源的选择要根据团队部署环境来定私有化交付场景外网下载经常受限提前把 base image 镜像和 Builder 镜像的大版本固定下来比如不用node:latest而是node:18.20.2-alpine比日常省心得多。3.4 多阶段构建下依赖安装的取舍依赖安装对多阶段构建有直接影响主要有两个方向要注意锁文件和安装策略。先说说锁文件。无论 npm 的package-lock.json、pip 的requirements.txt、Go 的go.sum还是 Java 的pom.xml或 maven wrapper都建议提前单独 COPY 进构建阶段执行依赖安装再拷贝源码。这样能利用 Docker 的层缓存只要依赖文件没变依赖安装层就直接用缓存不用每改一行代码就重新编译一遍项目。这个细节处理好了构建速度能快上好几倍。然后说说安装策略。Node.js 项目生产依赖和开发依赖要分清依赖安装在 builder 阶段执行你最终只需要拷贝dist或者build目录以及运行阶段必要的依赖。如果项目体积非常大也可以把“最终运行依赖”再单独 COPY 一次常见的写法是# 阶段一构建 FROM node:18 AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 阶段二生产依赖精简 FROM node:18-alpine AS deps WORKDIR /app COPY package*.json ./ RUN npm ci --omitdev # 阶段三运行 FROM node:18-alpine WORKDIR /app COPY --frombuilder /app/dist ./dist COPY --fromdeps /app/node_modules ./node_modules EXPOSE 3000 CMD [node, dist/index.js]这样生产镜像里没有 devDependencies也不会把整个源码目录都拷进去。注意这里中间多了一个deps阶段它和builder阶段的区别就是只安装生产依赖避免把开发依赖带进最终镜像。4. 实操过程与核心环节实现4.1 场景一Go 服务编译与 scratch 运行Go 也许是多阶段构建里最顺的场景因为 Go 本身能把依赖和运行时静态编译到一个二进制文件里。配合scratch或alpine产物镜像可以做到几 MB 到十几 MB。一个生产可用的 Dockerfile 长这样# syntaxdocker/dockerfile:1.7 FROM golang:1.21 AS builder WORKDIR /src # 先拷贝 go.mod 和 go.sum利用缓存 COPY go.mod go.sum ./ RUN go mod download # 拷贝全部源码并编译 COPY . . RUN CGO_ENABLED0 GOOSlinux go build -trimpath -ldflags-s -w -o /out/app . FROM scratch COPY --frombuilder /out/app /app EXPOSE 8080 ENTRYPOINT [/app]这里有几点要特别说明CGO_ENABLED0会强制关闭 CGO。这样编译出的二进制不会动态链接 glibc放到没有 glibc 的scratch镜像里才能直接运行。如果你用到了需要 CGO 的库比如某些 SQLite 驱动、网络库编译期会有兼容性问题那时就不能用 scratch改换成alpine并安装对应运行库。-trimpath会去掉编译信息里的本地路径-ldflags-s -w会去掉符号表和调试信息能明显减小二进制体积。一个是减少泄露代码路径一个是压缩体积两个建议在生产构建里都加上。如果你的 Go 程序需要读取系统证书比如访问 HTTPS 接口scratch里没有 CA 证书需要从 builder 或者其他基础镜像里额外拷贝COPY --frombuilder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/另外很多 Go 服务需要时区数据scratch 里也没有可以从 builder 里拷贝/usr/share/zoneinfo或只拷贝需要的时区文件。最后确认产物到底能否在 scratch 上跑最好先在本机验证一下动态链接信息。构建完镜像后进入一个普通容器执行ldd myapp如果输出里面有libc.so.6、ld-linux-x86-64.so.2这类路径说明它依赖 glibc不能直接用 scratch必须换成alpine并安装 musl 兼容层或者直接用 Ubuntu/Debian 的 slim 镜像作为运行基础。4.2 场景二Node.js 前端/后端产物与 Nginx前端项目的目标产物是静态文件。用 Node 镜像构建完成后把dist目录拷贝到 Nginx 镜像里就可以了运行阶段完全不需要 Node。# 构建阶段 FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 运行阶段 FROM nginx:1.25-alpine COPY --frombuilder /app/dist /usr/share/nginx/html # 如果你有自定义的 nginx.conf也一起拷贝 # COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]最终这个镜像只包含 Nginx 和静态文件体积大概在 50MB 左右而不带多阶段优化时可能超过 1GB。需要注意如果你用了 SPA单页应用路由模式比如 Vue Router 的 history 模式Nginx 需要配置 try_files否则刷新页面会 404。还有一点前端项目里如果有.env之类的环境变量文件建议让它直接留在构建上下文里被排除运行时如果需要动态配置环境变量应走 Nginx 的 envsubst 模板方案而不是把文件打进镜像。4.3 场景三Java 后端项目中 Maven 与 JRE 分离Java 生态里多阶段构建特别有价值因为 JDK 和 Maven 的体积非常大这两者都不该出现在运行时里。理想情况下构建阶段用 JDK Maven运行阶段用 JRE 或者更精简的 JRE-based alpine 镜像。以 Spring Boot 项目为例# syntaxdocker/dockerfile:1.7 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build # 利用 maven 依赖缓存 COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests FROM eclipse-temurin:17-jre-alpine WORKDIR /app RUN addgroup -S appgroup adduser -S appuser -G appgroup COPY --frombuilder /build/target/myapp-*.jar app.jar USER appuser EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]几个细节解释一下先只拷贝pom.xml再执行mvn dependency:go-offline目的是预下载依赖利用 Docker 的层缓存。以后只要不改pom.xml这层就不会失效构建速度会快很多。Spring Boot 的 fat JAR 可以通过java -jar运行。如果你用了 Jib 或者 Spring Boot 的 layered jar 模式还可以进一步拆分层级把依赖和业务代码分开让镜像层缓存更精细。建议在 Dockerfile 里创建非 root 用户并切换。镜像默认以 root 运行容器进程这在生产环境里风险很高。多阶段构建正好给了你一个很自然的机会在运行阶段创建普通用户。4.4 场景四多阶段 Docker Compose 的联动用法多阶段构建不是只能单独配合docker build使用它同样适合在docker compose里做一键编排这在本地环境和 CI 环节非常顺手。一个常见的 Compose 文件片段长这样services: web: build: context: . target: runner ports: - 8080:8080这里的target: runner表示只构建 Dockerfile 中名为runner的那个阶段。如果你的 Dockerfile 只有一个运行阶段这个参数可不写但当 Dockerfile 里有多条阶段路径比如既有测试阶段又有编译阶段又有最终运行阶段你就可以在本地构建时只选runner在 CI 流水线里先跑tester阶段做静态检查或单元测试。一个更典型的联动是本地开发用 volume 挂载源码做热更新生产部署用多阶段构建出精简镜像。这种情况下你只需要一个 Dockerfile开发环境用docker compose up配合挂载生产环境用docker compose build或者 CI 里直接docker build完全不需要维护第二套配置。4.5 构建缓存与层缓存优化策略多阶段构建已经解决了“最终镜像太大”的问题但如果你不注意层缓存的利用率构建过程本身可能会非常慢。我把常用的缓存优化策略总结成几条可以逐条对照的清单依赖锁文件单独 COPY 并安装业务代码最后 COPY。这是最基础也最有效的一层缓存。对于有 lockfile 的项目npm、pip、go优先使用锁文件而不是手写模糊匹配版本。这样能保证可复现性也让缓存更容易命中。避免在一条 RUN 命令里写“先下载再删除”的步骤。虽然逻辑上没问题但它会把缓存的操作也写进层里面层缓存命中率会变差。如果你真的要用这种写法至少要把“下载依赖”和“清理缓存”分开并考虑通过网络代理或者其他方式缓存依赖包。官方 Docker 从 BuildKit 开始支持RUN --mounttypecache用在包管理器的缓存目录上很有效果。下面是一个真实可用示例FROM node:18-alpine AS builder WORKDIR /app RUN --mounttypecache,target/root/.npm \ npm ci它会把 npm 的缓存目录挂载为构建持久化缓存即使 Dockerfile 的其他层发生变化只要依赖源没变化依赖下载就不会重新走网络。这个能力在docker buildx和docker build --progressplain等 BuildKit 模式下默认开启。尽可能把“经常变化的”步骤往后放把“不常变化的”步骤往前放。这听起来像废话但实际很多人在写 Dockerfile 时会不自觉地把源码 COPY 放在依赖安装前面导致每次改代码都触发依赖重装构建时间直接翻倍。4.6 BuildKit 与构建参数ARG注入Docker 从 18.09 开始引入了 BuildKit 构建引擎从 23.0 起它已经是默认构建器。BuildKit 带来几个对多阶段构建特别友好的能力并行阶段构建、更好的层缓存包括跨 Dockerfile 的缓存复用、RUN --mounttypecache等高级语法。要在 Dockerfile 里使用这些高级语法第一行一般要加上# syntaxdocker/dockerfile:1.7这不是注释它是构建器识别的指令用来指定 Dockerfile 前端解析器的版本。没有这行也能用基本的多阶段构建但一些新特性比如RUN --mount可能不会启用。我的建议是只要是新建的 Dockerfile就把这一行放在最上面。ARG 注入是多阶段构建里非常实用但容易被忽略的能力。你可以在 Dockerfile 里定义参数然后通过docker build --build-arg传入# syntaxdocker/dockerfile:1.7 ARG APP_VERSION1.0.0 ARG BUILD_ENVproduction FROM golang:1.21 AS builder ARG APP_VERSION RUN echo Building version $APP_VERSION ...执行构建时docker build --build-arg APP_VERSION2.1.0 -t myapp .这样同一个 Dockerfile 就能在不同环境构建出不同版本的镜像不需要为版本号维护多个 Dockerfile。注意 ARG 的作用域问题基础阶段定义的 ARG不会自动传递给其他阶段。你需要在每一个需要用到它的阶段里重新声明一次即使只是透传。另外构建参数不要和运行环境变量混淆。构建参数只在构建过程中生效不会出现在最终镜像的运行环境变量里。如果你需要运行时配置比如数据库地址、密钥等请通过docker run -e或 Compose 里的environment注入。构建参数适合版本号、构建模式、资源地址这类“构建期变量”。4.7 多架构镜像与构建经验如果你需要同时产出linux/amd64和linux/arm64的镜像比如苹果芯片的 Mac 和 x86 服务器并存多阶段构建同样适用。核心工具是docker buildx它是 Docker BuildKit 的扩展命令。首先启用并创建构建器docker buildx create --name mybuilder --use docker buildx build --platform linux/amd64,linux/arm64 -t yourname/myapp:latest --push .这里有几个前提条件镜像仓库支持 multi-arch manifest目前主流仓库基本都支持builder 节点上配置了对应的模拟器或原生构建节点。Docker Desktop 自带 QEMU 模拟可以在本地直接构建多个平台的镜像。在多阶段构建 多架构的场景里两个特别值得注意的地方阶段缓存要分开命名否则不同架构的构建可能互相污染缓存。BuildKit 在缓存 key 里会自动带上平台信息一般不会有问题但如果你手动设置了很多--mounttypecache缓存挂载目标路径最好保持一致让不同平台可以复用公共缓存。编译参数要带上目标平台。还是以 Go 为例如果在 arm64 的机器上编译 amd64 镜像光有CGO_ENABLED0不够还需要GOARCHamd64。用 buildx 构建时它会自动注入 TARGETOS/TARGETARCH 等平台变量所以在 Dockerfile 里尽量用这些内置变量RUN CGO_ENABLED0 GOOS$TARGETOS GOARCH$TARGETARCH go build ...手动硬编码GOOSlinux GOARCHamd64虽然也能工作但在多架构构建场景下会用错误平台的二进制打包服务启动必然失败。这是我在实际项目里踩过的一个真实坑后面问题排查章节会再提到。5. 常见问题与排查技巧实录5.1 问题表多阶段构建常见报错速查为了让排查效率更高我把这些年遇到的多阶段构建相关问题整理成一张速查表按“报错现象—原因—解决方案”的格式呈现。这张表你可以直接打印出来贴在工位旁边报错现象常见原因解决方案COPY --frombuilder ...报failed to compute cache key阶段名写错或该阶段不存在于当前 Dockerfile检查AS builder的命名是否和COPY --frombuilder一致注意大小写构建时提示unable to prepare context构建上下文存在不可访问的文件或路径过大加上.dockerignore排除不需要的目录并用docker build .时确认当前目录正确exec: /app/app: permission denied运行的二进制没有可执行权限或者从非 Linux 环境编译导致格式不对在 Dockerfile 里RUN chmod x /app/app或构建时加--chmodx同时确认编译平台是目标平台standard_init_linux.go: exec format error架构不匹配比如在 arm64 上跑 amd64 的二进制用file命令检查二进制架构在构建命令里指定--platform并在 Go 构建时使用$TARGETOS/$TARGETARCH/bin/sh: 1: ./app: not found动态链接库缺失常见于 scratch 下跑动态链接的二进制使用ldd检查动态链接依赖改为FROM alpine或slim镜像并安装所需运行库npm/pip/go 依赖下载慢或失败网络原因或镜像源不可达更换国内可访问的包管理器源或配置 registry mirrorfailed to solve: rpc error: ...BuildKit 后端异常常见于磁盘空间不足、并发构建过多docker system prune清理无用镜像/缓存重启 Docker daemon或检查磁盘空间构建出的镜像仍然很大最后的运行阶段没有精简基础镜像或 COPY 了整个构建上下文确认最后一个FROM是否使用 slim/alpine确认是否只 COPY 了产物目录COPY --fromnginx:1.25 ...拉取失败镜像标签不存在、网络不通或镜像仓库被墙先手动docker pull nginx:1.25验证检查仓库地址和网络策略mysql/redis等容器启动失败数据目录权限不足容器内用户与宿主机挂载目录权限不匹配映射目录后在宿主机上 chmod 或 chown 到对应 UID或者启动命令里加权限修复参数docker desktop failed to start because virtualization support ...Windows 下虚拟化没有在 BIOS 开启或 Hyper-V / WSL2 没有启用进入 BIOS 开启 AMD-V/Intel VT-x控制面板启用 Hyper-V 和“适用于 Linux 的 Windows 子系统”然后重启5.2 排查思路实录一次 Go 服务的 “not found” 定位我有一次在客户服务器上部署 Go 服务镜像构建特别顺利启动直接报./app: No such file or directory。这个报错很有意思——文件明明在路径也正确为什么说找不到排查步骤是这样的先进入容器执行ls -l /app文件确实存在权限也是可执行的。手动执行/app依然报No such file or directory。突然意识到这可能是动态链接库找不到导致的。在宿主机上对二进制执行file app输出dynamically linked (uses shared libs)确认它是动态链接。我又在本机的 Ubuntu 环境里ldd app看到依赖了libc.so.6、ld-linux-x86-64.so.2。而容器是scratch里面什么都没有。解决方案有两步第一步在编译阶段增加CGO_ENABLED0 GOOSlinux确认file app输出变成statically linked第二步如果项目强制依赖 CGO就换alpine作为运行基础镜像。这个经历给我的一个深刻经验是多阶段构建的“精简”是把双刃剑越小的运行环境越要提前确认二进制或应用的静态依赖情况。没有 shell 的 scratch 给了你极限的体积但排查问题的手段也更有限。还有一种很别扭的情况是在 macOS 上交叉编译 Linux 二进制本地编译通过放进容器也能跑但偶尔网络层异常。后面查资料发现是因为CGO_ENABLED1时编译出的二进制混入了本机 clang 的库导致在容器内解析 DNS 时行为不一致。强制CGO_ENABLED0后问题彻底消失。所以我现在做 Go 项目编译时只要运行环境没有硬性 CGO 需要一律打包成静态二进制。5.3 关于缓存失效的排查docker build的层缓存很智能但偶尔也有“明明该命中却没命中”的困扰。多阶段构建下的缓存失效原因我总结过几类依赖文件频繁变化package-lock.json、go.mod只要有改动依赖安装层就必然重新执行。这是正常行为但如果你希望“改一行依赖文件只影响依赖层”请确保 lockfile 里不包含时间戳/本地路径等不稳定信息。COPY 了不该 COPY 的目录如果你COPY . .放在依赖安装前面那么任何文件变更都会导致之后的层全部失效。这是新手最常见的缓存杀手。基础镜像 tag 漂移如果 Builder 阶段使用node:latest、golang:latest每次构建拉取到的基础镜像都可能是新版本层缓存基本不生效而且可复现性差。固定到精确版本如golang:1.21.9-alpine3.19会让缓存命中率高很多。BuildKit 缓存挂载目录没有统一使用RUN --mounttypecache时cache 的有效性和 cache target 路径相关。如果同一条命令在不同阶段用了不同 target缓存是没办法共享的。排查缓存失效问题时最重要的是先分清“层缓存”和“上下文缓存”。层缓存命中与否可以在构建日志里看CACHED关键字上下文缓存本质是 Docker 在发送上下文之前的临时文件和远程缓存由 BuildKit 管理一般不需要人工干预。5.4 我在运行时环境踩到的其他坑除了二进制动态链接的问题还有一些和小型基础镜像相关的坑值得提前知道时区问题alpine默认 UTC 时间时区数据只有/usr/share/zoneinfo下有极少数条目。如果你的日志需要显示本地时间建议在 Dockerfile 里用环境变量TZAsia/Shanghai或者从 builder 拷贝时区文件。scratch 镜像则必须自己拷。CA 证书缺失用 scratch 镜像跑 Go/Python 等访问 HTTPS 接口的程序报证书错误很正常因为根本没有证书链。解决方式是从带证书的基础镜像拷贝我在 Go 场景已经演示过了。DNS 解析问题有些迷你基础镜像里没有/etc/resolv.conf或缺少解析器。如果你的应用在容器里访问外部服务时解析失败检查一下基础镜像的网络配置或者换成更完整的镜像。非 root 用户的 home 目录不存在很多应用启动时会尝试读取用户 home 目录下的配置比如.netrc、.ssh。如果你创建了普通用户但没设置 HOME很多库会静默失败。建议在 Dockerfile 里显式设置ENV HOME/home/appuser WORKDIR $HOME构建缓存里的存量数据导致测试误判如果你在 builder 阶段执行了RUN go test ./...并且依赖层命中了旧缓存那么测试跑的还是旧的源码结果。需要把测试命令放到“源码 COPY”之后的层才能保证测试时效性。6. 结合 Docker 安装与日常使用的经验补充既然本文里的实操都离不开一个能正常构建的 Docker 环境我再把这几天的排查经验里最实用的几条安装和日常运维心得也放进来避免你卡在第一步。6.1 Windows 上 Docker Desktop 启动失败怎么办virtualization support not detected、docker desktop failed to start because virtualisation support wasnt detected是 Windows 上最常见的启动失败提示。它本质上是检测不到 CPU 的虚拟化支持或者虚拟化功能处于禁用状态。我建议按顺序排查重启进入 BIOS/UEFI找到Intel Virtualization TechnologyIntel 平台或SVM ModeAMD 平台改为 Enabled保存退出。Windows 功能里勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”以管理员身份运行 PowerShell 并启用 WSL 2 功能。安装/更新 WSL2 内核执行wsl --update。重启电脑后打开 Docker Desktop确认任务栏的鲸鱼图标不再转圈报错。如果日志里报的是failed to connect to the docker api at npipe:////./pipe/dockerDesktopLinuxEngine多半是 Docker 引擎没有起来可以重置 Docker 引擎数据在 Docker Desktop 的 Troubleshoot 页面或者直接退出 Docker Desktop 后重新打开。注意重置会清掉本地已有的镜像和容器。6.2 一台 Linux 服务器的日常 Docker 打理在 Linux 上装完 Docker 后最影响日常体验的其实就是几件事定期清理孤儿资源。构建多阶段镜像时如果反复改宿主机上会有很多悬空镜像和 build cache。定时执行docker system prune -af这个命令会删掉所有未使用的镜像和构建缓存空间释放立竿见影。但注意它也会清理掉你手头停掉的容器、网络和匿名卷对本地调试不友好所以我一般只在磁盘亮红时才跑。镜像下载慢。这个老生常谈的问题我补一个从国内到国外都通用的思路可以在 Docker daemon 配置 registry mirror也可以配置镜像仓库的 HTTP 代理再配合多阶段构建把镜像基础层体积降下来镜像是中午拉还是晚上拉基本就不焦虑了。权限问题。很多 Linux 新手第一次跑docker命令会收到 permission denied因为当前用户不在 docker 组里。可以执行sudo usermod -aG docker $USER然后重新登录或执行newgrp docker生效。要注意加 docker 组等于给用户 root 级别的容器控制权限在多人共享的服务器上要谨慎。6.3 结合 MySQL、Redis、GitLab 等多容器场景的镜像管理思路从热词里可以看到很多人在部署 MySQL 8.0、Redis 主从、GitLab、KodBox 等中间件或应用。这些场景虽然不直接属于“多阶段构建”但它们会把镜像管理的复杂度放大——一旦镜像多了体积问题、启动问题、依赖问题都会同步放大。我对这类多容器应用部署的建议是每个中间件都尽量选择官方镜像或长期维护的镜像并且在 Compose 文件里固定版本 tag不要用 latest。比如services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: change-me volumes: - mysql-data:/var/lib/mysql redis: image: redis:7-alpine command: [redis-server, --appendonly, yes] gitlab: image: gitlab/gitlab-ce:16.11.0-ce.0 hostname: gitlab.example.com ports: - 8022:22 - 8043:443 - 8080:80如果你的业务自研服务也想要达到中间件镜像那样的精简度多阶段构建就是那个最佳抓手。甚至更进一步你可以效仿 GitLab 官方的做法把代码、配置、证书、日志目录全部通过 volume 挂载出来镜像里只保留程序本体让镜像升级和回滚都变得非常轻量。7. 一点个人体会在我参与过的项目里从“一个镜像 800MB”到“一个镜像 15MB”的转变往往只需要一次多阶段构建的重写。技术含量不高但带来的效率提升非常明显构建时间缩短、推送变快、磁盘占用下降、安全扫描干净团队成员之间同步镜像也痛快很多。有朋友问过我说多阶段构建会不会把 Dockerfile 写复杂了我的看法是多阶段构建不是复杂度它是对复杂度更清晰的管理。你只是把一个原本必须靠外部脚本才能做好的事情收编到了 Dockerfile 本身里让构建流程从“给你一堆手工步骤”变成了“给我一份描述文件”。如果你还没开始用最推荐的做法很简单拿一个现有的服务先记录当前镜像体积再照着文中的示例重写 Dockerfile构建一次看看结果。任何语言、任何框架都可以用同样的逻辑套。等你用顺手了多半就回不去单阶段构建那种写法了。
Docker多阶段构建实战：从原理到镜像瘦身与构建缓存优化
1. 为什么我劝你早点用上多阶段构建很多朋友第一次接触 Docker 都是先学会写一个简单的 Dockerfile拉一个基础镜像把代码 COPY 进去再 RUN 几条安装命令最后 EXPOSE 一个端口完事。这种写法在跑通项目的阶段完全够用但一旦项目开始交付、上生产环境痛点就马上出来了。最大的痛点就是镜像体积。我见过一个 Java 后端服务开发机打包出来的 JAR 才 80MB结果 Dockerfile 用FROM maven:3.8-jdk-11做基础镜像再把源码直接 COPY 进去构建最后构建出来的镜像居然有将近 800MB。800MB 是什么概念你推送到镜像仓库要好几分钟在服务器上拉取也要好几分钟带宽占用大不说万一同时部署好几个服务磁盘空间直接报警。更尴尬的是这 800MB 里真正运行时的 Java 程序只有 80MB剩下 700 多 MB 全是编译工具、依赖缓存和中间产物这些在容器跑起来之后一点用都没有。第二个痛点也很要命构建环境的安全风险。用一个大而全的基础镜像做运行时意味着你的生产容器里装着编译器、构建工具、各种源码文件。如果镜像被拉下来做安全扫描这些组件很容易暴露高危漏洞如果应用被攻破攻击者甚至可以基于容器里的编译工具做进一步的横向操作。简单说你在生产环境里塞了一堆完全不该存在的东西。多阶段构建multi-stage build就是冲着这两个痛点去的。它的核心思路特别朴素构建过程用功能完整的大镜像构建产物拷贝到一个干净的小镜像里最后只有小镜像被打包分发。整个过程写在一个 Dockerfile 里不依赖外部的 CI 脚本也不需要维护两套配置文件。这篇文章我会从多阶段构建的原理讲起逐步演示 Go、Node.js、Java 三种主流场景的完整 Dockerfile 写法再讲构建缓存、ARG 传参、平台兼容、镜像瘦身这些进阶操作最后把我在实际项目中踩过的坑和排查思路整理成一份速查表。不管你是刚接触 Docker 的新手还是已经在生产环境用了一段时间、想进一步优化镜像体积的开发者这篇文章应该都能给你一些可直接落地的参考。为了方便复现我先说明一下环境和基础操作。本机为 Windows 11已安装 WSL2 后端但本文所有 Dockerfile 也能在 macOS、Linux 及裸机 docker 上直接运行。如果你的 Docker 还没装好或者启动时报错我建议先检查两件事Windows 上确认 BIOS 里虚拟化已开启WSL2 终端里执行wsl -l -v能看到 docker-desktop 分发版Ubuntu/CentOS 上就在终端执行docker info确认 Client 和 Server 都已正常。下面的内容默认你的docker version和docker compose version都输得出信息。2. 多阶段构建的核心思路与设计逻辑2.1 从单阶段构建的“一条龙”说起先看一个典型的单阶段构建 Dockerfile以 Node.js 项目为例FROM node:18 WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build EXPOSE 3000 CMD [npm, start]这个 Dockerfile 的问题在哪里它把依赖安装、源代码拷贝、构建、运行全部混在一个镜像里了。node:18是一个完整的开发环境镜像自带了 npm、npx、编译链等工具体积本身就超过了 1GB。你最终分发出去的镜像既有 node_modules 里几百 MB 的依赖包又有构建过程中生成的临时文件还有完整的开发工具链。逻辑上这相当于你在搬家的时候不但把家里用的家具搬过去了还把装修用的电锯、油漆桶、脚手架也一起搬过去了。家具只需要用一次但装修工具永远留在新家里占地方第一次可能感受不到等镜像多起来、团队成员多起来每个人本地都要拉这几百 MB 的东西问题就会被无限放大。单阶段构建还有一种常见情况运行环境需要的东西和构建环境需要的东西不一样。比如 C 语言项目要编译出二进制文件编译需要 gcc、make、各类头文件但运行时只靠一个动态链接的二进制文件就够了比如 Java 项目编译需要 JDK 和 Maven运行时只需要 JRE比如前端项目构建需要 Node.js但最终产物只是静态文件甚至连 Nginx 都可以用现成的镜像。这种“构建和运行环境分离”的需求单阶段构建几乎没法优雅满足传统的做法是写两个 Dockerfile再靠 CI 脚本去串联维护成本很高。2.2 多阶段构建解决了什么多阶段构建的核心机制非常简单一个 Dockerfile 里可以有多个FROM指令每个FROM开启一个新的构建阶段。后面的阶段可以通过COPY --from阶段名或序号从前面的阶段拷贝文件而前面的阶段就是“构建使用的环境”最后一个阶段才是“实际产出的镜像”。这么说可能还是有点抽象下面是一个最简单的 Go 语言示例# 阶段一编译 FROM golang:1.21 AS builder WORKDIR /build COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED0 GOOSlinux go build -o myapp . # 阶段二打包运行 FROM alpine:3.19 WORKDIR /root COPY --frombuilder /build/myapp . EXPOSE 8080 CMD [./myapp]这个 Dockerfile 里有两个阶段golang:1.21阶段只做一件事拉取依赖、编译出二进制。alpine:3.19阶段只做一件事把编译好的二进制文件拷过来然后运行它。最终镜像不包含 Go 编译器、不包含源代码、不包含任何依赖缓存只有瘦小的 Alpine 系统和那一个二进制文件。在真实项目中这个镜像的实际大小大概在 10~20MB 之间这和使用标准golang:1.21镜像构建且不做任何优化的版本相比体积缩小 10 倍以上。理解了这句话你基本就把握住多阶段构建的七成了前面的阶段是加工车间后面的阶段是成品房车间里的工具一概不带走。2.3 为什么这条路径值得选权衡与取舍同为镜像瘦身方案多阶段构建还常被拿来和另几条路对比我列一下自己在调研和实践中看到的真实差异用docker-slim做自动瘦身这个工具能基于运行行为自动生成精简镜像但生成过程比较玄学依赖动态分析遇到启动后不怎么写入文件的应用容易误删而且对不同项目的结果一致性不太好保证。我的体会是它适合拿来处理那些你拿不到源码的历史镜像如果源码就在你手里多阶段构建的控制力要强得多。手动“编译后清理”就是在同一条 RUN 命令里先安装构建工具编译完再删掉。问题在于镜像的分层机制删除操作如果不在同一层里完成就不会真正减小镜像体积如果你把 apt 安装和 rm 拆成两条 RUN那些包还是会在镜像历史里占空间。多阶段构建把这个问题从根上绕开了因为构建工具根本不会进入最终阶段。把构建放在宿主机只把产物打进镜像这种方式本质上是在 Dockerfile 之外手工复刻了多阶段构建里的“builder”阶段但容易把宿主机环境差异带进来比如 glibc 版本不一致、平台架构不一致而且 CI 脚本要额外维护。多阶段构建完全在 Dockerfile 描述范围内完成换任何人、任何机器都能以同样的方式构建可复现性更高。所以我的经验是如果一个项目需要在容器里做构建能上多阶段构建就尽量上它应该是默认选项而不是需要特别理由的优化项。3. 核心细节解析与实操要点3.1 阶段命名与 COPY --from 的正确姿势多阶段构建里有两个特别容易忽略的小细节阶段命名和COPY --from的写法。阶段默认的标识是序号从 0 开始。也就是说上面的 Go 例子里golang阶段是第 0 阶段alpine阶段是第 1 阶段。你在后面的阶段里可以写COPY --from0 /build/myapp /root/myapp。序号写法有个问题如果你在中间插入了新的阶段所有的序号都会变Dockerfile 的可维护性直线下降。所以凡是超过两个阶段或者有插入新阶段可能的项目我都建议给阶段起一个可读的名字。方法是在FROM后面加上AS关键字FROM golang:1.21 AS builder然后在拷贝的时候用名字引用COPY --frombuilder /build/myapp /root/myapp这样不管阶段顺序怎么调整、上面新增多少阶段只要AS builder这个名字不变下面的拷贝逻辑就永远正确。另外注意一个容易踩的坑COPY --from不仅能从前面的阶段拷贝文件还能从“外部镜像”拷贝文件。比如你能从nginx:1.25镜像里直接拷贝配置文件而不需要在当前构建过程中再拉取那个镜像。这在实际项目中用途很多最常见的做法是COPY --fromnginx:1.25 /etc/nginx/nginx.conf /etc/nginx/nginx.conf这段指令在构建时会把nginx:1.25镜像里的nginx.conf文件拷贝到当前镜像对应路径相当于一个“文件级引用”不必继承整个镜像的基础层。需要注意此时 Docker 会去拉取这个镜像如果本地没有它会先从远程仓库下载然后再提取文件。好处是你不用自己写一份配置文件也无需单独维护一个配置文件镜像。3.2 构建上下文与 .dockerignore 配合多阶段构建能在最终镜像里缩小体积但有一个前置条件容易被忽略构建上下文的大小。所谓构建上下文就是你执行docker build时指定的那个目录通常是.。Docker 会先把整个上下文目录打包发送给 Docker 守护进程然后才能执行 Dockerfile 里的指令。如果你的项目目录里有一个巨大的node_modules、target、dist、.git每次构建这些都会被打包发送。这会带来两个实际问题构建前等待时间变长如果上下文里包含敏感信息比如.env文件、密钥文件它们还有可能被留在镜像历史中。多阶段构建不会自动帮你过滤上下文。所以我建议在任何项目里都保持一个基本的.dockerignore文件至少排除掉这些内容.git .gitignore node_modules npm-debug.log target dist build *.log .env .env.* Dockerfile .dockerignore这个文件的作用是构建时 Docker 会跳过这些路径不把它们发送到守护进程。看着很不起眼但在 monorepo 或大型项目里它能显著加快构建速度。另外一个很容易被忽略的点.dockerignore对构建上下文的大小优化只影响“发送阶段”不影响你在 Dockerfile 里实际能 COPY 什么。如果你在.dockerignore里排除了node_modules然后又写了COPY node_modules /app/node_modules构建时会报错找不到文件所以“排除”和“使用”边界要分清。3.3 基础镜像选型与包管理器源多阶段构建中基础镜像的选择会直接影响最终镜像的体积和安全性。让我从几个常用方向分析一下官方镜像 vs 精简镜像官方镜像如node:18、python:3.11、golang:1.21适合作为 builder 阶段的基础镜像。它们功能完整有什么依赖问题基本都能在官方镜像里找到CLI 工具齐全调试省心。但最终运行阶段我通常不会直接用它们而是换用 Alpinealpine:3.19、Distrolessgcr.io/distroless/*或直接基于scratch。Alpine 镜像目前最主流的精简镜像选择体积约 5MB基于 musl libc包管理用apk。缺点是如果你编译的程序是动态链接到 glibc 的直接放到 Alpine 里会报 “not found”。这个坑我后面专门讲。Distroless 镜像Google 提供的“只包含运行时必要内容”的镜像里没有 shell、没有包管理器、没有系统库以外的东西安全等级更高但进容器调试基本不可能没有/bin/sh。它适合你已经很稳定、几乎不需要在容器里敲命令的服务。scratch空镜像适合纯静态二进制比如 Go 的CGO_ENABLED0编译结果。注意scratch不是一个真正的镜像仓库它只是一个构建起点FROM scratch后你的镜像里除了自己 COPY 进去的东西什么都不会有。镜像源调整技巧如果你在国内网络环境构建官方镜像源往往拉不动或者慢到怀疑人生。我常用的两个办法先在宿主机或 Dockerfile 里配好国内镜像源比如 alpine 的mirrors.aliyun.com、Ubuntu 的mirrors.tuna.tsinghua.edu.cn、npm 的registry.npmmirror.com在 Dockerfile 里加一行RUN sed -i s#dl-cdn.alpinelinux.org#mirrors.aliyun.com#g /etc/apk/repositories之类的替换逻辑。另一个办法是给 Docker daemon 配 registry mirrorDaemon 层面统一走加速器这样在任何镜像仓库的拉取都会快不少。从我的实践看镜像源的选择要根据团队部署环境来定私有化交付场景外网下载经常受限提前把 base image 镜像和 Builder 镜像的大版本固定下来比如不用node:latest而是node:18.20.2-alpine比日常省心得多。3.4 多阶段构建下依赖安装的取舍依赖安装对多阶段构建有直接影响主要有两个方向要注意锁文件和安装策略。先说说锁文件。无论 npm 的package-lock.json、pip 的requirements.txt、Go 的go.sum还是 Java 的pom.xml或 maven wrapper都建议提前单独 COPY 进构建阶段执行依赖安装再拷贝源码。这样能利用 Docker 的层缓存只要依赖文件没变依赖安装层就直接用缓存不用每改一行代码就重新编译一遍项目。这个细节处理好了构建速度能快上好几倍。然后说说安装策略。Node.js 项目生产依赖和开发依赖要分清依赖安装在 builder 阶段执行你最终只需要拷贝dist或者build目录以及运行阶段必要的依赖。如果项目体积非常大也可以把“最终运行依赖”再单独 COPY 一次常见的写法是# 阶段一构建 FROM node:18 AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 阶段二生产依赖精简 FROM node:18-alpine AS deps WORKDIR /app COPY package*.json ./ RUN npm ci --omitdev # 阶段三运行 FROM node:18-alpine WORKDIR /app COPY --frombuilder /app/dist ./dist COPY --fromdeps /app/node_modules ./node_modules EXPOSE 3000 CMD [node, dist/index.js]这样生产镜像里没有 devDependencies也不会把整个源码目录都拷进去。注意这里中间多了一个deps阶段它和builder阶段的区别就是只安装生产依赖避免把开发依赖带进最终镜像。4. 实操过程与核心环节实现4.1 场景一Go 服务编译与 scratch 运行Go 也许是多阶段构建里最顺的场景因为 Go 本身能把依赖和运行时静态编译到一个二进制文件里。配合scratch或alpine产物镜像可以做到几 MB 到十几 MB。一个生产可用的 Dockerfile 长这样# syntaxdocker/dockerfile:1.7 FROM golang:1.21 AS builder WORKDIR /src # 先拷贝 go.mod 和 go.sum利用缓存 COPY go.mod go.sum ./ RUN go mod download # 拷贝全部源码并编译 COPY . . RUN CGO_ENABLED0 GOOSlinux go build -trimpath -ldflags-s -w -o /out/app . FROM scratch COPY --frombuilder /out/app /app EXPOSE 8080 ENTRYPOINT [/app]这里有几点要特别说明CGO_ENABLED0会强制关闭 CGO。这样编译出的二进制不会动态链接 glibc放到没有 glibc 的scratch镜像里才能直接运行。如果你用到了需要 CGO 的库比如某些 SQLite 驱动、网络库编译期会有兼容性问题那时就不能用 scratch改换成alpine并安装对应运行库。-trimpath会去掉编译信息里的本地路径-ldflags-s -w会去掉符号表和调试信息能明显减小二进制体积。一个是减少泄露代码路径一个是压缩体积两个建议在生产构建里都加上。如果你的 Go 程序需要读取系统证书比如访问 HTTPS 接口scratch里没有 CA 证书需要从 builder 或者其他基础镜像里额外拷贝COPY --frombuilder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/另外很多 Go 服务需要时区数据scratch 里也没有可以从 builder 里拷贝/usr/share/zoneinfo或只拷贝需要的时区文件。最后确认产物到底能否在 scratch 上跑最好先在本机验证一下动态链接信息。构建完镜像后进入一个普通容器执行ldd myapp如果输出里面有libc.so.6、ld-linux-x86-64.so.2这类路径说明它依赖 glibc不能直接用 scratch必须换成alpine并安装 musl 兼容层或者直接用 Ubuntu/Debian 的 slim 镜像作为运行基础。4.2 场景二Node.js 前端/后端产物与 Nginx前端项目的目标产物是静态文件。用 Node 镜像构建完成后把dist目录拷贝到 Nginx 镜像里就可以了运行阶段完全不需要 Node。# 构建阶段 FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 运行阶段 FROM nginx:1.25-alpine COPY --frombuilder /app/dist /usr/share/nginx/html # 如果你有自定义的 nginx.conf也一起拷贝 # COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]最终这个镜像只包含 Nginx 和静态文件体积大概在 50MB 左右而不带多阶段优化时可能超过 1GB。需要注意如果你用了 SPA单页应用路由模式比如 Vue Router 的 history 模式Nginx 需要配置 try_files否则刷新页面会 404。还有一点前端项目里如果有.env之类的环境变量文件建议让它直接留在构建上下文里被排除运行时如果需要动态配置环境变量应走 Nginx 的 envsubst 模板方案而不是把文件打进镜像。4.3 场景三Java 后端项目中 Maven 与 JRE 分离Java 生态里多阶段构建特别有价值因为 JDK 和 Maven 的体积非常大这两者都不该出现在运行时里。理想情况下构建阶段用 JDK Maven运行阶段用 JRE 或者更精简的 JRE-based alpine 镜像。以 Spring Boot 项目为例# syntaxdocker/dockerfile:1.7 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build # 利用 maven 依赖缓存 COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests FROM eclipse-temurin:17-jre-alpine WORKDIR /app RUN addgroup -S appgroup adduser -S appuser -G appgroup COPY --frombuilder /build/target/myapp-*.jar app.jar USER appuser EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]几个细节解释一下先只拷贝pom.xml再执行mvn dependency:go-offline目的是预下载依赖利用 Docker 的层缓存。以后只要不改pom.xml这层就不会失效构建速度会快很多。Spring Boot 的 fat JAR 可以通过java -jar运行。如果你用了 Jib 或者 Spring Boot 的 layered jar 模式还可以进一步拆分层级把依赖和业务代码分开让镜像层缓存更精细。建议在 Dockerfile 里创建非 root 用户并切换。镜像默认以 root 运行容器进程这在生产环境里风险很高。多阶段构建正好给了你一个很自然的机会在运行阶段创建普通用户。4.4 场景四多阶段 Docker Compose 的联动用法多阶段构建不是只能单独配合docker build使用它同样适合在docker compose里做一键编排这在本地环境和 CI 环节非常顺手。一个常见的 Compose 文件片段长这样services: web: build: context: . target: runner ports: - 8080:8080这里的target: runner表示只构建 Dockerfile 中名为runner的那个阶段。如果你的 Dockerfile 只有一个运行阶段这个参数可不写但当 Dockerfile 里有多条阶段路径比如既有测试阶段又有编译阶段又有最终运行阶段你就可以在本地构建时只选runner在 CI 流水线里先跑tester阶段做静态检查或单元测试。一个更典型的联动是本地开发用 volume 挂载源码做热更新生产部署用多阶段构建出精简镜像。这种情况下你只需要一个 Dockerfile开发环境用docker compose up配合挂载生产环境用docker compose build或者 CI 里直接docker build完全不需要维护第二套配置。4.5 构建缓存与层缓存优化策略多阶段构建已经解决了“最终镜像太大”的问题但如果你不注意层缓存的利用率构建过程本身可能会非常慢。我把常用的缓存优化策略总结成几条可以逐条对照的清单依赖锁文件单独 COPY 并安装业务代码最后 COPY。这是最基础也最有效的一层缓存。对于有 lockfile 的项目npm、pip、go优先使用锁文件而不是手写模糊匹配版本。这样能保证可复现性也让缓存更容易命中。避免在一条 RUN 命令里写“先下载再删除”的步骤。虽然逻辑上没问题但它会把缓存的操作也写进层里面层缓存命中率会变差。如果你真的要用这种写法至少要把“下载依赖”和“清理缓存”分开并考虑通过网络代理或者其他方式缓存依赖包。官方 Docker 从 BuildKit 开始支持RUN --mounttypecache用在包管理器的缓存目录上很有效果。下面是一个真实可用示例FROM node:18-alpine AS builder WORKDIR /app RUN --mounttypecache,target/root/.npm \ npm ci它会把 npm 的缓存目录挂载为构建持久化缓存即使 Dockerfile 的其他层发生变化只要依赖源没变化依赖下载就不会重新走网络。这个能力在docker buildx和docker build --progressplain等 BuildKit 模式下默认开启。尽可能把“经常变化的”步骤往后放把“不常变化的”步骤往前放。这听起来像废话但实际很多人在写 Dockerfile 时会不自觉地把源码 COPY 放在依赖安装前面导致每次改代码都触发依赖重装构建时间直接翻倍。4.6 BuildKit 与构建参数ARG注入Docker 从 18.09 开始引入了 BuildKit 构建引擎从 23.0 起它已经是默认构建器。BuildKit 带来几个对多阶段构建特别友好的能力并行阶段构建、更好的层缓存包括跨 Dockerfile 的缓存复用、RUN --mounttypecache等高级语法。要在 Dockerfile 里使用这些高级语法第一行一般要加上# syntaxdocker/dockerfile:1.7这不是注释它是构建器识别的指令用来指定 Dockerfile 前端解析器的版本。没有这行也能用基本的多阶段构建但一些新特性比如RUN --mount可能不会启用。我的建议是只要是新建的 Dockerfile就把这一行放在最上面。ARG 注入是多阶段构建里非常实用但容易被忽略的能力。你可以在 Dockerfile 里定义参数然后通过docker build --build-arg传入# syntaxdocker/dockerfile:1.7 ARG APP_VERSION1.0.0 ARG BUILD_ENVproduction FROM golang:1.21 AS builder ARG APP_VERSION RUN echo Building version $APP_VERSION ...执行构建时docker build --build-arg APP_VERSION2.1.0 -t myapp .这样同一个 Dockerfile 就能在不同环境构建出不同版本的镜像不需要为版本号维护多个 Dockerfile。注意 ARG 的作用域问题基础阶段定义的 ARG不会自动传递给其他阶段。你需要在每一个需要用到它的阶段里重新声明一次即使只是透传。另外构建参数不要和运行环境变量混淆。构建参数只在构建过程中生效不会出现在最终镜像的运行环境变量里。如果你需要运行时配置比如数据库地址、密钥等请通过docker run -e或 Compose 里的environment注入。构建参数适合版本号、构建模式、资源地址这类“构建期变量”。4.7 多架构镜像与构建经验如果你需要同时产出linux/amd64和linux/arm64的镜像比如苹果芯片的 Mac 和 x86 服务器并存多阶段构建同样适用。核心工具是docker buildx它是 Docker BuildKit 的扩展命令。首先启用并创建构建器docker buildx create --name mybuilder --use docker buildx build --platform linux/amd64,linux/arm64 -t yourname/myapp:latest --push .这里有几个前提条件镜像仓库支持 multi-arch manifest目前主流仓库基本都支持builder 节点上配置了对应的模拟器或原生构建节点。Docker Desktop 自带 QEMU 模拟可以在本地直接构建多个平台的镜像。在多阶段构建 多架构的场景里两个特别值得注意的地方阶段缓存要分开命名否则不同架构的构建可能互相污染缓存。BuildKit 在缓存 key 里会自动带上平台信息一般不会有问题但如果你手动设置了很多--mounttypecache缓存挂载目标路径最好保持一致让不同平台可以复用公共缓存。编译参数要带上目标平台。还是以 Go 为例如果在 arm64 的机器上编译 amd64 镜像光有CGO_ENABLED0不够还需要GOARCHamd64。用 buildx 构建时它会自动注入 TARGETOS/TARGETARCH 等平台变量所以在 Dockerfile 里尽量用这些内置变量RUN CGO_ENABLED0 GOOS$TARGETOS GOARCH$TARGETARCH go build ...手动硬编码GOOSlinux GOARCHamd64虽然也能工作但在多架构构建场景下会用错误平台的二进制打包服务启动必然失败。这是我在实际项目里踩过的一个真实坑后面问题排查章节会再提到。5. 常见问题与排查技巧实录5.1 问题表多阶段构建常见报错速查为了让排查效率更高我把这些年遇到的多阶段构建相关问题整理成一张速查表按“报错现象—原因—解决方案”的格式呈现。这张表你可以直接打印出来贴在工位旁边报错现象常见原因解决方案COPY --frombuilder ...报failed to compute cache key阶段名写错或该阶段不存在于当前 Dockerfile检查AS builder的命名是否和COPY --frombuilder一致注意大小写构建时提示unable to prepare context构建上下文存在不可访问的文件或路径过大加上.dockerignore排除不需要的目录并用docker build .时确认当前目录正确exec: /app/app: permission denied运行的二进制没有可执行权限或者从非 Linux 环境编译导致格式不对在 Dockerfile 里RUN chmod x /app/app或构建时加--chmodx同时确认编译平台是目标平台standard_init_linux.go: exec format error架构不匹配比如在 arm64 上跑 amd64 的二进制用file命令检查二进制架构在构建命令里指定--platform并在 Go 构建时使用$TARGETOS/$TARGETARCH/bin/sh: 1: ./app: not found动态链接库缺失常见于 scratch 下跑动态链接的二进制使用ldd检查动态链接依赖改为FROM alpine或slim镜像并安装所需运行库npm/pip/go 依赖下载慢或失败网络原因或镜像源不可达更换国内可访问的包管理器源或配置 registry mirrorfailed to solve: rpc error: ...BuildKit 后端异常常见于磁盘空间不足、并发构建过多docker system prune清理无用镜像/缓存重启 Docker daemon或检查磁盘空间构建出的镜像仍然很大最后的运行阶段没有精简基础镜像或 COPY 了整个构建上下文确认最后一个FROM是否使用 slim/alpine确认是否只 COPY 了产物目录COPY --fromnginx:1.25 ...拉取失败镜像标签不存在、网络不通或镜像仓库被墙先手动docker pull nginx:1.25验证检查仓库地址和网络策略mysql/redis等容器启动失败数据目录权限不足容器内用户与宿主机挂载目录权限不匹配映射目录后在宿主机上 chmod 或 chown 到对应 UID或者启动命令里加权限修复参数docker desktop failed to start because virtualization support ...Windows 下虚拟化没有在 BIOS 开启或 Hyper-V / WSL2 没有启用进入 BIOS 开启 AMD-V/Intel VT-x控制面板启用 Hyper-V 和“适用于 Linux 的 Windows 子系统”然后重启5.2 排查思路实录一次 Go 服务的 “not found” 定位我有一次在客户服务器上部署 Go 服务镜像构建特别顺利启动直接报./app: No such file or directory。这个报错很有意思——文件明明在路径也正确为什么说找不到排查步骤是这样的先进入容器执行ls -l /app文件确实存在权限也是可执行的。手动执行/app依然报No such file or directory。突然意识到这可能是动态链接库找不到导致的。在宿主机上对二进制执行file app输出dynamically linked (uses shared libs)确认它是动态链接。我又在本机的 Ubuntu 环境里ldd app看到依赖了libc.so.6、ld-linux-x86-64.so.2。而容器是scratch里面什么都没有。解决方案有两步第一步在编译阶段增加CGO_ENABLED0 GOOSlinux确认file app输出变成statically linked第二步如果项目强制依赖 CGO就换alpine作为运行基础镜像。这个经历给我的一个深刻经验是多阶段构建的“精简”是把双刃剑越小的运行环境越要提前确认二进制或应用的静态依赖情况。没有 shell 的 scratch 给了你极限的体积但排查问题的手段也更有限。还有一种很别扭的情况是在 macOS 上交叉编译 Linux 二进制本地编译通过放进容器也能跑但偶尔网络层异常。后面查资料发现是因为CGO_ENABLED1时编译出的二进制混入了本机 clang 的库导致在容器内解析 DNS 时行为不一致。强制CGO_ENABLED0后问题彻底消失。所以我现在做 Go 项目编译时只要运行环境没有硬性 CGO 需要一律打包成静态二进制。5.3 关于缓存失效的排查docker build的层缓存很智能但偶尔也有“明明该命中却没命中”的困扰。多阶段构建下的缓存失效原因我总结过几类依赖文件频繁变化package-lock.json、go.mod只要有改动依赖安装层就必然重新执行。这是正常行为但如果你希望“改一行依赖文件只影响依赖层”请确保 lockfile 里不包含时间戳/本地路径等不稳定信息。COPY 了不该 COPY 的目录如果你COPY . .放在依赖安装前面那么任何文件变更都会导致之后的层全部失效。这是新手最常见的缓存杀手。基础镜像 tag 漂移如果 Builder 阶段使用node:latest、golang:latest每次构建拉取到的基础镜像都可能是新版本层缓存基本不生效而且可复现性差。固定到精确版本如golang:1.21.9-alpine3.19会让缓存命中率高很多。BuildKit 缓存挂载目录没有统一使用RUN --mounttypecache时cache 的有效性和 cache target 路径相关。如果同一条命令在不同阶段用了不同 target缓存是没办法共享的。排查缓存失效问题时最重要的是先分清“层缓存”和“上下文缓存”。层缓存命中与否可以在构建日志里看CACHED关键字上下文缓存本质是 Docker 在发送上下文之前的临时文件和远程缓存由 BuildKit 管理一般不需要人工干预。5.4 我在运行时环境踩到的其他坑除了二进制动态链接的问题还有一些和小型基础镜像相关的坑值得提前知道时区问题alpine默认 UTC 时间时区数据只有/usr/share/zoneinfo下有极少数条目。如果你的日志需要显示本地时间建议在 Dockerfile 里用环境变量TZAsia/Shanghai或者从 builder 拷贝时区文件。scratch 镜像则必须自己拷。CA 证书缺失用 scratch 镜像跑 Go/Python 等访问 HTTPS 接口的程序报证书错误很正常因为根本没有证书链。解决方式是从带证书的基础镜像拷贝我在 Go 场景已经演示过了。DNS 解析问题有些迷你基础镜像里没有/etc/resolv.conf或缺少解析器。如果你的应用在容器里访问外部服务时解析失败检查一下基础镜像的网络配置或者换成更完整的镜像。非 root 用户的 home 目录不存在很多应用启动时会尝试读取用户 home 目录下的配置比如.netrc、.ssh。如果你创建了普通用户但没设置 HOME很多库会静默失败。建议在 Dockerfile 里显式设置ENV HOME/home/appuser WORKDIR $HOME构建缓存里的存量数据导致测试误判如果你在 builder 阶段执行了RUN go test ./...并且依赖层命中了旧缓存那么测试跑的还是旧的源码结果。需要把测试命令放到“源码 COPY”之后的层才能保证测试时效性。6. 结合 Docker 安装与日常使用的经验补充既然本文里的实操都离不开一个能正常构建的 Docker 环境我再把这几天的排查经验里最实用的几条安装和日常运维心得也放进来避免你卡在第一步。6.1 Windows 上 Docker Desktop 启动失败怎么办virtualization support not detected、docker desktop failed to start because virtualisation support wasnt detected是 Windows 上最常见的启动失败提示。它本质上是检测不到 CPU 的虚拟化支持或者虚拟化功能处于禁用状态。我建议按顺序排查重启进入 BIOS/UEFI找到Intel Virtualization TechnologyIntel 平台或SVM ModeAMD 平台改为 Enabled保存退出。Windows 功能里勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”以管理员身份运行 PowerShell 并启用 WSL 2 功能。安装/更新 WSL2 内核执行wsl --update。重启电脑后打开 Docker Desktop确认任务栏的鲸鱼图标不再转圈报错。如果日志里报的是failed to connect to the docker api at npipe:////./pipe/dockerDesktopLinuxEngine多半是 Docker 引擎没有起来可以重置 Docker 引擎数据在 Docker Desktop 的 Troubleshoot 页面或者直接退出 Docker Desktop 后重新打开。注意重置会清掉本地已有的镜像和容器。6.2 一台 Linux 服务器的日常 Docker 打理在 Linux 上装完 Docker 后最影响日常体验的其实就是几件事定期清理孤儿资源。构建多阶段镜像时如果反复改宿主机上会有很多悬空镜像和 build cache。定时执行docker system prune -af这个命令会删掉所有未使用的镜像和构建缓存空间释放立竿见影。但注意它也会清理掉你手头停掉的容器、网络和匿名卷对本地调试不友好所以我一般只在磁盘亮红时才跑。镜像下载慢。这个老生常谈的问题我补一个从国内到国外都通用的思路可以在 Docker daemon 配置 registry mirror也可以配置镜像仓库的 HTTP 代理再配合多阶段构建把镜像基础层体积降下来镜像是中午拉还是晚上拉基本就不焦虑了。权限问题。很多 Linux 新手第一次跑docker命令会收到 permission denied因为当前用户不在 docker 组里。可以执行sudo usermod -aG docker $USER然后重新登录或执行newgrp docker生效。要注意加 docker 组等于给用户 root 级别的容器控制权限在多人共享的服务器上要谨慎。6.3 结合 MySQL、Redis、GitLab 等多容器场景的镜像管理思路从热词里可以看到很多人在部署 MySQL 8.0、Redis 主从、GitLab、KodBox 等中间件或应用。这些场景虽然不直接属于“多阶段构建”但它们会把镜像管理的复杂度放大——一旦镜像多了体积问题、启动问题、依赖问题都会同步放大。我对这类多容器应用部署的建议是每个中间件都尽量选择官方镜像或长期维护的镜像并且在 Compose 文件里固定版本 tag不要用 latest。比如services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: change-me volumes: - mysql-data:/var/lib/mysql redis: image: redis:7-alpine command: [redis-server, --appendonly, yes] gitlab: image: gitlab/gitlab-ce:16.11.0-ce.0 hostname: gitlab.example.com ports: - 8022:22 - 8043:443 - 8080:80如果你的业务自研服务也想要达到中间件镜像那样的精简度多阶段构建就是那个最佳抓手。甚至更进一步你可以效仿 GitLab 官方的做法把代码、配置、证书、日志目录全部通过 volume 挂载出来镜像里只保留程序本体让镜像升级和回滚都变得非常轻量。7. 一点个人体会在我参与过的项目里从“一个镜像 800MB”到“一个镜像 15MB”的转变往往只需要一次多阶段构建的重写。技术含量不高但带来的效率提升非常明显构建时间缩短、推送变快、磁盘占用下降、安全扫描干净团队成员之间同步镜像也痛快很多。有朋友问过我说多阶段构建会不会把 Dockerfile 写复杂了我的看法是多阶段构建不是复杂度它是对复杂度更清晰的管理。你只是把一个原本必须靠外部脚本才能做好的事情收编到了 Dockerfile 本身里让构建流程从“给你一堆手工步骤”变成了“给我一份描述文件”。如果你还没开始用最推荐的做法很简单拿一个现有的服务先记录当前镜像体积再照着文中的示例重写 Dockerfile构建一次看看结果。任何语言、任何框架都可以用同样的逻辑套。等你用顺手了多半就回不去单阶段构建那种写法了。 
