Docker build卡在pulling fs layer或waiting本质是网络超时，需先通过docker pull hello-world验证是否全局问题；若仅build失败，则聚焦RUN指令内apt/yum/npm等网络请求，并确认registry-mirrors配置合法、生效且与系统包源独立处理。
docker build 卡在 pulling fs layer 或 waiting 是网络超时
直接看日志里有没有 pulling fs layer、waiting for download 或 timeout 字样。这类卡住基本不是 Dockerfile 写错了，而是构建过程中拉基础镜像或 RUN 指令里触发的网络请求失败。
快速验证：运行 docker pull hello-world，如果也卡住，说明是全局网络问题；如果它成功，但 docker build 失败，那问题大概率出在 RUN 指令内部（比如 apt update 或 npm install）。
- 用
ping registry-1.docker.io测连通性，丢包或超时就确认是 DNS 或出口限制 - 用
curl -v https://registry-1.docker.io/v2/看是否卡在 TLS 握手——这是典型国内直连失败特征 - Windows 上执行
docker info | findstr "Registry Mirrors"，确认加速器是否已生效
registry-mirrors 配置了但没生效的常见原因
Docker Desktop 的 GUI 设置和底层 daemon.json 文件是联动的，但改完不重启、路径错、格式非法都会让配置白配。
- Windows 用户配置文件实际在
%USERPROFILE%\.docker\daemon.json，不是C:\Program Files\Docker\... - JSON 必须严格合法：末尾不能多逗号，字符串必须双引号，
registry-mirrors值必须是数组（哪怕只填一个地址） - 改完一定要点 Docker Desktop 的 Apply & Restart，只点 Save 不会重启守护进程
- 配置多个地址更稳妥，例如：
["https://docker.m.daocloud.io", "https://docker.xuanyuan.me"]
RUN 指令里 apt/yum/npm 失败要单独处理源
registry-mirrors 只影响 docker pull 和 FROM 拉取基础镜像，对 RUN 里的系统包管理器或语言包工具完全无效。
Debian/Ubuntu 镜像中，别依赖默认源：
RUN sed -i 's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list && \
apt update && \
apt install -y curl
CentOS/RHEL 镜像中，替换 /etc/yum.repos.d/CentOS-Base.repo 里的 baseurl 为清华或阿里云地址；Alpine 则用 sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories。
FROM 镜像不存在或标签拼错也会报“超时”假象
错误日志里出现 manifest unknown 或 no matching manifest，其实是镜像名写错了，Docker 会反复重试直到超时，看起来像卡住。
- 检查
FROM node:20.18.1这类标签是否存在：去 Docker Hub node 镜像页 找对应 tag，注意20.18.1和20.18是不同标签 - 私有仓库镜像必须带完整域名和端口，例如
FROM my-registry.local:5000/myapp:latest - 企业内网若禁用了
registry-1.docker.io，但没配insecure-registries，拉私有镜像也会卡在 TLS 验证
真正难排查的是混合场景：镜像源配对了，但某条 RUN 指令又调了外部 API 或下载第三方二进制，这种请求完全不受 Docker 配置控制，得进容器里手动复现命令才能定位。
