执行 docker build 或 docker buildx build 时，日志停在 failed to compute cache key，后面还跟着某个文件 not found，问题多半不是缓存本身损坏，而是BuildKit在计算 COPY 或 ADD 输入摘要时找不到源文件。
先不要急着删除镜像、构建缓存或整个Docker数据目录。源文件没有进入构建上下文时，清多少次缓存都不会让它凭空出现。
先从完整错误中找到失败的COPY
使用纯文本进度输出重新执行构建，保留失败步骤和Dockerfile行号：
docker buildx build --progress=plain -f Dockerfile .重点看错误末尾的路径，以及它对应哪条 COPY、ADD 或 COPY --from。构建上下文是命令最后一个参数指定的目录，上例中的 . 才决定BuildKit能读取哪些本地文件，Dockerfile放在哪里并不会自动改变上下文。
核对构建命令所在目录
先在执行构建的同一终端检查工作目录和文件：
pwd
ls -la
find . -maxdepth 3 -type f | sort | sed -n '1,120p'若Dockerfile位于 docker/Dockerfile，项目根目录是 /srv/app，较稳妥的命令是：
cd /srv/app
docker buildx build -f docker/Dockerfile .在CI中还要检查仓库实际检出的子目录。本地能构建、流水线失败，经常是两边传给BuildKit的上下文不同。
检查.dockerignore是否排除了源文件
.dockerignore 会在上下文发送给构建器之前移除匹配内容。先查看根目录规则：
sed -n '1,200p' .dockerignore多Dockerfile项目还可能存在 build.Dockerfile.dockerignore 这类专用文件，而且它会优先于根目录规则。检查是否把构建产物、配置目录或整个父目录排除了，再用否定规则只放回确实需要的文件：
dist/
!dist/app.js不要为了快速通过构建直接清空忽略文件。密钥、环境文件和版本库元数据不应被打进镜像上下文。
修正COPY源路径和上下文边界
COPY 的本地源路径相对于上下文根目录解析，不是相对于Dockerfile所在目录。下面的写法只有在上下文中确实存在 package.json 时才成立：
COPY package.json package-lock.json ./COPY ../secret.txt /app/ 不能用来绕过上下文边界。需要复制项目上级目录的文件，应重新选择合理的上下文，或使用明确配置的命名上下文，而不是扩大到包含大量无关文件的目录。
多阶段构建要确认阶段名和产物路径
遇到 COPY --from=builder 时，源文件来自指定构建阶段，而不是本机目录：
FROM node:22 AS builder
WORKDIR /app
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=builder /app/dist/ /usr/share/nginx/html/检查 AS builder 是否拼写一致，以及前一阶段是否真的生成 /app/dist。阶段内工作目录变化不会自动修正最终COPY路径。 可以在失败步骤之前临时加入只读的 RUN ls -la /app 收集证据，确认后再移除调试命令。
不要把清缓存当作第一步
--no-cache 只是不复用既有构建层，无法解决源路径不存在或被忽略的问题。先修正上下文，再按需执行：
docker buildx build --no-cache --progress=plain -f docker/Dockerfile .需要在独立VPS复现构建目录差异时，可以使用 萤光云 或 LightNode 建立隔离环境。只上传最小复现项目，不要把生产密钥、私有镜像凭据或真实 .env 一并复制。
修复后怎样验收
重新构建时应看到上下文成功加载，原失败的 COPY 步骤完成，并且最终镜像可被创建。继续检查镜像内容，而不是只看命令退出码：
docker image inspect myapp:test >/dev/null
docker run --rm myapp:test test -e /app/package.json验收标准是构建命令在本地与CI使用相同上下文规则，目标文件存在于镜像预期位置，同时敏感文件没有进入上下文或镜像层。
FAQ
为什么文件明明在服务器上，BuildKit还是说找不到？ 因为BuildKit只能读取构建上下文内且未被忽略的文件，服务器其他目录是否存在同名文件并不重要。
改成旧版构建器能解决吗？ 不建议把切换构建器当成修复。错误暴露的是输入边界或路径问题，应先让Dockerfile和构建命令的关系保持明确。
温馨提示
排查时可以输出文件名和目录结构，但不要把配置内容、令牌或完整环境变量写进公开日志。先固定上下文、忽略规则和失败行，再决定是否清缓存。
