多阶段构建中COPY --from复制失败主因是路径不匹配、目录未创建、阶段名偏差或隐藏文件遗漏；需严格核对阶段名大小写与FROM AS定义一致，验证源阶段文件真实存在且目标父目录已用RUN mkdir -p创建，显式处理.env等隐藏文件。
多阶段构建中，COPY --from 复制失败往往不是“找不到文件”，而是“找错了地方”——路径不匹配、目录未创建、阶段名偏差或隐藏文件遗漏。排查重点不在报错本身，而在构建上下文与指令执行逻辑的严格对齐。
确认源阶段名称和路径是否完全准确
阶段名区分大小写，且必须与 FROM ... AS xxx 中的 xxx 完全一致。常见错误包括拼写差异（如 builder 写成 Builder）、空格残留、或误用索引（--from=0）而未定义命名阶段。
- 检查 Dockerfile 中每个
FROM ... AS stage-name行，记录所有阶段名 - 核对
COPY --from=xxx的xxx是否逐字符匹配，不含前后空格 - 避免混用命名阶段与数字索引；若必须用索引，确保构建顺序未被
--target改变
验证源路径是否存在且可访问
Docker 不会自动展开通配符或递归遍历隐藏文件，也不会提示“文件在源阶段但路径不对”。需主动进入源阶段镜像检查实际结构：
- 构建时加
--target builder（假设阶段名为 builder），再运行容器：docker build -t test-builder --target builder . && docker run --rm -it test-builder ls -la /app/ - 确认你要复制的文件（如
/app/server）确实存在，且权限允许读取 - 注意：
COPY --from只能访问该阶段WORKDIR及其子路径，不能越级访问（如/root/xxx），除非显式COPY过去
检查目标路径的父目录是否已创建
Docker 的 COPY 指令不会自动创建缺失的父目录。若目标路径为 /etc/app/.env，而 /etc/app 不存在，构建直接失败。
- 在
COPY前添加RUN mkdir -p /etc/app - 或者使用带引号的 JSON 格式写法，虽不能替代目录创建，但可规避空格等解析问题：
COPY ["--from=builder", "/app/config/.env", "/etc/app/.env"]（注意：这不是标准语法，仅作说明；正确写法仍是分开RUN+COPY） - 对批量复制，建议先
RUN mkdir -p目标根路径，再统一COPY
留意隐藏文件和通配符行为
.env、.gitignore 等以点开头的文件不会被 COPY . /dest/ 自动包含，即使源阶段里有，也会漏掉。
- 显式列出关键隐藏文件：
COPY --from=builder /app/.env /app/.config /etc/app/ - 或改用构建脚本预处理：在源阶段打包成 tar.gz，再解压到目标阶段，确保完整性
- 避免依赖 shell 展开（如
*），Docker 的 COPY 不支持 glob 递归匹配隐藏项
