“文件丢失”本质是源阶段未生成、路径错位或缓存干扰导致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
查看最终镜像各层内容，确认 dist 目录是否出现在某一层 - 对中间阶段镜像运行 docker run --rm
ls -la /app/dist ，直连验证文件是否存在
