Docker COPY 无法读取构建上下文外的文件

Dockerfile 放在项目的 docker/ 目录，配置文件放在同级的 config/ 目录。终端明明能读到配置，构建时写成 COPY ../config/app.conf /app/app.conf，却提示：

COPY failed: forbidden path outside the build context

这是传统构建器拒绝越过构建上下文的错误。使用 BuildKit 时，同样的写法可能变成文件找不到，也可能复制到上下文内的同名文件：BuildKit 会去掉开头越界的 ../，不会借此读取宿主机的父目录。

应核对构建命令传入的上下文，以及 COPY 的源路径。仅仅移动 Dockerfile、增加 ../ 或换成绝对路径，都不能把上下文之外的文件变成可用输入。

下文针对本地目录构建 Linux 镜像、从默认上下文复制普通文件的场景。多阶段构建中的 COPY --from=... 有自己的来源，不按这里的默认上下文路径判断。传统构建器与 BuildKit 的错误文字也不能混用来推断 Docker 版本。

Dockerfile 的目录不等于上下文根目录

假设项目是下面的结构，路径和文件内容均为示例：

project/
├── config/
│   └── app.conf
└── docker/
    └── Dockerfile

如果进入 project/docker/ 后执行 docker build .，末尾的 . 把 docker/ 设为上下文根目录。它的兄弟目录 config/ 不在这个范围内。Dockerfile 中的源路径从上下文根目录计算，而不是从宿主机任意位置寻找。

反过来，在 project/ 目录执行：

docker build -f docker/Dockerfile -t context-demo:check .

末尾的 . 就代表整个 project/。-f docker/Dockerfile 只指定要读取哪份 Dockerfile，不会把上下文缩回 docker/。因此，配置文件对应的源路径应是 config/app.conf。

检查自己的命令时，把这两个位置分开：-f 后面是 Dockerfile，最后的目录参数是上下文。CI 脚本也要确认执行这条命令时的工作目录；同一个 . 在不同目录中代表不同输入范围。

同时调整上下文和 COPY 路径

在本地测试目录中准备上述结构，config/app.conf 放一行不含凭据的示例内容：

mode=example

docker/Dockerfile 使用下面的最小内容：

FROM alpine:3.23
COPY config/app.conf /app/app.conf

然后从 project/ 执行上一节的构建命令。这个镜像只用来检查文件复制，不是可直接部署的应用镜像；首次构建还需要能获取基础镜像。

扩大上下文后，也要将源路径改为相对新根目录的位置。不要继续保留 ../config/app.conf。BuildKit 即便接受这段路径，也不能说明它读取了真正的父目录；明确写出上下文内的相对路径，才能避免不同构建器的处理差异。

目标路径 /app/app.conf 是镜像内的路径，与宿主机上 Dockerfile 所在目录无关。修改 WORKDIR 也不会改变 COPY 查找本地源文件时所依据的上下文根目录。

已有项目无需换掉原有基础镜像或其他构建步骤。将示例中的目录关系映射到实际项目，只调整构建输入范围和受影响的源路径，并逐条复核其他 COPY，避免它们在新根目录下指向别的文件。

Docker Compose 中要改 build.context

如果 compose.yaml 位于 project/ 根目录，可以这样表达同一个构建：

services:
  demo:
    image: context-demo:check
    build:
      context: .
      dockerfile: docker/Dockerfile

这里 context: . 使用项目目录，dockerfile 则相对构建上下文解析。原先如果写的是 context: ./docker，只把 dockerfile 改成别的路径仍不能让兄弟目录里的配置文件进入默认上下文。

从项目目录执行构建即可，不需要启动服务：

docker compose -f compose.yaml build demo

这份示例只涉及单个 Compose 文件。已有多个配置文件、指定项目目录或由 CI 组装参数的项目，应先确认最终使用的上下文位置，再修改路径，不要单靠编辑器里看到的文件相对位置判断。

文件在范围内，却仍提示找不到

确认 config/app.conf 位于上下文内后，再检查忽略规则。构建客户端会读取上下文根目录的 .dockerignore，匹配的文件会从上下文中排除。文件在本机存在，不代表构建器收到它。

本例要检查 project/.dockerignore。如果还存在 project/docker/Dockerfile.dockerignore，这份与 Dockerfile 对应的忽略文件优先于根目录的 .dockerignore。不能只看其中一份就认定没有排除配置。

核对是否有排除 config、*.conf 或更宽范围的规则。按实际需要缩小规则，让构建必需的普通配置进入上下文，同时保留凭据和无关文件的排除。不要为了让构建通过，直接删除整份忽略文件。

扩大上下文之前也应审查这些规则。原先放在 docker/ 下的 .dockerignore 不会因为上下文改成项目根目录，就自动成为根目录的忽略规则。若旧 Dockerfile 有 COPY . ...，扩大后的复制范围也会改变，必须确认不会带入 .env、私钥或不需要的目录。生产密钥不应靠复制进镜像来解决构建缺文件的问题。

检查镜像里实际复制了什么

构建通过后，用独立测试标签检查文件内容：

docker run --rm --network none context-demo:check cat /app/app.conf

对于上面的最小示例，应输出 mode=example。这个命令创建临时容器，读取镜像中的文件后退出，不挂载宿主机目录，也不发布端口。这里的镜像有 cat；实际业务镜像如果没有这类工具，应使用适合该镜像的文件检查方法。

核对内容比只看构建结束更可靠，尤其是上下文里也有同名目录时。若实际文件不是预期版本，回到构建工作目录、上下文参数、源路径和忽略规则逐项确认；关闭缓存不会让上下文外的文件变得可读。

修改前保留原 Dockerfile、忽略规则、构建脚本和 Compose 配置。验证使用新的测试标签，不覆盖正在部署的镜像标签；确认内容和应用检查都通过后再进入部署流程。需要回退时一并恢复上下文参数与源路径，不能只恢复其中一项。