Docker 多阶段构建怎样只复制运行时文件

Docker 多阶段构建要只带走运行时文件，关键是用新的 FROM 开始最终阶段，再用 COPY --from=阶段名 指定产物路径。不要让最终阶段继承编译阶段，也不要把源码目录整体复制进运行镜像。下面用一个只输出业务标识的小程序，把需要保留的文件限定为 /app/report。

官方地址：https://www.docker.com/

示例适用于能够构建 Linux 镜像的 Docker 环境；Docker Desktop 用于查看镜像，Docker CLI 用于构建。命令为供读者执行的示例，本文没有实际运行它们，也没有提供本机测试记录。界面图片均为原创说明图。

1. 准备只生成单个文件的示例

先进入 Docker Desktop 的“Images → Local”，在 Search 中输入 runtime-copy-demo。若这是第一次使用该示例标签，列表可能为空；若已有同名镜像，记住它并不能代表稍后这次构建的结果，应以构建后的记录为准。这里的目的只是建立明确的目标名称。

在一个独立示例目录中保存 main.go。本例没有第三方依赖，不需要通过模块下载来解释复制范围，也不需要证书、模板或配置文件。将文件内容写为：

package main

import "fmt"

func main() {
    // 只输出固定业务标识，不读取网络或外部资源。
    fmt.Println("report service ready")
}

同目录另建 Dockerfile。构建命令末尾的点表示当前目录作为上下文，因此之后要在这两个文件所在目录执行。请勿将自己的密码文件或生产配置放进该示例目录。

2. 以命名阶段输出文件，再显式复制

将下面内容保存为 Dockerfile。compile 只负责编译；runtime 是最终交付目标。这里的 /out/report 属于构建阶段文件系统，不是宿主机上的路径。

# 在构建阶段使用编译工具，产物单独放在 /out。
FROM golang:1.26 AS compile
WORKDIR /src
COPY main.go ./
RUN CGO_ENABLED=0 go build -trimpath -o /out/report ./main.go

# 新阶段从空基础开始，只复制已明确列出的运行文件。
FROM scratch AS runtime
COPY --from=compile /out/report /app/report
# 使用绝对路径直接启动程序，不依赖 shell。
ENTRYPOINT ["/app/report"]

复制语句只选择一个文件，不使用 COPY --from=compile /src /app 这样的整目录搬运。命名阶段也比依赖阶段数字更容易维护：新增一个准备阶段时，不必到处重算索引。

在示例目录执行：

# 明确选择运行阶段，并给最终镜像一个容易识别的本地标签。
docker build --target runtime -t runtime-copy-demo:local .

等构建命令成功结束，再回到“Images → Local → Search”，输入相同名称，找到 local 标签。命令失败时先处理真实报错，不要拿列表里旧的同名镜像当成这次新产物。

若希望单独保留编译阶段调试，应使用另一个标签和 --target compile；不要把编译阶段标签推送成运行版本。多阶段隔离的是最终镜像内容，构建缓存仍可能占用本机空间，两者不能混为一谈。

3. 查看最终镜像并运行示例

在“Docker Desktop → Images → Local”点击目标镜像行进入详情，查看镜像历史、层和基础镜像信息。不同桌面版本的详情布局可能不同，图只解释所关注的对象，不要求逐像素对应。选择正确的标签后，再在命令行检查入口配置并运行：

# 查看镜像记录的入口，确认不是编译命令。
docker image inspect runtime-copy-demo:local --format '{{json .Config.Entrypoint}}'
# 程序应输出业务标识后退出；退出时删除本次临时容器。
docker run --rm runtime-copy-demo:local

按本例代码，程序预期输出 report service ready 后结束；这是一段短任务，不是监听端口的常驻服务。如果需要独立核对交付文件，可从一个不启动的临时容器复制产物：

# 创建容器但不启动，使用唯一名称避免与已有容器冲突。
docker create --name runtime-copy-review runtime-copy-demo:local
# 将镜像中的程序复制出来供交付核对；当前目录需可写。
docker cp runtime-copy-review:/app/report ./report.from-image
# 核对结束后清理该临时容器。
docker rm runtime-copy-review

如果创建命令提示名称已被占用，应先确定旧容器用途，或为本次检查换一个未使用的名称，再同步修改后续命令。不要直接删除不认识的容器。入口配置正确也不等于所有业务依赖都齐全，运行结果仍要结合具体应用判断。

常见问题

为什么文件存在却提示无法启动？

先判断是否有动态链接依赖、架构是否匹配，以及入口路径是否正确。本例关闭 CGO 并仅使用基础功能；不能据此认定任意应用都适合 scratch。

配置目录应该怎样复制？

把运行时真正需要的配置或模板列成独立清单，再为每项增加精确的 COPY 语句。凭据通过运行时机制提供，不随镜像写入。

最终镜像里能执行 sh 吗？

本例不行。排查文件不必依赖容器内 shell，可以使用上述不启动容器的复制方式。确实需要系统库和工具时，选择适合应用的运行基础镜像。

官方多阶段构建说明：https://docs.docker.com/build/building/multi-stage/

Docker Desktop 镜像界面说明：https://docs.docker.com/desktop/use-desktop/images/