docker pull 提示 manifest unknown 怎么办？

Q: docker pull 提示 manifest unknown 怎么办？

该提示多表示镜像名、标签写错或远端无此清单。按步骤核对镜像与 tag，并排除客户端版本等因素。

本文适用于：

• Docker 20+ / 24+（低版本可能导致此错误）
• 国内网络环境
• 拉取镜像时遇到 manifest unknown 错误
• 需要验证镜像是否存在或 Docker 版本是否兼容

⚠️ 重要提示

这通常不是网络问题，而是镜像不存在或 Docker 版本过低。也不是「平台尚未同步」——轩辕镜像与原仓库镜像实时同步，不存在同步滞后。

相关常见问题

若拉取时报 manifest unknown，并怀疑是「原仓库有、轩辕镜像还没同步」，请先阅读轩辕镜像是否实时全量同步原仓库的所有镜像？，再按本文步骤排查 Docker 版本与镜像名、标签。

快速诊断流程：

manifest unknown 错误
  ↓
检查 Docker 版本（docker info）
  ↓ 版本 < 20
升级 Docker（主要原因）
  ↓ 版本 >= 20
验证镜像名和标签是否存在

✅ 推荐做法

优先检查 Docker 版本，Docker 20+ 是使用现代镜像仓库的前提。确认版本后，再验证镜像信息是否正确。

当您遇到 manifest unknown 错误时，需要先检查 Docker 版本，然后确认镜像信息是否正确。

错误示例

root@btpanel:~# docker pull docker.xuanyuan.run/nodebb/nodebb:latest Error response from daemon: manifest for docker.xuanyuan.run/nodebb/nodebb:latest not found: manifest unknown: manifest unknown

问题排查步骤

步骤 1：检查 Docker 版本

首先执行 docker info 查看 Server Version：

docker info | grep "Server Version"

如果版本低于 20.x，请先升级 Docker 到 20+ 版本。因为 Docker 不同版本支持的 Registry API 协议不同，低版本客户端在拉取镜像时可能不兼容 v2 接口。

步骤 2：确认镜像信息

如果 Docker 版本已经是 20+，仍然报错，这表示镜像仓库中不存在指定的镜像名或标签（tag）。

请优先到原仓库（如 Docker Hub）核实镜像名与标签是否真实存在。若怀疑是「平台未同步」导致，请先阅读轩辕镜像是否实时全量同步原仓库的所有镜像？。

常见原因包括：

• 镜像名称拼写错误
• 指定的标签（tag）不存在
• 镜像已被删除或下架

解决方案

方案 1：升级 Docker（如果版本过低）

参考 Docker 升级文档：

Linux Docker 安装与升级教程

方案 2：验证镜像信息（如果版本已是最新）

请先在本站镜像仓库页面搜索该镜像，确认镜像名与标签（tag）是否正确。

使用页面提供的完整拉取命令执行 docker pull。

示例

假设网站查询到正确的镜像信息为：

镜像名：elestio/nodebb

标签：v4.4.6

则拉取命令为：

docker pull docker.xuanyuan.run/elestio/nodebb:v4.4.6

💡总结：遇到 manifest unknown 错误时，先排除「平台未同步」（见实时全量同步说明），再检查 Docker 版本，版本过低则升级；版本正常则验证镜像信息是否正确。这样可以快速定位和解决问题。

你可能还会遇到：

本文由「轩辕镜像」维护
轩辕镜像 | 国内 Docker 镜像下载加速
内容基于轩辕镜像真实用户使用与实测整理