“文件丢失”本质是源阶段未生成、路径错位或缓存干扰导致COPY失败；需验证源阶段产物、检查COPY路径与权限、禁用缓存确认阶段名称一致性，并用--progress=plain定位具体错误。

多阶段构建中“文件丢失”通常不是真丢，而是 copy --from 阶段引用失败、路径错位或缓存干扰导致的构建时不可见。排查核心是确认源阶段是否生成了目标文件、目标路径是否存在、以及构建上下文是否被意外覆盖。

确认源阶段是否真实产出文件

很多“丢失”本质是源阶段压根没生成对应文件。例如构建命令写错、编译失败静默跳过、或 .dockerignore 排除了关键目录。

• 用 docker build --target builder -o ./out . 单独构建源阶段，并检查 ./out 目录下是否有预期文件（如 /app/dist/index.js）
• 在源阶段末尾加 RUN ls -la /app/dist/ || echo "dist is empty"，强制暴露构建产物状态
• 检查 Docker 构建日志，确认 RUN 指令是否成功执行——尤其注意 npm run build 或 go build 是否返回 0

验证 COPY --from 路径与权限是否匹配

COPY --from 不会自动创建父目录，也不复制隐藏文件，路径稍有偏差就会报 “no such file or directory”。

• 确保目标路径的父目录已存在：在 runtime 阶段先执行 RUN mkdir -p /app/dist，再 COPY
• 检查路径是否带多余斜杠或大小写错误，比如 /App/dist 和 /app/dist 在 Linux 下是不同路径
• 若需复制 .env 等隐藏文件，不能依赖 COPY ./.，要显式写 COPY --from=builder /app/.env /app/.env

排除缓存干扰与 stage 名称混淆

构建缓存可能让旧阶段残留，或因 AS 名称未对齐导致 --from 找不到阶段。

• 用 docker build --no-cache --progress=plain . 彻底禁用缓存，看问题是否复现——若禁用后正常，说明是缓存层错位
• 确认每个 FROM 后都带明确的 AS name，且 COPY --from=xxx 中的 xxx 与之完全一致（区分大小写）
• 避免使用数字索引（如 --from=0），它依赖 Dockerfile 顺序，重构时极易断裂；始终用命名阶段

快速定位失败点的日志技巧

Docker 默认日志较简略，开启详细输出能直接看到哪一行 COPY 报错及具体路径。

• 构建时加上 --progress=plain，观察最后一行失败提示，例如：failed to compute cache key: "/app/dist" not found
• 用 docker history <image-id> 查看最终镜像各层内容，确认 dist 目录是否出现在某一层
• 对中间阶段镜像运行 docker run --rm <intermediate-image> ls -la /app/dist，直连验证文件是否存在