docker构建失败最常见原因是基础镜像选错或写错。需确保from指令中镜像名和标签精确匹配（大小写敏感）、存在且适用；国内用户应配置有效镜像加速器并验证网络连通性；多阶段构建须严格核对阶段名。
基础镜像选错或写错，是 Docker 构建失败最常卡住的第一步。问题通常不复杂，但容易忽略。
镜像名称或标签拼写错误
FROM 指令必须精确匹配镜像名和标签，比如 node:20.18.1 不能写成 node:20.18 或 Node:20.18.1（大小写敏感）。Docker Hub 上不存在的组合会直接报错“manifest unknown”或“pull access denied”。
- 去 Docker Hub 手动搜索确认镜像是否存在、标签是否准确
- 优先使用明确版本号（如
python:3.9-slim），避免用latest导致行为不可控 - 国内用户注意：部分镜像（如
golang:alpine）在某些加速器中可能同步滞后，可临时切回官方源验证
基础镜像不适用当前需求
选错类型会导致后续命令失败。例如用 scratch 基础镜像却执行 apt update，或用 alpine 却调用 apt 而非 apk。
- Python 项目推荐
python:3.9-slim（Debian系）或python:3.9-alpine（轻量，但需适配 apk） - Node.js 推荐
node:18-alpine或node:20-slim，避免无构建工具的node:20-alpine直接跑npm install - 需要编译 C 扩展时，
-slim镜像默认不含gcc，得显式RUN apt-get update && apt-get install -y gcc
网络原因拉不到基础镜像
尤其是国内环境，docker build 执行 FROM 时静默卡住或超时，本质是 registry-1.docker.io 连接失败。
- 检查本地是否配置了可用的镜像加速器（如阿里云、中科大源），修改
/etc/docker/daemon.json并重启 Docker - 临时测试：手动执行
docker pull python:3.9-slim，看是否能成功，快速定位是网络还是镜像本身问题 - 企业内网若需代理，确保
daemon.json中proxies配置正确，且与系统环境变量不冲突
多阶段构建中基础镜像引用错位
在 FROM ... AS xxx 后续阶段里，误写 FROM base 却没定义 base，或拼错阶段名，会报 “unknown stage” 错误。
- 每个
AS定义的阶段名要全小写、无特殊字符，且后续FROM必须严格一致 - 建议阶段命名有语义，如
builder、runtime、test，避免用stage1这类易混淆名称 - 构建时加
--progress=plain参数，可清晰看到哪个阶段的 FROM 出错
