docker pull 提示 no matching manifest 怎么办？
本文适用于：
- • 拉取时出现
no matching manifest for linux/amd64、linux/arm64或linux/arm64/v8等提示 - • 本机是 x86 却拉了仅含 ARM 的镜像，或本机是 ARM（Apple M 系列、ARM 云主机、树莓派等）却拉了仅含 amd64 的镜像
- • 需要区分本错误与「manifest unknown」（镜像名或 tag 不存在）
先搞清一点：这通常不是「镜像源坏了」
no matching manifest for linux/amd64 表示：清单里没有当前环境需要的 amd64 条目——常见是镜像只提供 ARM（例如部分 arm64v8/... 命名空间），而你的机器是 x86。
反向同理：若提示 no matching manifest for linux/arm64 或 linux/arm64/v8，多表示镜像未提供 ARM64 层，而你的设备正是 ARM64；同样属于架构与清单不匹配，与镜像加速服务本身无关。
下面分步说明：两种典型报错长什么样、按场景怎么处理、ARM 离线时如何在 x86 上准备 arm64 镜像再搬过去。
错误示例（两种常见方向）
情况 A：x86（amd64）本机，镜像只有 ARM
情况 B：ARM64 本机，镜像未提供 ARM 层（真实案例）
在 Apple M 系列、部分 ARM 云服务器或树莓派等 ARM64 环境下拉取某标签时，若作者只构建了 amd64，会出现类似：
linux/arm64/v8 与 linux/arm64 在此类报错里含义接近，都表示 Docker 在为 ARM64 设备解析清单时，找不到对应平台的条目。
常见解决办法（按场景选）
1）你本来就在 x86（amd64）上跑容器
- 改用提供 amd64（或多架构）的镜像。例如需要 Nginx 时，可优先使用官方多架构镜像
nginx，而不是仅面向 ARM 命名空间的镜像。 - 在镜像说明或标签页确认是否包含
amd64。更多拉取指定架构的写法见：如何拉取指定 CPU 架构的镜像。
2）你的设备是 ARM64，但镜像没有 arm64 清单（如上「情况 B」）
说明该标签在仓库中很可能只发布了 amd64（或缺少你当前平台需要的变体），与是否走轩辕镜像加速无直接关系。可依次考虑：
- 查多架构：在镜像仓库页或文档中确认是否存在 ARM64 构建、是否有别的 tag 含 arm64（见 指定架构拉取）。
- 换运行环境：若业务允许，在 x86 / amd64 主机或云服务器上运行该镜像。
- 联系作者：请维护者发布含
linux/arm64的 manifest 或提供 ARM 构建说明。
ARM 不能联网：能在 x86 上先拉 arm64 再搬到 ARM 吗？
可以。思路是：在能联网的 x86 电脑上，用平台参数显式拉取 ARM 架构镜像，打成文件，再拷贝到离线 ARM 主机上导入。
拉取示例（请把镜像名换成你实际需要的仓库与标签）：
拉取成功后，镜像内容即为 linux/arm64，可与 ARM 设备上的 Docker 兼容。
打包与离线导入（docker save / docker load）的完整步骤与注意点，见专题：机器不能直连外网时，怎么用 docker save / load 迁镜像？
小结：no matching manifest …（无论是 amd64 还是 arm64/v8）优先按 CPU 架构与镜像清单是否一致 排查，而不是先怀疑镜像源。 若仍看到 manifest unknown，多半是镜像名或 tag 错误，请对照manifest unknown 专题排查。
你可能还会遇到：
- • docker pull 提示 manifest unknown 怎么办？
- • Docker pull 时 HTTPS / TLS 证书验证失败怎么办？
- • Docker pull 时 DNS 解析超时或连不上仓库怎么办？
- • Docker 拉取出现 410 Gone 怎么办？
- • 出现 402 或「流量用尽」提示怎么办？
- • Docker 拉取提示 UNAUTHORIZED（401）怎么办？
- • 遇到 429 Too Many Requests（请求太频繁）怎么办？
- • docker login 提示 Cannot autolaunch D-Bus，还算登录成功吗？
- • 为什么会出现「单层超过 20GB」或 413，无法加速拉取？
本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理