Docker 多阶段构建如何只保留运行时依赖

如果把安装依赖、编译和启动程序都写在同一个 Docker 镜像里，最终镜像往往会把包管理器、编译器、缓存和源码一起带上。解决办法不是在最后再删除这些文件，而是从 Dockerfile 的阶段边界上隔离它们：用一个 builder 阶段完成构建，再用一个干净的 runtime 阶段只接收可运行产物。

官方资料：https://docs.docker.com/build/building/multi-stage/

先在项目入口确认构建上下文

在 VS Code 中选择 File > Open Folder 打开项目根目录，左侧 Explorer 应能同时看到 Dockerfile、应用源码目录和 .dockerignore。如果 Dockerfile 放在 docker/ 子目录，命令路径和 COPY 源路径就容易错位；本例把 Dockerfile 放在根目录，构建上下文也使用根目录。

打开 View > Command Palette，输入并执行 Docker: Add Docker Files to Workspace（若项目已有 Dockerfile，可跳过生成），然后在 Explorer 点击 .dockerignore，确认没有把 node_modules、dist 和本地日志发送进构建上下文。这个动作只影响构建器能看到什么，不会决定最终镜像复制哪些文件。

可见状态：Explorer 中能看到根目录 Dockerfile，编辑器底部没有“找不到构建上下文”的提示，终端执行路径显示为项目根目录。

用两个阶段分离构建依赖和运行时

点击 Explorer 中的 Dockerfile，将示例内容整理成下面的最小结构。这里以 Node.js 静态构建为例；如果你的项目输出是 Go 二进制或 Java JAR，只需要把 dist 换成实际产物目录。

# 构建阶段：安装完整依赖并生成生产文件
FROM node:22-bookworm AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 运行阶段：只保留静态产物和 Web 服务器
FROM nginx:alpine AS runtime
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

关键点是 FROM nginx:alpine AS runtime 会开启一个新的根文件系统，而 COPY --from=builder 只从前一阶段读取 /app/dist。npm、源码和构建缓存没有被复制。不要写成 COPY . /usr/share/nginx/html，否则本地上下文里不该进入运行时的文件也可能被带入。

可见状态：编辑器中能看到两个带名称的 FROM，构建阶段有 RUN npm run build，运行阶段只有产物复制和启动命令。

从项目根目录构建最终镜像

在 VS Code 选择 Terminal > New Terminal，确认提示符位于项目根目录后执行：

# 使用当前目录作为构建上下文，并给最终镜像打可识别的标签
docker build -t web-demo:runtime .

命令末尾的点不能省略；它告诉 Docker 使用当前目录作为上下文。若只想调试构建阶段，可临时执行 docker build --target builder -t web-demo:builder .，但发布和运行时检查应使用默认的最后阶段。构建日志出现 exporting to image 后，说明最终导出的是 runtime 阶段。

可见状态：终端显示镜像导出完成，且 docker images web-demo 能列出 web-demo:runtime 标签。若出现 failed to calculate checksum，优先检查 COPY 路径是否相对于构建上下文，而不是继续增加依赖。

在 Docker Desktop 中验收运行时镜像

打开 Docker Desktop，左侧选择 Images，在搜索框输入 web-demo，点击 web-demo:runtime 所在行的 Run。端口映射填写 8080:80，点击 Run 后进入 Containers 查看状态。

如果页面显示容器为 Running，访问 http://localhost:8080 能看到构建后的页面，就完成了运行验收。想检查内容时，在 Images 的目标行打开 Inspect，确认入口命令是 nginx；不要把“镜像变小”只理解成一个固定 MB 数，真正的验收是构建工具没有进入运行时、应用产物能正常启动。

可见状态：Images 列表有 web-demo:runtime，Containers 中对应实例为 Running，Inspect 面板的启动命令来自运行阶段。

常见问题

为什么最终镜像里找不到 node_modules？

这是预期结果。本例的运行阶段是 Nginx，只需要 dist；只有当运行时确实需要 Node.js 时，才应在 runtime 阶段安装生产依赖并复制必要文件。

可以把 builder 写在最后吗？

可以构建，但默认导出的最后阶段就会变成 builder，编译器和源码也会进入最终镜像。生产镜像应把最小 runtime 阶段放在最后，或用 --target runtime 明确选择目标。

.dockerignore 能替代多阶段构建吗？

不能。.dockerignore 控制构建上下文，多阶段构建控制最终镜像的阶段和复制边界，两者应一起使用。