docker pull 报 manifest unknown 怎么解决？tag 找不到的 4 种原因

现象：仓库在，tag 不在

Error response from daemon: manifest for myapp/api:v1.2.0 not found:
manifest unknown: manifest unknown

# 或拉 compose 依赖时
pull access denied（仓库级）
manifest unknown（tag 级）

一行结论：registry 认这个仓库，但找不到你写的那个 tag 对应的 manifest。manifest 是镜像的「目录页」（列出各架构的层信息），tag 指向 manifest——tag 错了或指向的东西不存在，就报这个错。

它和 pull access denied 是兄弟错误：denied 是仓库级问题（不存在/没权限），manifest unknown 是仓库内的 tag 级问题。看到 manifest unknown 说明仓库名多半是对的，盯住 tag 查。

四种原因，按概率排序

1. tag 拼写错误（最常见）

大小写敏感、v1.2 和 1.2 是两个 tag、- 和 _ 看混。最靠谱的核对方法——直接问 registry：

# 列出镜像的所有 tag（Docker Hub）
curl -s "https://hub.docker.com/v2/repositories/library/nginx/tags?page_size=20" | grep -o '"name":"[^"]*"'

# 或查特定 manifest 是否存在
docker manifest inspect myapp/api:v1.2.0

2. latest 陷阱：镜像根本没有 latest tag

docker pull myapp/api 省略 tag 时默认拉 latest。官方镜像基本都维护 latest，但个人/团队镜像经常只 push 过版本号 tag——docker push myapp/api:v1.2.0 不会自动创建 latest。写全 tag 就解决：

docker pull myapp/api:v1.2.0   # ✅ 显式 tag
docker pull myapp/api          # ❌ 拉不存在的 latest

3. 官方镜像改名/下架

镜像生态会变迁：仓库转移（旧仓库归档只读）、更名（如 amazonlinux）、或某版本 tag 被清理。如果你的 Dockerfile/文档是几年前写的，docker manifest inspect 确认一下，然后去 Hub 搜同名镜像看新家。

4. 架构不匹配：manifest 存在但没有你这个平台的

docker pull --platform linux/amd64 myapp/api:v1 时，如果该 tag 只 push 过 arm64 的 manifest，就会报 manifest unknown 或 no matching manifest。M 系列 Mac 用户交叉构建时高发：

# 看这个 tag 都有哪些架构
docker manifest inspect myapp/api:v1 | grep -A2 platform

# 构建时显式指定平台，保证目标架构存在
docker buildx build --platform linux/amd64 -t myapp/api:v1 --push .

exec format error（运行时架构不匹配炸掉）是这个问题没在 pull 阶段暴露的后果——拉的时候就要对齐平台。

排查路线（按顺序两分钟）

# 1. 列出仓库真实存在的 tag
curl -s "https://hub.docker.com/v2/repositories/<user>/<repo>/tags?page_size=50" | grep -o '"name":"[^"]*"'

# 2. tag 对但还报错？查 manifest 与架构
docker manifest inspect <完整镜像名:tag>

# 3. 省略 tag 拉的？补全 tag 再试
docker pull <完整镜像名>:<显式tag>

和相邻错误的分界

| 报错 | 层级 | 方向 | |---|---|---| | manifest unknown / not found | tag 级 | 本篇 | | pull access denied | 仓库级 | pull access denied 排查 | | no matching manifest for platform | 架构级 | 本篇原因 4 | | exec format error | 运行时架构 | 拉取阶段就该对齐平台 |

排查清单

1. tag 拼写逐字符核对（大小写、v 前缀、分隔符）
2. 省略 tag = 拉 latest——这个镜像真的有 latest 吗？
3. Hub Tags 页 / registry API 列出真实 tag 列表
4. 指定了 --platform 的，确认该 tag 有对应架构的 manifest
5. 老 Dockerfile 里的镜像名，确认仓库没改名/下架

本文由 ToolVault 工具匣 提供。相关工具：Dockerfile 生成器、Linux 命令速查。相关阅读：pull access denied 排查、Docker 磁盘爆满清理。访问 首页 查看更多开发者工具。