执行 docker pull 后看到 manifest unknown，首先要确认请求的仓库、标签或摘要在目标镜像仓库中是否存在。它表示仓库没有返回所请求的清单，不能只凭这条报错判断是 VPS 网络故障。
先保留完整镜像名和报错原文。 尤其要看镜像来自 Docker Hub 还是私有仓库，以及命令中是否省略了标签。
记录实际拉取的引用
docker pull example/app:1.2.3把示例名替换为实际引用。Docker 的拉取语法是 NAME[:TAG|@DIGEST]；标签、仓库路径和仓库主机名任一处写错，都可能指向另一份清单。 从部署文件复制完整镜像名，与发布方给出的引用逐字比较。
检查标签是否真的存在
打开镜像发布方的官方仓库页面或私有仓库管理界面，核对标签拼写、大小写和版本。不要猜测 latest 一定存在；省略标签时，Docker 会请求默认标签，但发布方未必提供它。
可用 docker manifest inspect example/app:1.2.3 查看某个引用的清单。该命令在 Docker 文档中仍标为实验功能，它的失败不应单独作为仓库不存在的证据；应结合仓库页面或 Registry API 回应判断。
区分仓库路径与权限问题
私有仓库的路径可能包括主机名、命名空间和项目名。先核对登录目标，再检查凭据是否有该仓库的 pull 权限。某些仓库为避免泄露私有项目，会把无权访问的引用表现为类似不存在的错误。
不要把仓库密码写进命令行参数、截图或文章。 使用组织规定的安全登录方式，并让仓库管理员核对授权范围。
检查架构与清单列表
如果标签存在，却只有别的 CPU 架构镜像，报错文本往往会指向 no matching manifest for linux/...。这与 manifest unknown 不是同一判断。先运行 docker info --format '{{.Architecture}}' 确认宿主架构，再查看发布方支持的平台。
不要为绕过架构限制而随意指定 --platform。 跨架构运行可能依赖模拟器，性能和兼容性需要另行验证。
修正部署文件中的镜像名
找到 Compose 文件或部署清单的 image: 项，改为发布方确认存在的完整引用。生产部署建议固定明确版本或摘要，避免未审查的标签漂移。变更前记录旧值，按现有发布流程重启受影响服务。
需要在隔离环境复现镜像引用时，可使用 萤光云 或 LightNode 的测试实例；不要把生产仓库凭据复制进去。
再次拉取并核对摘要
docker pull example/app:1.2.3
docker image inspect example/app:1.2.3 --format '{{json .RepoDigests}}'验收要同时确认拉取成功、来源仓库正确和摘要符合发布记录。 若仍失败，保留完整响应与仓库端日志，避免反复更换标签掩盖发布流程问题。
FAQ
manifest unknown 就是网络断了吗？不是。它更直接指向所请求清单无法取得；网络错误一般会出现连接、DNS 或 TLS 相关信息。
可以直接改用 latest 吗？先确认发布方确实发布该标签，并评估版本变化。生产环境不宜盲目改成浮动标签。
温馨提示
镜像引用是部署输入的一部分。 修复后把正确标签或摘要同步到配置仓库，并记录发布方与更新时间，防止下一次部署又拉取旧引用。
