Docker build 报错 COPY failed file not found 路径错误怎么修

大多数情况下，这个报错是因为 Dockerfile 里的路径是相对于构建上下文（build context）的，而不是相对于 Dockerfile 本身所在的目录。先检查执行 docker build 时指定的上下文路径是否正确。

先说结论：这是路径映射问题，文件在构建上下文中不存在或被忽略，需修正上下文或文件路径。

先确认构建上下文目录与 Dockerfile 中 COPY 源路径的相对关系
先处理 .dockerignore 规则是否误删了目标文件
再验证重新构建后镜像内是否包含该文件

命令速用版

# 确保在包含 Dockerfile 和源文件的目录执行
docker build -t my-image .

# 查看当前上下文包含的文件
ls -R .

# 检查忽略规则
cat .dockerignore

完整 Dockerfile 与目录结构示例

以下是一个标准的 project 结构及对应的 Dockerfile 写法，确保 COPY 路径相对于构建上下文根目录。

project/
├── Dockerfile
├── .dockerignore
└── src/
    └── config.json

Dockerfile 内容示例：

FROM alpine:latest
WORKDIR /app
# 路径 ./src/config.json 是相对于 docker build 执行时的上下文根目录
COPY ./src/config.json /app/config.json
CMD ["cat", "/app/config.json"]

构建命令：

Docker build 报错 COPY failed file not found 路径错误怎么修

cd project
docker build -t my-image .

为什么会这样

Docker 构建过程中，客户端会先将“构建上下文”目录下的文件发送给守护进程。Dockerfile 中的 COPY 指令只能访问这个上下文范围内的文件。如果路径写错，或者文件被 .dockerignore 排除，守护进程就找不到源文件，从而报错 file not found。

根据 Docker 官方文档，COPY 指令的源路径必须是相对于构建上下文根目录的相对路径，不能使用绝对路径，也不能跳出上下文目录。

分步处理

1. 确认构建上下文位置

检查你运行 docker build 命令时最后那个点（.）代表什么。例如 docker build -f Dockerfile . 表示当前目录是上下文。如果 Dockerfile 在子目录，但上下文是根目录，COPY 路径就要从根目录算起。

2. 检查文件实际路径

在终端执行 ls 命令，确认文件确实存在。注意大小写敏感，Linux 环境下 Config 和 config 是不同的文件。

ls -la path/to/your/file

3. 排查 .dockerignore

查看项目根目录是否有 .dockerignore 文件。如果里面写了 *.log 或特定文件夹规则，可能误伤了你要 COPY 的文件。临时重命名该文件测试构建是否通过。

mv .dockerignore .dockerignore.bak
docker build -t my-image .

4. 修正 Dockerfile 路径

如果文件在上下文根目录，直接写文件名。如果在子目录，写上相对路径。不要写宿主机绝对路径如 /home/user/project/file。

# 正确示例
COPY ./src/config.json /app/config.json

# 错误示例（绝对路径）
COPY /home/user/project/src/config.json /app/config.json

怎么验证是否生效

构建成功后，启动一个临时容器检查文件是否存在。

# 构建
docker build -t test-image .

# 运行容器并查看文件（注意 `--rm` 参数不要加反引号）
docker run `--rm` test-image ls /app/config.json

如果命令输出了文件路径，说明 COPY 成功。如果报错 no such file，说明文件虽然构建通过但路径可能抄写错误。

常见坑

上下文范围过大：直接在根目录 build 会把所有文件发送给 Docker，既慢又容易触发忽略规则，建议在项目子目录操作。
符号链接问题：如果 COPY 的源文件是符号链接，Docker 默认复制链接本身而非目标文件，且链接目标必须在上下文内，否则会失败。
多阶段构建路径：在多阶段构建中，COPY `--from`=0 指的是上一阶段镜像的文件系统，而不是构建上下文，路径规则不同。

参考来源

Docker Documentation - COPY instruction: https://docs.docker.com/engine/reference/builder/#copy
Docker Documentation - Build context: https://docs.docker.com/build/building/context/