docker镜像构建失败主因是构建上下文、依赖或配置未对齐，而非代码错误；需重点核查基础镜像标签可靠性、.dockerignore是否排除干扰项、dockerfile语法与路径准确性，以及缓存和本地状态是否干净。
Docker 镜像构建失败，多数不是代码写错，而是构建上下文、依赖或配置没对齐。抓住几个关键点，基本能快速定位。
基础镜像和标签是否可靠
FROM 指令写错是最常见的硬伤。比如写成 FROM node:20 却没确认该标签是否存在；或者误用 latest 导致环境不一致。建议： - 在 Docker Hub 上手动搜索镜像名+标签，确认可拉取； - 优先用带架构后缀的明确版本，如 python:3.11-slim-bookworm； - 构建前先试运行 docker pull python:3.11-slim，验证网络和镜像源是否通。
.dockerignore 是否漏掉了干扰项
构建上下文过大或包含非法路径，容易触发超时或 COPY 失败。典型干扰项包括：node_modules、.git、__pycache__、venv 等。检查你的 .dockerignore 文件是否已排除它们。没这个文件？补上它——哪怕只写一行 **/node_modules 也能避免很多意外。
Dockerfile 语法和路径是否准确
COPY、ADD、WORKDIR 这些指令对路径很敏感。常见坑有： - COPY ./src /app 中的 ./src 在构建目录里根本不存在； - WORKDIR 设置后，后续 RUN 或 CMD 没在正确路径下执行； - 指令大小写错误，比如把 run 写成 Run（Dockerfile 指令全小写）； - 多行命令没用反斜杠 \ 正确续行，导致 shell 解析中断。
缓存和本地状态是否干净
旧缓存可能掩盖真实问题，尤其当你改了基础镜像或依赖后。临时绕过缓存试试： - 加 --no-cache 参数重建：docker build --no-cache -t myapp .； - 清理无用中间层：docker builder prune（新版 BuildKit）或 docker system prune -a（慎用，会删所有未使用对象）； - 如果用了 BuildKit，确认 DOCKER_BUILDKIT=1 环境变量已启用，它对错误提示更友好。
