标签拼写错误是拉取失败最常见原因，表现为“manifest not found”或“pull access denied”，需通过docker search、docker hub网页tags页、curl查manifest等方式交叉验证标签真实性，注意大小写、非法字符及latest陷阱。
标签拼写错误是拉取失败中最隐蔽也最常被忽略的原因之一——它不报网络超时，也不提示权限问题，而是直接返回 manifest unknown 或 pull access denied，让人误以为是认证或仓库问题。
确认镜像是否存在且标签真实可用
不要依赖记忆或文档截图，必须通过权威渠道交叉验证：
- 用
docker search <name></name>查看官方/社区是否收录该镜像（注意：部分私有镜像或组织镜像不会出现在 search 结果中） - 打开 Docker Hub 网页（https://www.php.cn/link/641e0c2c35e72adecd8639eb76ebfa18），手动搜索镜像名，进入仓库主页后点击 Tags 标签页，逐行核对你要拉取的标签（如
1.25.3-alpine、v2.0.0-rc1）是否真实存在、是否为 latest 或 active 状态 - 对于私有仓库（如 Harbor、GitLab Container Registry），直接访问其 Web UI，路径通常是
https://<registry>/v2/<project>/<repo>/tags/list</repo></project></registry>，需登录后查看
区分大小写与特殊字符陷阱
Docker 标签严格区分大小写，且不支持空格、中文、下划线开头等非法字符：
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
-
nginx:Alpine≠nginx:alpine（官方镜像只提供小写alpine） -
redis:7.2.0可能有效，但redis:7.2可能已被弃用（Docker Hub 不自动重定向） - 避免使用
latest标签做生产部署——它不是“最新稳定版”，而是最后一次 push 的任意版本，容易因上游覆盖导致行为突变
用 API 直接查 manifest 验证标签有效性
绕过客户端缓存和 CLI 模糊提示，直接向 registry 发起查询：
- 对 Docker Hub 镜像：
curl -I "https://registry.hub.docker.com/v2/library/<name>/manifests/<tag>"</tag></name>，返回200 OK表示标签存在；404 Not Found即确认标签错误 - 对私有 registry：
curl -I -u user:pass "https://<registry>/v2/<namespace>/<repo>/manifests/<tag>"</tag></repo></namespace></registry>，注意需携带有效凭证 - 若返回
401 Unauthorized，说明认证失败，先docker login；若返回404，基本可锁定为标签不存在
检查本地镜像缓存干扰
有时 docker pull 显示“已存在”却无法运行，其实是本地有同名但不同源的镜像（比如从其他 registry 拉过）：
- 执行
docker images | grep <name></name>，观察 REPOSITORY 和 TAG 列是否匹配你预期的 registry 来源 - 用
docker inspect <image-id></image-id>查看RepoDigests字段，确认它指向的是registry-1.docker.io还是私有地址 - 如有混淆，先
docker rmi <image-id></image-id>清理再重新拉取，避免缓存误导判断
