Docker Desktop镜像源切换与加速设置指南

国内使用 Docker Desktop 拉取镜像时，常遇到卡在 0%、超时失败、速度不足 100 KB/s 等问题。根本原因并非本地网速或机器配置，而是默认连接到境外的 registry-1.docker.io。配置一个可用的镜像源后，拉取 nginx 镜像的时间能从 5 分钟压缩到 12 秒以内。

通过 Docker Desktop 图形界面配置（推荐新手）

第一步，右键点击任务栏（Windows）或菜单栏（macOS）中的 Docker 图标，选择 Settings（设置）。

第二步，在左侧导航栏找到 Docker Engine 选项卡，右侧会显示一个 JSON 格式的配置编辑框。

第三步，将以下内容直接粘贴进去。注意：必须完全覆盖原有内容，不能只修改部分字段：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://hub-mirror.c.163.com"
  ]
}

第四步，检查 JSON 格式是否合法：确保左右大括号配对、每个 URL 使用英文双引号包裹、数组末尾无多余逗号。若格式有误，Docker 启动会直接失败，且不会自动恢复。

第五步，点击右下角的 Apply & Restart，等待 Docker Engine 重启（通常 15–25 秒）。右下角状态灯变绿即表示配置生效。

手动修改 daemon.json 文件（适合批量部署或脚本化）

方法一：定位并编辑配置文件

Windows 路径：C:\ProgramData\Docker\config\daemon.json；macOS 路径：~/Library/Containers/com.docker.docker/Data/docker-daemon.json。

使用 VS Code 或记事本（以管理员身份运行）打开。如果文件不存在或为空，新建一个纯文本文件，写入最小有效结构：

{
  "registry-mirrors": ["https://mirror.baidubce.com"]
}

方法二：保留已有配置时的修改要点

如果原文件中有 "experimental": true 或 "builder" 等字段，registry-mirrors 必须作为顶层键出现，且值必须是字符串数组，不能嵌套在其他对象中。添加完成后，务必确认逗号位置正确——放错一个逗号会导致配置文件失效。

方法三：使配置生效的关键动作

保存文件后，Docker Desktop 不会自动读取新配置——仍需进入 Settings → Docker Engine，点击 Apply & Restart 才能激活。跳过这一步等同于未配置。

临时指定镜像源（单次命令验证用）

打开终端（PowerShell 或 Terminal），执行带 --registry-mirror 参数的拉取命令：

docker pull hello-world --registry-mirror https://docker.1panel.live

该方式不修改任何配置，仅对当前操作生效。适合快速确认某个镜像源是否可用，或在受限环境下临时绕过全局策略。

注意：URL 后面不要添加多余路径，例如 https://docker.1panel.live/v2/——添加后会导致认证失败。

验证镜像源是否生效

第一步：查看当前配置

docker info | findstr "Registry Mirrors"

第二步：查看输出结果

如果返回的行中包含你配置的域名（如 docker.1ms.run），说明 registry-mirrors 已成功加载。如果返回空或显示 Registry Mirrors: ，则表示配置未生效或 JSON 解析出错。

第三步：实测拉取

执行 docker pull busybox，观察下载速度能否稳定在 2 MB/s 以上，且无 context deadline exceeded 报错。能顺利拉取即表示配置正确。