Docker构建失败时可通过四种方式断点调试：一是用--no-cache加临时阻塞命令（如sleep）中断执行并exec进入；二是启用--progress=plain查看完整错误日志；三是基于上层镜像启动交互容器复现环境；四是用多阶段构建定义debug阶段保留中间状态。
当 Dockerfile 中的 RUN 指令执行失败时，Docker 默认会中断构建并丢弃当前层，无法直接进入失败命令的环境。但可以通过几种实用方式实现“断点调试”，快速定位问题。
用 --no-cache + 临时修改 Dockerfile 打断点
这是最常用、最轻量的方法：在出错的 RUN 指令前插入一条能保持容器运行的命令（如 sleep 或 bash -c "read -p 'Press any key...'"），并用 --no-cache 强制重新执行到该层：
- 把原指令拆成两步：先做前置操作（确保成功），再加一个阻塞命令
- 例如原指令是
RUN pip install -r requirements.txt，可临时改为：
RUN pip install -r requirements.txt && echo "OK" || (echo "FAIL"; exit 1)<br>RUN bash -c "echo 'Debug point — check /app now'; sleep 30"
然后运行：docker build --no-cache --target debug-stage .（若配合多阶段构建更精准）
构建停住后，用 docker ps 查看容器 ID，再 docker exec -it <id> /bin/bash</id> 进入调试。
用 docker build --progress=plain 查看详细错误输出
默认构建日志会折叠部分信息，掩盖真实报错原因（比如 Python 包编译失败被截断）。启用详细模式可暴露完整 stderr：
- 运行：
docker build --progress=plain . - 重点关注最后一段红色错误（尤其是 exit code、traceback、missing headers、权限拒绝等）
- 常见线索：网络超时（需配置 proxy）、缺少系统依赖（如
gcc、libpq-dev）、路径不存在、用户权限不足（USER切换后写入失败）
用交互式容器复现构建环境
基于上一层成功的镜像启动临时容器，手动执行失败命令，完全模拟构建时上下文：
- 先查出上一层镜像 ID：
docker images --format "{{.ID}} {{.Repository}}" | grep "<your-repo>"</your-repo> - 启动容器：
docker run -it --rm -v $(pwd):/workspace <pre class="brush:php;toolbar:false;"v-image-id> /bin/bash</code></li><li>在容器内 cd 到对应目录，逐条执行 <code>RUN</code> 中的命令（注意 shell 类型、工作目录、环境变量）</li><li>可自由安装调试工具（<code>strace</code>、<code>curl</code>、<code>vim</code>）、检查文件权限或网络连通性</li></ul><H3>用多阶段构建 + <code>debug</code> 阶段保留中间状态</H3><p>在 Dockerfile 开头定义一个调试专用阶段，显式保留构建中间产物：</p><font color="#666"><pre class="brush:php;toolbar:false;">FROM ubuntu:22.04 AS builder<br>WORKDIR /app<br>COPY . .<br>RUN apt-get update && apt-get install -y python3-pip build-essential<br># 此处可能失败<br>RUN pip3 install -r requirements.txt<br><br>FROM builder AS debug<br>RUN apt-get update && apt-get install -y vim strace net-tools && rm -rf /var/lib/apt/lists/*</pre><p>构建时指定目标：<code>docker build --target debug -t myapp:debug .，之后docker run -it myapp:debug /bin/bash即可进入已执行完失败命令（但未清理）的环境，检查/app下的文件、pip list、ls -l权限等。
