在开发环境里，我们常把编译器、包管理器、测试工具和应用源码放进同一个镜像，但生产容器真正需要的通常只有可执行文件、运行时依赖和少量配置。若直接沿用单阶段构建，不仅镜像臃肿，还可能把开发依赖、缓存文件甚至敏感凭据带入生产环境。Docker 多阶段构建通过“分阶段加工、按需复制”的方式，让构建环境与运行环境彻底分离，是优化镜像体积和降低依赖泄漏风险的重要手段。🚀

一、多阶段构建解决了什么问题

多阶段构建允许在同一个 Dockerfile 中使用多个 FROM 指令。每个 FROM 都会开启一个独立阶段，不同阶段可以使用不同基础镜像。前面的阶段负责下载依赖、执行测试和编译程序，最后阶段只接收明确指定的产物。Docker 的多阶段构建官方文档也强调，只有通过 COPY --from 显式复制的内容才会进入目标阶段。citeturn1search1

这与“安装完成后再删除工具”有本质区别。镜像由只读层组成，如果先在某一层写入文件，再在后续层删除，相关内容仍可能存在于历史层中。多阶段构建则让编译工具和临时文件停留在构建阶段，生产镜像从一个干净的基础镜像重新开始，从源头避免携带无关内容。

二、一个可落地的 Node.js 构建方案

以前端静态项目为例，第一阶段使用 Node.js 镜像安装依赖并生成 dist 目录，第二阶段使用轻量 Web 服务器镜像，仅复制构建结果：

FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine AS production
COPY --from=builder /app/dist /usr/share/nginx/html

这里将阶段命名为 builder 和 production，比使用数字序号更容易维护。即使以后调整阶段顺序，COPY --from=builder 的含义仍然清晰。生产镜像中不会包含 node_modules、npm、构建脚本和项目源码，只保留部署所需的静态文件与 Nginx 运行环境。📦

后端项目也可以采用相同思路。例如 Go 项目在 builder 阶段使用完整工具链生成静态二进制文件，运行阶段再选择 scratch 或满足程序需求的精简基础镜像；Java 项目可以在前一阶段使用 Maven 或 Gradle 打包，后一阶段仅保留 JRE 和最终制品。基础镜像不应只追求“小”，还要确认动态链接库、证书、时区数据和调试需求是否匹配。

三、利用缓存减少重复构建

多阶段构建优化的是最终镜像，而合理安排指令还能提升构建速度。以 Node.js 为例，应先复制 package.json 和锁文件并执行 npm ci，之后再复制业务代码。这样，普通源码变更不会立即使依赖安装层失效。Python、Java 等项目也应优先复制依赖清单，再复制变化更频繁的源码。

还应配置 .dockerignore，排除 .git、node_modules、测试报告、本地日志、编辑器配置和临时目录。这样既能减少发送给构建器的上下文，也能降低本地敏感文件被 COPY 进镜像的概率。需要注意的是，.dockerignore 不是秘密管理机制，密钥仍然不应保存在构建目录中。🧹

四、防范依赖与凭据泄漏

多阶段构建可以隔离大量开发依赖，但不能自动消除所有泄漏风险。最常见的错误，是通过 ARG 或 ENV 传递仓库令牌、云平台密钥和私有源密码。Docker 的构建密钥官方文档指出，构建参数和环境变量不适合传递秘密，应使用 BuildKit 的 secret mount 或 SSH mount，让凭据只在指定 RUN 指令执行期间临时可用。citeturn1search2

docker build --secret id=npmrc,src=$HOME/.npmrc .

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

这种方式不会要求把凭据复制到镜像文件系统，但构建命令仍需避免把秘密输出到日志。对于私有 Git 仓库，可使用 SSH mount，而不是把私钥写进 Dockerfile。还要警惕“复制范围过大”：若直接从 builder 阶段复制整个 /app，测试配置、源码映射、缓存和开发依赖仍可能进入生产镜像。更稳妥的做法是只复制明确的二进制文件、dist 目录或生产依赖目录。🔐

五、上线前的检查清单

• 检查阶段职责：编译、测试与运行阶段是否清晰分离。
• 限制复制范围：优先复制具体文件或产物目录，避免复制整个工作目录。
• 固定依赖版本：使用锁文件，并按团队策略固定基础镜像标签或摘要。
• 移除开发组件：确认最终镜像不包含编译器、测试框架、包管理缓存和源码。
• 保护构建秘密：使用 BuildKit secret mount 或 SSH mount，不在 ARG、ENV 和日志中暴露凭据。
• 采用非 root 用户：若基础镜像允许，应为应用创建低权限运行用户。
• 验证实际内容：检查镜像历史、文件系统、软件清单和漏洞扫描结果，而不是只比较镜像大小。
• 单独测试目标阶段：可通过 --target 构建指定阶段，便于在 CI 中执行测试或排查问题。

总结

Docker 多阶段构建的核心不是简单增加几个 FROM，而是建立清晰的交付边界：构建阶段可以复杂，生产阶段必须克制。通过按需复制产物、优化缓存顺序、缩小构建上下文，并配合 BuildKit 密钥挂载、非 root 运行和上线检查，可以同时减少无关依赖、降低泄漏风险并提升镜像可维护性。最终目标不是追求极端的小镜像，而是在运行完整、便于维护和安全可控之间取得平衡。✅