Docker 镜像源配置详解--解决拉取失败问题

一、问题根因分析

Docker 镜像拉取流程

默认情况下，Docker 会从 Docker Hub（docker.io）拉取镜像。由于 Docker Hub 在国内访问速度不稳定，很多教程会教大家配置国内镜像加速器（Registry Mirror）。

你的 Docker
  → 镜像源 A（你配置的 registry-mirrors）
  → 镜像源 A 去 docker.io 拉取并缓存
  → 返回给你

二、正确的镜像源配置方法

2.1打开 Docker Engine 配置文件

Windows / macOS（Docker Desktop）：

1. 右键点击任务栏右下角的 Docker 图标
2. 选择 Settings（设置）
3. 左侧菜单点击 Docker Engine
4. 右侧会显示一个 JSON 编辑器

Linux（直接编辑文件）：

bash

sudo vi /etc/docker/daemon.json

2.2推荐的国内镜像源列表

⚠️ 阿里云镜像源需要个人专属地址，获取方式：
登录 cr.console.aliyun.com → 左侧「镜像加速器」→ 复制你的专属地址

2.3完整配置示例（Docker Desktop）

在 Docker Engine 的 JSON 编辑器中，填入以下内容（已有配置请合并，不要直接覆盖）：

json

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "features": {
    "buildkit": true
  },
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://hub-mirror.c.163.com"
  ],
  "insecure-registries": []
}

2.4保存并重启

1. 点击右下角 Apply & Restart
2. 等待 Docker 重启完成（任务栏图标变绿，或 Docker Desktop 显示 Engine running）
3. 重启过程约 10~30 秒

三、验证配置是否生效

3.1查看当前生效的镜像源

bash

docker info

在输出中找到这一段：

Registry Mirrors:
  https://docker.m.daocloud.io/
  https://dockerproxy.com/
  https://hub-mirror.c.163.com/

能看到你配置的地址，说明生效了 ✅

3.2实际拉取测试

bash

# 拉一个常见镜像测试速度
docker pull python:3.12-slim

如果能在 1~3 分钟内完成，说明镜像加速正常工作。

四、常见问题 FAQ

Q1：配置了镜像源还是很慢？

可能原因：

• 镜像源本身不稳定，换一个试试
• 镜像源不支持你要拉的具体镜像（有些镜像源只缓存热门镜像）
• 你的网络本身有问题（尝试 ping docker.m.daocloud.io）

解决方法： 多配几个镜像源，Docker 会按顺序尝试：

json

"registry-mirrors": [
  "https://docker.m.daocloud.io",
  "https://dockerproxy.com",
  "https://hub-mirror.c.163.com",
  "https://mirror.baidubce.com"
]

Q2：公司网络有 HTTP 代理，怎么配置？

在 Docker Desktop 的 Resources → Proxies 里配置：

HTTP Proxy:  http://你的代理地址:端口
HTTPS Proxy: http://你的代理地址:端口

或者在 ~/.docker/config.json 里配置：

json

{
  "proxies": {
    "default": {
      "httpProxy": "http://127.0.0.1:7890",
      "httpsProxy": "http://127.0.0.1:7890",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

Q3：daemon.json 配置错了，Docker 启动不了？

Linux 上修复：

bash

# 还原配置文件
sudo vi /etc/docker/daemon.json
# 删掉错误内容，恢复为 {} 后保存
sudo systemctl restart docker

Windows / macOS 修复：

1. 右键 Docker 图标 → Troubleshoot → Reset to factory defaults
2. 这会重置所有配置，但能解决配置错误导致的启动失败

五、完整的 daemon.json 参考模板

json

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://hub-mirror.c.163.com"
  ],
  "insecure-registries": [],
  "experimental": false,
  "features": {
    "buildkit": true
  },
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "storage-driver": "overlay2"
}