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/<your-registry-domain>:<port>/ca.crt</port></your-registry-domain>，路径名必须严格匹配 registry 地址（含端口） - 认证失败时，先用
curl -v -u user:pass https://<your-registry>/v2/</your-registry>测试基础连通性和凭据有效性 - 使用
docker login <your-registry></your-registry>登录后，凭据存在~/.docker/config.json，确认其中auths字段 key 是完整 registry 地址（如"myreg.example.com:5000"，不能少端口） - Kubernetes 集群内 pod 拉私有镜像失败？那和本地
docker pull无关，得检查imagePullSecrets是否绑定正确
daemon.json 改了不重启 docker、私有 registry 的证书路径名拼错、multi-arch 场景下忘了传 --platform——这三个点占了实际问题的七成以上。 
