核心排查步骤 #

1. 验证文件与路径真实性 #

在执行构建命令的project根目录下，运行以下命令检查目标文件是否存在：

ls -l contrib/docker/agent/debug-agent

如果命令返回文件不存在，说明：

• 实际文件结构中目录/文件名存在拼写错误（比如误写为contribe而非contrib）
• 文件被意外删除或移动

2. 检查.dockerignore规则 #

查看project根目录下是否存在.dockerignore文件，确认其中是否包含以下类似规则：

contrib/
contrib/docker/agent/debug-agent

Docker会忽略.dockerignore中匹配的文件/目录，导致COPY操作找不到源文件。如果有上述规则，直接删除即可。

3. 确认大小写匹配（Linux/macOS环境） #

Linux和macOS系统对文件名大小写敏感，需确保Dockerfile中写的debug-agent与实际文件名完全一致（避免出现Debug-Agent或DEBUG-AGENT这类差异）。

具体解决方法 #

方法一：修正构建缓存与路径校验 #

如果确认文件存在但仍报错，尝试绕过构建缓存重新构建，避免缓存导致的路径识别异常：

docker build --no-cache . -f contrib/docker/agent/Dockerfile -t test:latest

方法二：调整构建上下文简化路径 #

进入contrib/docker/agent/目录，以当前目录为构建上下文执行构建，此时Dockerfile中的路径可改为相对当前上下文的写法，降低路径出错概率：
修改Dockerfile内容：

COPY ../../scripts/start.sh /
RUN chmod 755 /start.sh
COPY ./debug-agent /bin/debug-agent

CMD ["/start.sh"]

执行构建命令：

cd contrib/docker/agent/
docker build . -t test:latest

内容的提问来源于stack exchange，提问作者moluzhui