技术 · 实用指南
Docker build 提示 COPY 找不到源文件？改 Dockerfile 前先审计真实 context
COPY 只能读取 checkout、生成步骤和 ignore 过滤后的 build context。先保存命令并证明实际快照，再修一个明确边界，避免扩大 context 或打包 Secret。
Docker COPY 失败不等于文件不在电脑上，而是该源文件不在 BuildKit 实际收到并过滤后的 context 中，或 COPY 正从另一个 stage、image、named context 读取。
先保存命令和错误，再证明 context 类型、checkout 内容、有效 ignore 规则与 source kind；只修一个边界，并避免把 Secret 或整个父目录发送给 builder。
保存命令并确认真实 context
记录完整错误、cwd、版本、builder、Dockerfile 路径和最后的 context 参数；`-f` 不会改变 context root。
区分本地目录、Git、tar、named 或 empty context；主机上看得到不等于 builder 收得到。
证明 checkout 与生成后的源文件
在实际 workspace 或 Git snapshot 中按精确大小写检查路径，并核 sparse checkout、submodule、LFS 与 checkout path。
若文件由前序步骤生成，记录生成位置；默认 Git context 不会读取 runner 上刚生成的文件。
计算有效 ignore 规则
检查 context 根的 `.dockerignore` 及 Dockerfile 专用 ignore；后者优先，最后一条匹配决定结果。
不要为了通过而取消大范围规则或复制 Secret，只加最窄安全例外。
分开默认与 --from 来源
普通 COPY 读默认 context；COPY --from 读 stage、image 或 named context 的根。
不要用 `../` 逃出 context；需要另一棵目录时显式声明窄 named context。
一次修正并验证产物
只改 context、checkout、生成顺序、大小写、单条 ignore、Git/path context 或 --from 映射中的一个事实。
做一次 fresh build，核 source 已传输并检查最终 image；CI 必须复现同一 context contract。
