一句报错覆盖三种原因
pull access denied, repository does not exist or may require 'docker login' 这句提示同时覆盖三种情况：镜像或仓库名写错、私有仓库没有登录、账号对目标命名空间没有权限。报错文本完全相同，无法从提示里直接分辨，只能按顺序逐一排除——先核对完整地址，再看登录状态与凭据是否过期，最后确认账号授权范围。
基本信息
| 排查顺序 | 名字拼写 → 登录状态 → 命名空间权限 |
|---|---|
| 登录命令 | docker login 仓库地址 |
| 凭据位置 | ~/.docker/config.json 或系统凭据助手 |
| 成功标志 | 重新拉取后开始逐层下载而不是立即报错 |
典型使用场景
- 新环境初始化：换台机器后忘了登录私有仓库
- 凭据过期：定期轮换令牌后旧凭据失效，报错文本与权限不足相同
- 命名空间权限收紧：账号还在，但对某个仓库的读取权限被收回
- 镜像地址写错：漏了仓库地址前缀或命名空间，落到公共仓库上查找
- 代理或加速器限制：中转服务不转发私有仓库的请求
逐一排除
逐一排除
# 先确认完整地址：从仓库页面复制，避免手打
docker pull registry.example.com/team/app:1.0
# 再确认登录状态与凭据
docker login registry.example.com
docker info | grep -i -A3 'registry'
# 凭据可能过期时先登出再登录
docker logout registry.example.com && docker login registry.example.com
# 对比：公共镜像用完整路径拉取
docker pull library/nginx:1.27细节差异对照
| 现象细节 | 可能原因 | 处理 |
|---|---|---|
| 本地有旧标签但拉新版报错 | 镜像名或命名空间写错 | 从仓库页面复制完整地址后重试 |
| 公共镜像也拉不动 | 网络或镜像加速器限制 | 检查守护进程的镜像源与代理配置 |
| 登录成功仍报同样错误 | 账号无该仓库权限或凭据未生效 | 核对授权并在同终端重新登录 |
| 只有某个仓库失败 | 该命名空间的可见范围受限 | 确认令牌的仓库范围设置 |
多数情况下耗时最多的是名字拼写：先在仓库页面上找到完整地址再重试，比反复检查登录状态更快。
企业环境里镜像加速器通常只服务公共镜像，私有仓库要走直连配置，两者混用会得到与权限问题一模一样的报错。