Docker Desktop镜像拉取缓慢时，可通过图形界面、手动编辑daemon.json、临时指定源、多源故障转移四种方法配置国内加速镜像源，并用docker info命令验证生效。
如果您在使用 Docker Desktop 时发现镜像拉取缓慢、超时或频繁失败，则很可能是由于默认连接 Docker Hub 官方源受网络限制所致。以下是针对 Windows 和 macOS 系统的多种镜像加速配置方法：
一、通过 Docker Engine 设置界面配置（图形化操作）
该方法无需编辑文件，适合新手用户，所有修改通过 Docker Desktop 图形界面完成，配置后自动写入 daemon.json 并触发服务重启。
1、右键点击系统托盘（Windows）或菜单栏（macOS）中的 Docker 图标，选择 Settings（设置）。
2、在左侧导航栏中点击 Docker Engine 选项卡。
3、在右侧 JSON 配置框中，将原有内容完全替换为以下标准格式（保留已有非 registry-mirrors 字段亦可，但必须确保 registry-mirrors 是合法数组）：
4、粘贴如下示例配置（已包含 2026 年 4 月实测高可用镜像源）：
{ "registry-mirrors": ["https://docker.xuanyuan.me", "https://docker.1ms.run", "https://docker.1panel.live"] }
5、确认 JSON 格式无误（重点检查括号配对、逗号位置、双引号完整），点击右下角 Apply & Restart 按钮。
二、手动编辑 daemon.json 文件（适用于配置同步或脚本化部署）
该方法直接操作配置文件，适用于需批量部署、版本控制或与 CI/CD 流水线集成的场景，支持跨平台复用配置逻辑。
1、定位 daemon.json 文件路径：
Windows：C:\ProgramData\Docker\config\daemon.json
macOS：~/Library/Containers/com.docker.docker/Data/docker-daemon.json
2、使用文本编辑器（如 VS Code、Notepad++ 或 vim）以管理员权限打开该文件。
3、若文件为空或不存在，新建纯文本文件并写入以下最小有效结构：
{ "registry-mirrors": ["https://docker.xuanyuan.me"] }
4、若文件已存在且含其他字段（如 experimental、builder），仅在对象内添加或修改 registry-mirrors 字段，确保其值为字符串数组。
5、保存文件后，在 Docker Desktop 中仍需执行 Apply & Restart 才能使变更生效（Docker Desktop 不会自动监听文件变化）。
三、临时指定镜像源（单次命令生效）
该方法不修改任何全局配置，仅对当前 docker pull 命令生效，适用于验证某镜像源可用性、调试拉取失败原因或在受限环境中快速测试。
1、打开终端（Windows PowerShell / macOS Terminal）。
2、执行带 --registry-mirror 参数的拉取命令，例如：
docker pull nginx --registry-mirror=https://docker.xuanyuan.me
3、注意：此参数必须紧随 docker pull 后、镜像名前；不可用于 docker build 或 docker run。
4、若需同时指定多个临时镜像源，该方式不支持，须改用前两种永久配置方法。
四、配置多镜像源实现故障转移
Docker 客户端按 registry-mirrors 数组顺序尝试请求，首个响应成功的镜像源即被采用；后续请求继续沿用该源，直至其失效后才轮询下一源。合理排序可兼顾速度与容灾能力。
1、将实测最快且稳定性最高的镜像源置于数组首位，例如 https://docker.xuanyuan.me。
2、第二位放置高成功率备用源，例如 https://docker.1ms.run。
3、第三位可配置官方回源地址以保障兜底能力：https://registry-1.docker.io（注意不加 /v2/ 等路径）。
4、最终 registry-mirrors 数组应形如：
["https://docker.xuanyuan.me", "https://docker.1ms.run", "https://registry-1.docker.io"]
5、避免在任一 URL 末尾添加斜杠（/），否则可能导致解析失败。
五、验证配置是否成功加载
配置完成后，Docker Engine 会将 registry-mirrors 内容注入运行时配置。可通过命令行读取当前生效的守护进程配置，确认镜像源已正确载入。
1、在终端中执行命令：docker info --format '{{json .RegistryConfig.Mirrors}}'。
2、预期输出为一个 JSON 数组，内容应与 daemon.json 中 registry-mirrors 字段完全一致。
3、若输出为空数组 [] 或报错 template: :1:8: executing "" at <.registryconfig.mirrors>: can't evaluate field Mirrors，说明配置未生效或 JSON 格式错误。
4、此时请返回步骤一检查 Apply & Restart 是否完成，或使用 https://www.json.cn/ 在线校验 daemon.json 合法性。
