在使用 Docker 时，我们经常会通过 docker pull 命令获取镜像，但有时会遇到 pull 不下来的问题。本文总结了常见的失败原因及对应的解决方法，适用于初学者和开发者查错参考。
一、常见错误现象
net/http: request canceled while waiting for connection
Error response from daemon: Get https://registry-1.docker.io/v2/: net/http: TLS handshake timeout
connection refused
unauthorized: authentication required
denied: requested access to the resource is denied
Error response from daemon: manifest for xxx not found
二、解决方法汇总
1. 网络连接问题
最常见的原因是网络连接 Docker Hub 不稳定或被墙：
✅ 解决方案：
-
检查 DNS 设置，推荐使用阿里 DNS（223.5.5.5）或 Google DNS（8.8.8.8）：
编辑 /etc/resolv.conf，添加：
nameserver 8.8.8.8
nameserver 223.5.5.5
-
使用国内镜像源，例如：
编辑 /etc/docker/daemon.json：
{
"registry-mirrors": ["https://registry.docker-cn.com", "https://hub-mirror.c.163.com"]
}
重启 Docker：
sudo systemctl daemon-reexec
sudo systemctl restart docker
2. 镜像名称错误或不存在
比如打错镜像名、版本号错误等。
✅ 解决方案：
-
确认镜像名称拼写正确，例如：
docker pull nginx:latest
-
建议先通过 Docker Hub 网站或命令查找可用 tag：
docker search nginx
3. 权限问题（unauthorized）
有些镜像仓库（如私有仓库）需要登录授权。
✅ 解决方案：
使用 docker login 登录：
docker login
然后重新 pull。
4. 镜像 tag 不存在（manifest not found）
比如使用了错误的 tag。
✅ 解决方案：
-
先查看支持的 tag 列表：
docker pull image-name
或直接访问： https://hub.docker.com/
5. 代理问题（公司网络）
某些公司网络需要设置代理才能正常连接 Docker Hub。
✅ 解决方案：
配置 Docker 的代理：
编辑 /etc/systemd/system/docker.service.d/http-proxy.conf：
[Service]
Environment="HTTP_PROXY=http://your-proxy.com:port/"
Environment="HTTPS_PROXY=http://your-proxy.com:port/"
重启 Docker：
sudo systemctl daemon-reexec
sudo systemctl restart docker
6、无法在线 pull 镜像？试试离线下载镜像并导入
当服务器无法访问外网、Docker Hub 被墙或出于内网环境部署需求，可以选择离线下载 Docker 镜像，然后导入到目标服务器中使用。
✅ 离线导入镜像的完整流程如下：
Step 1：在可联网的机器上下载镜像
docker pull nginx:1.25
下载完成后，将镜像保存为 tar 文件：
docker save -o nginx_1.25.tar nginx:1.25
Step 2：将 tar 包复制到目标服务器
可以使用 scp、U 盘、内网传输等方式将 nginx_1.25.tar 拷贝至目标服务器。
scp nginx_1.25.tar user@192.168.x.x:/home/user/
Step 3：在目标服务器上导入镜像
docker load -i nginx_1.25.tar
验证镜像是否导入成功：
docker images
输出结果应包含 nginx:1.25
📝 提示：
-
离线导入支持多个镜像合并保存，例如：
docker save -o images.tar nginx:1.25 redis:7.2
-
同理，导入后也可用 docker tag 重命名或上传至私有仓库。
三、建议
-
遇到 pull 问题时，先执行 docker info 查看当前配置。
-
多用官方镜像，避免使用 tag 为 latest 造成不可控更新。
-
如果长期开发，建议搭建本地 Harbor 仓库，提高效率。
