让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可：
请先完整阅读并严格遵守以下文档中的全部规则与要求：
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。 若 AI 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
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 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理