Docker pull卡住或失败主因是网络慢、缓存不一致、平台不匹配或证书/认证问题；优先配置国内镜像加速器并重启docker服务，拉取时显式指定--platform，私有registry需正确配置证书路径和imagePullSecrets。

docker pull 卡在某个 layer 且超时

本质是默认的 registry 镜像源响应慢或中间网络不稳定，docker pull 默认没有重试机制，遇到短暂超时就直接失败。国内用户尤其常见，不是你本地配置错，也不是镜像坏了。

• 优先改用国内镜像加速器，比如阿里云、中科大、网易的 registry-mirrors 配置，写进 /etc/docker/daemon.json
• 改完必须执行 sudo systemctl restart docker，否则不生效
• 临时绕过加速器调试时，可用 docker pull --platform linux/amd64 registry.cn-hangzhou.aliyuncs.com/library/nginx:alpine 直接指定镜像全路径
• 不要依赖 docker info | grep -i mirror 判断是否生效——它只显示配置项，不反映实际连接行为；真正要看 docker pull 日志里有没有 pulling from ... 后快速出现 download complete

校验和 mismatch（sha256 digest verification failed）

不是镜像被篡改，而是客户端缓存了旧的 manifest 或 layer 元数据，跟 registry 当前返回的不一致。Docker 19.03+ 默认启用 manifest list 解析，容易在多平台镜像场景下出错。

• 清空本地元数据缓存：运行 docker system prune -a --volumes（注意会删所有未使用的镜像、容器、卷）
• 更轻量的做法是只删特定镜像的本地 manifest 缓存：rm -rf ~/.docker/manifests/*（Linux/macOS）或 %USERPROFILE%\.docker\manifests\（Windows）
• 如果用的是私有 registry，确认服务端是否启用了 content-trust 或强制签名；客户端需配 DOCKER_CONTENT_TRUST=1 才能拉取
• 某些 CI 环境中 docker build 带 --pull 也会触发校验，此时建议显式加 --no-cache 避免复用脏 layer

拉取 multi-arch 镜像时总下错平台 layer

Docker 默认根据宿主机 uname -m 自动选 platform，但构建机和目标运行环境架构不一致时（比如在 macOS M1 上拉 x86_64 镜像），容易下到不兼容的 layer，后续 run 失败报 exec format error。

• 强制指定平台：用 --platform linux/amd64 或 --platform linux/arm64，例如 docker pull --platform linux/amd64 python:3.9-slim
• 检查镜像支持哪些平台：运行 docker buildx imagetools inspect python:3.9-slim（需要先启用 buildx）
• CI 脚本里别省略 --platform，尤其当 runner 是通用型云主机（如 GitHub Actions 的 ubuntu-latest）时，不同批次可能调度到不同 CPU 架构节点
• 注意 FROM 指令里的镜像如果没带 platform，Dockerfile 构建时也会继承 host platform，导致 base image layer 不匹配

私有 registry 的 TLS 证书或认证失败导致 pull 中断

错误信息通常是 x509: certificate signed by unknown authority 或 unauthorized: authentication required，但提示位置靠后，容易误判为网络问题。

• 自签名证书必须提前信任：把 CA 证书拷到 /etc/docker/certs.d/:/ca.crt，路径名必须严格匹配 registry 地址（含端口）
• 认证失败时，先用 curl -v -u user:pass https:///v2/ 测试基础连通性和凭据有效性
• 使用 docker login 登录后，凭据存在 ~/.docker/config.json，确认其中 auths 字段 key 是完整 registry 地址（如 "myreg.example.com:5000"，不能少端口）
• Kubernetes 集群内 pod 拉私有镜像失败？那和本地 docker pull 无关，得检查 imagePullSecrets 是否绑定正确

事情说清了就结束。最常被忽略的是：daemon.json 改了不重启 docker、私有 registry 的证书路径名拼错、multi-arch 场景下忘了传 --platform——这三个点占了实际问题的七成以上。