容器与云原生 / 系统课时
编写多阶段 Dockerfile
编写多阶段 Dockerfile
多阶段构建把“编译应用”和“运行应用”放进同一个 Dockerfile 的不同阶段,让编译器、开发依赖和中间文件停留在 Builder 中,最终镜像只保留运行所需内容。本文以 TypeScript Node.js Web 应用为例完成一次可验证构建。
学习目标
- 理解 Builder 与 Runtime 两个阶段各自承担的职责
- 使用
COPY --from只把发布产物和生产依赖带入最终镜像 - 通过构建与镜像检查验证最终启动命令
先约定应用的构建结果
本文示例项目使用 package-lock.json 锁定依赖,npm run build 会把 TypeScript 编译到 dist/,生产启动命令为 node dist/server.js。如果你的项目输出目录或启动文件不同,应同步调整 Dockerfile,而不是机械照抄路径。

多阶段构建的关键不是“写两个 FROM”本身,而是明确最终阶段从前一阶段拿什么。只有被 COPY --from=builder 明确复制的文件才会进入 Runtime,因此编译器和未复制的源码不会自动出现在最终镜像中。
编写 Builder 和 Runtime
下面 Dockerfile 使用同一 Node.js 基础镜像保证原生依赖的运行环境一致。Builder 安装完整依赖并编译,再用 npm prune --omit=dev 删除开发依赖;Runtime 只复制启动必需内容。
FROM node:22-bookworm-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev
FROM node:22-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]这是 Dockerfile 配置,不会直接产生固定控制台输出。它的生效行为是:Docker 完整执行 Builder 后,只把三个 COPY --from 指定的结果带入最终阶段;最终容器以镜像中的 node 用户启动,并执行 node dist/server.js。
COPY package.json package-lock.json ./ 放在源码复制之前,是为了利用构建缓存:依赖清单没有变化时,npm ci 这一层可以复用;源码改变只会让后面的复制和编译层失效。对于依赖安装较慢的项目,这个顺序能明显减少重复构建时间。
构建并检查最终镜像
在 Dockerfile 所在目录执行下面两个命令。docker build -q 只输出最终镜像 ID,随后直接读取最终镜像的启动命令,因此不用真正启动服务也能验证 Runtime 阶段是否正确生效。
docker build -q -t web-app:multistage .
docker image inspect --format '{{json .Config.Cmd}}' web-app:multistage预期输出
sha256:<ID>
["node","dist/server.js"]<ID> 是每次构建得到的镜像标识,实际值会不同。如果第二行不是预期命令,应检查最终阶段的 CMD,以及构建命令是否指向了正确的 Dockerfile 和构建上下文。
避免把 Builder 的负担带回 Runtime
多阶段构建最常见的失效方式,是最终阶段又执行一遍完整开发依赖安装,或者直接复制整个 /app。这样虽然仍叫“多阶段”,却把源码、缓存和开发依赖重新带进了最终镜像。
USER node 还能减少容器默认以 root 身份运行的风险,但它也意味着应用不能随意写入 /app。需要持久写入的上传目录、缓存目录或数据库文件应单独规划挂载位置和权限,而不是把可变数据写进镜像层。